Crate vrd 

Minimum supported Rust version: 1.70.0

Versatile Random Distributions (VRD)

A lightweight, no_std-friendly random number generator backed by Xoshiro256++, with optional Mersenne Twister (MT19937) support.

Features

• High performance: Xoshiro256++ default — 32-byte state, period 2^256 - 1, SplitMix64 seed whitening.
• Legacy reproducibility: opt-in MT19937 backend. Random::new_mersenne_twister() requires alloc + std; Random::new_mersenne_twister_with_seed(u32) is alloc-only.
• no_std ready: pure-core build with default-features = false, validated on thumbv7em-none-eabihf (Cortex-M) and wasm32-unknown-unknown (WebAssembly) in CI.
• Unbiased sampling: int, uint, random_range, and the public bounded use Lemire’s nearly-divisionless method.
• Bit-precise floats: float() carries 24 mantissa bits, double() carries 53. Always [0.0, 1.0).
• Distributions: uniform(low, high), normal, exponential, poisson — std-free via libm.
• Convenience helpers: iter_u32 / iter_u64 / iter_bytes iterator adapters; uuid_v4_bytes (no_std) and uuid_v4 (alloc); hex_token and base64_token for URL-safe random tokens.
• rand 0.10 traits: TryRng, the blanket-implemented Rng, and SeedableRng.

Quickstart

use vrd::Random;

let mut rng = Random::from_u64_seed(42);   // deterministic, allocation-free

let n: u32 = rng.rand();                    // any u32
let _      = rng.u64();                     // any u64
let _      = rng.int(1, 100);               // i32 in [1, 100], uniform
let _      = rng.double();                  // f64 in [0.0, 1.0)
let _      = rng.bool(0.5);                 // 50/50 coin
assert!(n > 0 || n == 0);

Use Random::new() for entropy-seeded randomness on std targets, Random::from_seed() / Random::from_u64_seed() for deterministic / no_std use, and Random::new_mersenne_twister() / Random::new_mersenne_twister_with_seed() when you need bit-for-bit MT19937 reproducibility against existing test vectors.

Not a CSPRNG

Random is not cryptographically secure. For credentials, session IDs, or anything an attacker would benefit from predicting, use rand::rngs::OsRng or getrandom. A built-in ChaCha20-based CSPRNG backend is tracked in issue #90.

Re-exports

pub use mersenne_twister::MersenneTwisterConfig;

pub use mersenne_twister::MersenneTwisterError;

pub use mersenne_twister::MersenneTwisterParams;

pub use random::FloatExt;

pub use random::Random;

pub use random::RngBackend;

Modules

macros

Convenience macros. Convenience macros over the crate::Random facade.

mersenne_twister

Mersenne Twister configuration and constants. Mersenne Twister (MT19937) configuration types.

random

The core Random facade. The Random facade and the enum-dispatched RngBackend backends.

xoshiro

Xoshiro256++ implementation. Xoshiro256++ pseudo-random number generator.

Macros

rand_alphanumeric

Returns a random alphanumeric ASCII char.

rand_bool

Generates a random bool whose probability of true is the second argument. Panics if the probability is outside [0.0, 1.0].

rand_bytes

Returns a Vec<u8> of len random bytes. Requires the alloc feature.

rand_char

Returns a random lowercase ASCII char ('a'..='z').

rand_choose

Picks a random reference into the given slice (Option<&T>).

rand_double

Generates an f64 in [0.0, 1.0).

rand_exponential

Exponential sample with the given rate.

rand_float

Generates an f32 in [0.0, 1.0).

rand_int

Generates an unbiased i32 in the inclusive range [min, max].

rand_normal

Standard Box-Muller normal sample.

rand_poisson

Poisson sample with the given mean.

rand_range

Inclusive [min, max] range for i32.

rand_seed

Re-seeds the active backend.

rand_shuffle

Fisher-Yates shuffle in place.

rand_string

Returns a fresh lowercase ASCII String of length chars. Requires alloc.

rand_twist

Forces a Mersenne-Twister twist; no-op on Xoshiro.

rand_uint

Generates an unbiased u32 in the inclusive range [min, max].

rand_weighted_choice

Selects a reference into $choices weighted by $weights.

random_range

Generates an unbiased u32 in the half-open range [min, max).

Enums

VrdError

Crate-level error type for the vrd library.