Add OsRandom::try_clone for fallible duplication of the underlying
/dev/urandom file handle, and implement Clone as the infallible convenience
form. This gives independent call sites their own OsRandom values without
adding interior mutability or shared buffering to the core type.
The fallible method is documented as the preferred API when callers need to
handle a failed file-handle duplication. Clone mirrors Default by panicking only
for the convenience path.
Document both cloning forms with doctested examples and add a runnable clone
example that uses independent handles for IDs and string helpers.
Test Plan:
- cargo test
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo +nightly fmt
Refs: IDEAS.md ergonomics backlog
Add token, hex, and pin helpers for the common ASCII string formats already
represented by the crate's built-in charsets. These methods keep frequent use
cases concise while continuing to route through string_from, so callers still
get the same uniform per-character sampling behavior.
Avoid adding a password preset in this change. Password generation implies
policy choices around symbols, ambiguous characters, and service-specific
constraints, while these presets are direct names for existing alphabets.
Document every preset with doctested examples and add a runnable presets
example. Update the demo to show both presets and custom string generation.
Test Plan:
- cargo test
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo +nightly fmt
Refs: IDEAS.md ergonomics backlog
Add OsRandom::choose for callers that want a uniformly selected reference from
any non-empty slice. This covers the common generic selection use case without
adding collection algorithms such as shuffle.
Keep OsRandom::pick as the byte-oriented helper by delegating it through
choose. This preserves the existing public API while sharing the usize range
sampler and avoiding the old u32 length limit.
Document choose, pick, and string_from with working examples, and add a choices
example that demonstrates generic slice selection alongside byte alphabets.
Test Plan:
- cargo test
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo +nightly fmt
Refs: IDEAS.md ergonomics backlog
Expand range sampling from the original u32-only helper to all primitive
integer widths. The new gen_range_<int> methods cover 0..n sampling, while
matching gen_range_<int>_in methods accept standard RangeBounds forms such as
exclusive, inclusive, open-ended, and full-width ranges.
Use rejection sampling against the matching primitive reader for each integer
width. That keeps modulo bias out of the public helpers without introducing a
general RNG trait or depending on rand. Full-width ranges fall back directly to
the primitive reader because their span cannot be represented in the same
integer type.
Document the generated APIs with doctested examples and add a ranges example
that demonstrates unsigned, signed, usize, and full-width sampling.
Test Plan:
- cargo test
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo +nightly fmt
Refs: IDEAS.md ergonomics backlog
Add OsRandom::fill_bytes so callers can fill a byte slice without importing
std::io::Read. This keeps the common raw-byte use case close to the rest of
the crate's typed convenience API while still forwarding to the same
/dev/urandom handle.
Implement Default for OsRandom as the infallible convenience constructor. The
fallible OsRandom::try_new API remains the right choice when the caller wants
to handle an unavailable operating-system randomness source explicitly.
Document the public constructors and byte-fill helper with working examples,
and add a runnable bytes example for the top-level workflow.
Test Plan:
- cargo test
- cargo clippy
- cargo clippy --benches
- cargo clippy --tests
- cargo +nightly fmt
Refs: IDEAS.md ergonomics backlog
Adds examples/demo.rs so users can quickly see the crate in action via
`cargo run --example demo` without writing any glue code first.
The example exercises the three main surface areas of the crate:
- the typed primitive readers (get_u8, get_u32, get_u64, get_i32) to
show that every integer width is covered and that signed values come
out signed;
- gen_range_u32 in a dice-roll idiom (+ 1 to shift 0..6 into 1..6),
which doubles as a hint that the helper returns a half-open range;
- string_from with three of the prebuilt charsets (ALPHANUMERIC for a
generic token, HEX_LOWER for a 128-bit-style hex string, DIGITS for
a numeric PIN), demonstrating the typical "generate me a random
identifier" use case the crate is designed for.
No library code changes; this is purely an onboarding aid. Picked an
example over expanding the crate-level rustdoc because a runnable
binary is easier to copy-paste-modify than a doctest, and Cargo's
examples/ convention is the idiomatic place for this.
Test Plan:
- `cargo run --example demo` prints one line per demonstrated API and
exits 0.
- `cargo clippy --all-targets` is clean.
ddidderr
