From d618bd7cc96f88e2b71f790d3a8f75a7cca4956d Mon Sep 17 00:00:00 2001 From: ddidderr Date: Tue, 28 Apr 2026 19:38:44 +0200 Subject: [PATCH] docs: add IDEAS.md with ergonomy backlog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture a short backlog of ergonomy improvements for the public API so the ideas don't get lost between sessions. This is a planning document only — no code changes, and nothing here is committed to as a roadmap. Items recorded: - Thread-local global helpers (e.g. `random_u64()`) to avoid threading an `OsRandom` through call sites for one-off uses. - `gen_range` for all integer widths and `Range`/`RangeInclusive` overloads; today only `gen_range_u32` exists. - `fill_bytes(&mut [u8])` so callers don't need to bring `io::Read` into scope just to fill a buffer. - `bool()` and `f64()` (unit interval) helpers. - Generic `shuffle(&mut [T])` and `choose(&[T]) -> &T`, not just byte slices. - Accept `&str` alphabets directly and drop the ASCII assert by iterating `chars()` instead of bytes. - Loosen `&mut self` to `&self` (interior buffering) or impl `Clone`, so multiple call sites can share a handle without borrow-checker friction. - Preset constructors: `OsRandom::password(len)`, `::hex(len)`, `::token(len)`. --- IDEAS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 IDEAS.md diff --git a/IDEAS.md b/IDEAS.md new file mode 100644 index 0000000..f1f2be2 --- /dev/null +++ b/IDEAS.md @@ -0,0 +1,15 @@ +# 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`. +- `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)`.