From 631dc1938c59904e50e42a6f3eebaa34bb98ece5 Mon Sep 17 00:00:00 2001 From: ddidderr Date: Tue, 28 Apr 2026 20:10:06 +0200 Subject: [PATCH] docs: update ergonomics backlog Refresh IDEAS.md after the ergonomic API pass so the backlog no longer lists implemented items as open work. Split the remaining ideas into deferred and still-open groups to record which omissions were deliberate crate-scope choices. This keeps the project notes aligned with the public API and captures the reasoning for not adding globals, shuffle, or password presets yet. Test Plan: - Not run; documentation-only change. Refs: IDEAS.md ergonomics backlog --- IDEAS.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/IDEAS.md b/IDEAS.md index f1f2be2..3bcec56 100644 --- a/IDEAS.md +++ b/IDEAS.md @@ -1,15 +1,27 @@ # Ergonomy ideas -- `Default` / `thread_local` global: `ez_urandom::random_u64()` without - constructing or threading an `OsRandom`. -- `gen_range` for all int widths (currently only `u32`) plus a `Range` / - `RangeInclusive` overload. -- `fill_bytes(&mut [u8])` convenience so callers don't need to import - `io::Read`. +- Implemented: + - `Default` for infallible convenience construction. + - `fill_bytes(&mut [u8])` convenience so callers don't need to import + `io::Read`. + - `gen_range_` for all primitive integer widths. + - `gen_range__in` for standard `RangeBounds` forms, including `Range` + and `RangeInclusive`. + - `choose(&[T]) -> &T` for generic slice selection. + - `Clone` plus fallible `try_clone()` so multiple call sites can own separate + handles without adding interior mutability. + - Presets for direct alphabet names: `OsRandom::token(len)`, `::hex(len)`, + and `::pin(len)`. + +- Deferred to keep the crate small: + - `thread_local` global helpers like `ez_urandom::random_u64()` without + constructing or threading an `OsRandom`. + - `shuffle(&mut [T])`; `choose` covers the smaller selection use case without + growing into collection algorithms. + - `OsRandom::password(len)`; password generation needs policy decisions about + symbols, ambiguous characters, and service-specific constraints. + +- Still open for later consideration: - `bool()` / `f64()` (unit interval) helpers. -- `shuffle(&mut [T])` and `choose(&[T]) -> &T` — generic, not just bytes. - Accept a `&str` alphabet directly (not just `&[u8]`) and drop the ASCII assert by iterating `chars()`. -- Loosen `&mut self` to `&self` via interior buffering, or impl `Clone`, so - multiple call sites don't fight the borrow checker. -- Builder / presets: `OsRandom::password(len)`, `::hex(len)`, `::token(len)`.