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.

Choosing a backend

Default Random is non-cryptographic Xoshiro256++. For credentials, session IDs, or anything an attacker would benefit from predicting, enable the crypto feature and construct via Random::new_secure (entropy-seeded) or Random::from_secure_seed (deterministic). The other backends cover different speed / state-size / reproducibility points:

Backend	Constructor	State	Crypto-quality?
Xoshiro256++	Random::new	32 B	no
MT19937	Random::new_mersenne_twister	2 488 B	no
PCG32 / PCG64	Random::new_pcg32 / Random::new_pcg64	16 / 32 B	no
ChaCha20	Random::new_secure	~256 B	yes

Optional features

• simd - SIMD-batched fill_bytes (~2–3× bulk throughput).
• pcg - PCG32 / PCG64 backends.
• crypto - ChaCha20 CSPRNG backend.
• quasirandom - Halton / Sobol / Van der Corput low-discrepancy sequences for Monte Carlo integration.
• serde - Serialize / Deserialize on the public types.

Re-exports

pub use distribution::Distribution;

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

chacha

ChaCha20 CSPRNG (feature crypto). ChaCha20-based CSPRNG backend (feature crypto).

distribution

Pluggable Distribution trait and built-in samplers. Trait-based distributions and pluggable user-defined samplers.

macros

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

mersenne_twister

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

pcg

PCG32 / PCG64 generators (feature pcg). PCG (Permuted Congruential Generator) family - O’Neill, 2014.

quasirandom

Quasi-random low-discrepancy sequences (feature quasirandom). Quasi-random (low-discrepancy) sequences.

random

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

xoshiro

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

xoshiro_simd

SIMD-batched fill_bytes (feature simd).

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.