mod-rand 1.0.0

What it is

mod-rand is a tiered randomness library for Rust. Three concrete random sources, each chosen to be excellent for one threat model; every operation you'd reach for — bounded integer ranges, byte buffers, hex tokens, random or process-unique strings, shuffles, samples, and weighted choice — exposed at the appropriate tier.

Zero runtime dependencies. MSRV 1.75. API locked under SemVer for the entire 1.x line.

use mod_rand::tier1::Xoshiro256;
use mod_rand::{tier2, tier3};

// Tier 1 — fast deterministic PRNG (xoshiro256**). Reproducible from a seed.
let mut rng = Xoshiro256::seed_from_u64(42);
let n: u64       = rng.next_u64();
let pct: u32     = rng.gen_range_u32(0..100);
let token: String = rng.gen_alphanumeric(16);

// Tier 2 — process-unique values. Tempdir names, request IDs.
let id: String = tier2::unique_name(12);

// Tier 3 — OS-backed cryptographic random. Tokens, keys, session IDs.
let secret: String = tier3::random_hex(32)?;
# Ok::<(), std::io::Error>(())

What it covers

Every category of randomness operation that's in scope, at every tier where it makes sense.

Tier 1 is no_std-compatible for everything that doesn't require allocation. Tier 2 and Tier 3 require std (default feature).

The three tiers

Pick by threat model, not by speed.

If the answer to the third question is "yes" — even maybe — use Tier 3.

Bounded ranges — every integer width

Every tier exposes gen_range_* / range_* / random_range_* methods using Rust's range syntax. .. is half-open, ..= is inclusive; the caller's choice is the contract. All bounded methods use Daniel Lemire's "Nearly Divisionless" rejection sampling, so output is uniformly distributed — no modulo bias.

Widths covered: u8, u16, u32, u64, u128, usize, and the signed counterparts.

use mod_rand::tier1::Xoshiro256;
use mod_rand::{tier2, tier3};

let mut rng = Xoshiro256::seed_from_u64(42);

let byte: u8   = rng.gen_range_inclusive_u8(0..=255);
let pct:  u32  = rng.gen_range_u32(0..100);
let big:  u128 = rng.gen_range_u128(0..(u128::MAX / 2));
let die:  u32  = rng.gen_range_inclusive_u32(1..=6);   // classic d6

let id     = tier2::range_inclusive_u32(1..=1_000);
let secret = tier3::random_range_inclusive_u64(0..=u64::MAX)?;
# Ok::<(), std::io::Error>(())

The 128-bit ranges generalise Lemire's algorithm to a 256-bit intermediate via two u64 draws; the full-width inclusive 0..=u128::MAX is special-cased to a raw 128-bit reinterpret.

String generation

Custom charset, or a pick from the standard ones in mod_rand::charsets.

use mod_rand::tier1::Xoshiro256;
use mod_rand::{charsets, tier2, tier3};

let mut rng = Xoshiro256::seed_from_u64(1);

// Tier 1 — deterministic from the seed.
let id    = rng.gen_alphanumeric(16);
let hex   = rng.gen_hex(32);
let pin   = rng.gen_numeric(6);

// Custom charset — pick from charsets:: or supply your own &[u8].
let url   = rng.gen_string(24, charsets::URL_SAFE);
let coin  = rng.gen_string(20, charsets::BASE58);

// Tier 2 — `unique_*` guarantees per-call distinctness;
// `random_*` guarantees a uniform distribution. Both ship.
let name  = tier2::unique_name(12);             // distinct across calls
let token = tier2::random_alphanumeric(16);     // uniform distribution

// Tier 3 — cryptographic.
let key   = tier3::random_alphanumeric(32)?;
# Ok::<(), std::io::Error>(())

Charset constants in mod_rand::charsets: ALPHANUMERIC, ALPHA, ALPHA_LOWER, ALPHA_UPPER, NUMERIC, HEX_LOWER, HEX_UPPER, URL_SAFE (RFC 4648 §5), BASE58 (Bitcoin alphabet), BASE64 (RFC 4648 §4). Custom charsets are accepted as &[u8]; non-ASCII charsets are rejected (panic on Tier 1 / Tier 2; InvalidInput on Tier 3) so the returned String is always valid UTF-8.

Collection operations

Fisher-Yates shuffle, sample-without-replacement, and weighted choice. Available on Tier 1 (deterministic, reproducible) and Tier 3 shuffle (cryptographic).

use mod_rand::tier1::Xoshiro256;
use mod_rand::tier3;

let mut rng = Xoshiro256::seed_from_u64(1);

// Shuffle in place. Uniform over all n! permutations.
let mut hand: Vec<u8> = (0..52).collect();
rng.shuffle(&mut hand);

// Sample k references without replacement, in source-slice order.
let pool: Vec<&str> = vec!["alice", "bob", "carol", "dave", "erin"];
let chosen: Vec<&&str> = rng.sample(&pool, 2);

// Weighted choice over a probability vector.
let items   = ["common", "uncommon", "rare", "epic"];
let weights = [70.0, 20.0, 8.0, 2.0];
let drop    = rng.weighted_choice(&items, &weights).unwrap();

// Cryptographic shuffle — every permutation drawn from the OS CSPRNG.
let mut deck: Vec<u8> = (0..52).collect();
tier3::shuffle(&mut deck)?;
# Ok::<(), std::io::Error>(())

Performance

Measured on a Ryzen 9 9950X3D, Windows 11 (cargo bench):

Tier 1 — xoshiro256** (target ~1 ns/u64)

Tier 2 — process-unique (dominated by SystemTime::now())

Tier 3 — OS CSPRNG (Windows / BCryptGenRandom)

Tier 1 beats its 1 ns/u64 target. Linux / macOS Tier 3 numbers are kernel-dependent; expect 100–500 ns per call on commodity hardware.

Why this library exists

• Zero dependencies. No rand, no getrandom crate, no libc. Just std. Tier 1 works in no_std.
• Explicit threat model. You pick the tier; you know what guarantees you're getting.
• Lower MSRV than the alternatives. 1.75. Many random crates in the ecosystem require 1.85+.
• Determinism contract on Tier 1. Locked byte-for-byte under SemVer for the entire 1.x line — see docs/STABILITY.md.
• One library, three tiers, every operation. Numbers, bytes, strings, tokens, shuffle, sample, weighted choice. You don't need rand + rand_distr + fastrand + a hand-rolled crypto random.

How it compares

Honest, side-by-side. The full discussion (including non-strengths) is in docs/COMPARISON.md.

Use mod-rand when its tier model fits and you want zero deps + a locked API. Reach for rand if you need named distributions or generic-trait ecosystem interop.

Feature flags

[dependencies]
mod-rand = { version = "1.0", default-features = false }   # tier1 only, no_std
mod-rand = { version = "1.0", features = ["tier2"] }       # + tier2
mod-rand = "1.0"                                             # all three tiers (default)

Default features: ["std", "tier2", "tier3"].

Documentation

• docs/API.md — hand-written API reference, tier by tier.
• docs/STABILITY.md — SemVer policy, determinism contract, deprecation rules.
• docs/COMPARISON.md — side-by-side with rand, fastrand, nanorand.
• docs/API-FREEZE-AUDIT.md — full manifest of every 1.0 public symbol.
• CHANGELOG.md — release history.

Minimum supported Rust version

1.75 — pinned in Cargo.toml, verified by CI on every change. An MSRV bump is a minor-version bump minimum.

License

Apache-2.0. See LICENSE.