random
Two generators and a set of distributions over them. Both generators implement RandomSource, so the whole draw surface works with either — or with a source of your own.
public module random::error;
public module random::bits;
public module random::source;
public module random::rng;
public module random::secure;
public module random::distribution;| File | What it holds | Import |
|---|---|---|
source | RandomSource, the trait both generators implement | import std::random::source; |
rng | Rng, xoshiro256** | import std::random::rng; |
secure | SecureRng, the kernel CSPRNG | import std::random::secure; |
distribution | Distribution, UniformU64, Normal, WeightedIndex, ... | import std::random::distribution; |
error | RandomError | import std::random::error; |
random::bits holds the two little-endian load/store helpers the generators share; there is nothing in it for user code.
Choosing a generator
Rng is xoshiro256** — excellent statistical quality, 256 bits of state, very fast. It is not suitable for cryptography.
SecureRng draws straight from the operating system's cryptographic generator. It exposes no predictable algorithm and is the right choice for keys, tokens, and nonces.
import std::random::rng;
mut r: Rng = Rng::from_seed(42); // reproducible
const roll: u64 = r.next_range(1, 7);public function name() { ... }
public:Visible to any module that imports this one - the default for top-level items and for struct fields, so it is mostly written to be explicit. public: opens a visibility block that groups the members after it.
public module collections::array;In a directory's _module.cryo aggregator, lists a submodule and whether it is public. Importing the directory's namespace sees only the modules declared public here.
namespace std::random::bits;std::random::bits: internal little-endian byte helpers.
namespace std::random::distribution;std::random::distribution: samplers over any RandomSource.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
mut name: Type = value;A mutable binding, reassignable after declaration - mutability is opt-in, const is the default. At module level it declares mutable global state. Before & it marks an exclusive reference or receiver instead.
mut r: Rngtype struct Rng {
s0: u64;
s1: u64;
s2: u64;
s3: u64;
}A fast non-cryptographic PRNG (xoshiro256**). The 256-bit state is the four words s0..s3.
static Rng::from_seed(seed: u64) -> RngSeed deterministically from a single 64-bit value. The same seed always produces the same sequence.
std::random::rngconst NAME: Type = value;At module level, a true compile-time constant, conventionally SCREAMING_SNAKE_CASE. (mut at module level declares mutable global state instead.)
const roll: u64mut r: RngRng::next_range<T>(mut &this, lo: T, hi: T) -> Tvia trait RandomSource
A uniform integer of type T in [lo, hi). Requires lo < hi. static match (T) covers every integer width: the spans of the 64-bit-and-narrower types are drawn unbiased through next_below; u128/i128 use an inline 128-bit rejection sampler.
type trait RandomSource {
next_64(mut &this) -> u64;
next<T>(mut &this) -> T;
next_below(mut &this, bound: u64) -> u64;
next_range<T>(mut &this, lo: T, hi: T) -> T;
next_below_wide(mut &this, bound: u128) -> u128;
fill(mut &this, dst: Slice<u8>) -> void;
shuffle<T>(mut &this, items: &Slice<T>) -> void;
choose<T>(mut &this, items: &Slice<T>) -> Option<T*>;
}type struct SecureRng {}Cryptographically secure source backed by the kernel CSPRNG. Slower than Rng; use it only where unpredictability matters.
type trait Distribution<T> {
sample<R>(&this, rng: mut &R) -> T
where R: RandomSource;
}A sampleable distribution producing values of type T.
type struct UniformU64 {
lo: u64;
hi: u64;
}Uniform unsigned integers in [lo, hi).
type struct Normal {
mean: f64;
std_dev: f64;
}The normal distribution, parameterized by mean and std_dev.
type struct WeightedIndex {
cumulative: Array<f64>;
total: f64;
}Chooses an index 0..n with probability proportional to a weight. Built once from a weight list, then sampled cheaply. Owns its cumulative table, so it carries a drop.
type enum RandomError {
EntropyUnavailable;
EmptyRange;
InvalidWeights;
}What went wrong in a fallible random operation.
std::random::error