`stdlib.rand`¶

Random Number Generation

Generated from v0.65.7. 4 source files, 57 documented symbols.

`chacha.xi`¶

`type ChaChaRng`¶

ChaCha20-based deterministic RNG state.

Field	Type
`state`	`Vec[UInt32]`
`pos`	`Int`

`fn chacha_rng_new() -> ChaChaRng`¶

Create a ChaCha RNG with an all-zero key (deterministic default). Test vector: the first output word of the zero-key block is 0xADE0B876.

Postcondition: result.state.len() == 16
Postcondition: result.pos == 0

`fn chacha_rng_from_seed(seed: UInt64) -> ChaChaRng`¶

Create a ChaCha RNG from a 64-bit seed. The seed's two 32-bit halves are replicated into the 8 key words.

Postcondition: result.state.len() == 16
Postcondition: result.pos == 0

`fn chacha_rng_next_u32(r: &mut ChaChaRng) -> UInt32`¶

Return the next 32-bit output word. pos tracks the position within the 64-word keystream window (16 words per block, 4 blocks per window); the block counter advances at each 16-word boundary.

Precondition: r.state.len() == 16
Precondition: r.pos >= 0 && r.pos < 64

`fn chacha_rng_next_int(r: &mut ChaChaRng) -> Int`¶

Return the next value as a signed i64 in [0, 2^32).

Postcondition: result >= 0 && result < 4294967296

`fn chacha_rng_next_float(r: &mut ChaChaRng) -> Float64`¶

Return the next value as a Float64 in [0, 1).

Postcondition: result >= 0 && result < 1

`fn chacha_rng_next_bounded(r: &mut ChaChaRng, hi: Int) -> Int`¶

Return the next value in [0, hi). Requires hi > 0.

Postcondition: (hi <= 0) => (result == 0)
Postcondition: (hi > 0) => (result >= 0 && result < hi)

`mt19937.xi`¶

`type Mt19937`¶

Mersenne Twister (MT19937) RNG state.

Field	Type
`state`	`Vec[UInt32]`
`index`	`Int`

`fn mt19937_new() -> Mt19937`¶

Create an MT19937 generator with the classic default seed 5489.

Postcondition: result.state.len() == 624
Postcondition: result.index == 624

`fn mt19937_from_seed(seed: UInt32) -> Mt19937`¶

Create an MT19937 generator from an explicit 32-bit seed.

Postcondition: result.state.len() == 624
Postcondition: result.index == 624

`fn mt19937_reseed(r: &mut Mt19937, seed: UInt32)`¶

Re-seed an existing generator in place using the classic seeding algorithm.

Postcondition: r.index == 624
Postcondition: r.state.len() == r.state.len()@pre

`fn mt19937_next_u32(r: &mut Mt19937) -> UInt32`¶

Return the next 32-bit output word, tempering with: y ^= y >> 11; y ^= (y << 7) & 0x9d2c5680; y ^= (y << 15) & 0xefc60000; y ^= y >> 18.

Precondition: r.state.len() == 624
Precondition: r.index >= 0 && r.index <= 624

`fn mt19937_next_int(r: &mut Mt19937) -> Int`¶

Return the next value as a signed i64 in [0, 2^32).

Postcondition: result >= 0 && result < 4294967296

`fn mt19937_next_float(r: &mut Mt19937) -> Float64`¶

Return the next value as a Float64 in [0, 1).

Postcondition: result >= 0 && result < 1

`fn mt19937_next_bounded(r: &mut Mt19937, hi: Int) -> Int`¶

Return the next value in [0, hi). Requires hi > 0.

Postcondition: (hi <= 0) => (result == 0)
Postcondition: (hi > 0) => (result >= 0 && result < hi)

`pcg.xi`¶

`type Pcg`¶

PCG64 RNG state.

Field	Type
`state`	`UInt64`
`inc`	`UInt64`

`fn pcg_new() -> Pcg`¶

Create a PCG generator with the reference default state/stream constants.

Postcondition: result.state != 0
Postcondition: result.inc != 0

`fn pcg_from_seed(seed: UInt64) -> Pcg`¶

Create a PCG generator from a 64-bit seed. Standard init: state = 0, inc = (seed << 1) | 1, then advance once.

Postcondition: result.state != 0
Postcondition: result.inc != 0

`fn pcg_next_u32(r: &mut Pcg) -> UInt32`¶

Return the next 32-bit output word. xorshifted = ((oldstate >> 18) ^ oldstate) >> 27; rot = oldstate >> 59; output = (xorshifted >> rot) | (xorshifted << ((-rot) & 31)).

Postcondition: result < 4294967296

`fn pcg_next_int(r: &mut Pcg) -> Int`¶

Return the next value as a signed i64 in [0, 2^32).

Postcondition: result >= 0 && result < 4294967296

`fn pcg_next_float(r: &mut Pcg) -> Float64`¶

Return the next value as a Float64 in [0, 1).

Postcondition: result >= 0 && result < 1

`fn pcg_next_bounded(r: &mut Pcg, hi: Int) -> Int`¶

Return the next value in [0, hi). Requires hi > 0.

Postcondition: (hi <= 0) => (result == 0)
Postcondition: (hi > 0) => (result >= 0 && result < hi)

`rand.xi`¶

`type StdRng`¶

=== Standard RNG ===

Field	Type
`state`	`Int`

Derives: Clone

`fn new() -> StdRng`¶

Seeded standard RNG (OS/time entropy when available).

Precondition: true

`fn from_seed(seed: Int) -> StdRng`¶

Deterministic standard RNG from an integer seed.

Postcondition: result.state != 0
Postcondition: (seed != 0) => (result.state == seed)

`fn random() -> Float64`¶

=== Basic random values ===

Postcondition: result >= 0
Postcondition: result < 1

`fn random_int(min: Int, max: Int) -> Int`¶

Uniform Int in [min, max] (inclusive).

Precondition: min <= max
Postcondition: result >= min && result <= max

`fn random_float(min: Float64, max: Float64) -> Float64`¶

Uniform Float64 in [min, max).

Postcondition: (min <= max) => (result >= min && result <= max)

`fn random_bool() -> Bool`¶

Fair coin flip.

Precondition: true

`fn random_bytes(count: Int) -> Vec[UInt8]`¶

count random bytes (empty when count <= 0).

Postcondition: (count > 0) => (result.len() == count)
Postcondition: (count <= 0) => (result.len() == 0)

`fn sample_uniform(min: Float64, max: Float64) -> Float64`¶

=== Distributions ===

Postcondition: (min <= max) => (result >= min && result <= max)

`fn sample_normal(mean: Float64, stddev: Float64) -> Float64`¶

Normal (Gaussian) sample with the given mean and stddev.

Postcondition: ((stddev == 0) && (mean == mean)) => (result == mean)

`fn sample_exponential(lambda: Float64) -> Float64`¶

Exponential sample with the given rate lambda.

Postcondition: (lambda > 0) => (result >= 0)

`fn sample_bernoulli(p: Float64) -> Bool`¶

Bernoulli trial: true with probability p.

Postcondition: (p <= 0) => (result == false)
Postcondition: (p > 1) => (result == true)

`fn sample_binomial(n: Int, p: Float64) -> Int`¶

Binomial sample: successes in n independent trials with probability p.

Postcondition: (n >= 0) => (result >= 0 && result <= n)
Postcondition: (n < 0) => (result == 0)

`fn sample_poisson(lambda: Float64) -> Int`¶

Poisson sample with mean lambda.

Postcondition: (lambda <= 0) => (result == -1)
Postcondition: (lambda >= 1) => (result >= 0)

`fn sample_gamma(shape: Float64, scale: Float64) -> Float64`¶

Gamma sample with the given shape and scale.

Postcondition: (shape <= 0) => (result == 0)

`fn sample_beta(alpha: Float64, beta: Float64) -> Float64`¶

Beta sample with parameters alpha and beta.

Postcondition: (alpha <= 0 || beta <= 0) => (result == 0)

`fn shuffle[T](items: &mut Vec[T])`¶

=== Shuffle & Pick ===

Postcondition: items.len() == items.len()@pre

`fn pick[T](items: &Vec[T]) -> Option[&T]`¶

Uniformly pick one element, or None for an empty vector.

Postcondition: (items.len() == 0) => (result.is_none)
Postcondition: (items.len() > 0) => (result.is_some)

`fn pick_n[T](items: &Vec[T], n: Int) -> Vec[&T]`¶

Uniformly pick n distinct elements (fewer when the vector is shorter).

Postcondition: result.len() <= items.len()
Postcondition: (items.len() == 0) => (result.len() == 0)
Postcondition: (n > 0 && n < items.len()) => (result.len() == n)

`fn weighted_pick[T](items: &Vec[T], weights: &Vec[Float64]) -> Option[&T]`¶

Pick an element with probability proportional to its weight; None when the vector is empty or all weights are <= 0.

Postcondition: (items.len() == 0) => (result.is_none)
Postcondition: (weights.len() != items.len()) => (result.is_none)
Postcondition: result.is_some => (items.len() > 0 && weights.len() == items.len())

`fn uuid_v4() -> Str`¶

Random (version 4) UUID string.

Postcondition: result.len() == 36

`fn uuid_v7() -> Str`¶

Time-ordered (version 7) UUID string.

Postcondition: result.len() == 36

`fn seed_from_entropy()`¶

=== Seeding ===

Precondition: true

`fn seed_from_time()`¶

Reseed the global RNG from the current time.

Precondition: true

`fn seed_from_value(seed: Int)`¶

Reseed the global RNG from an explicit value.

Postcondition: state() != 0

`fn state() -> Int`¶

Returns an opaque snapshot of the global RNG state. Pass the value to set_state to restore the exact stream position; snapshots are implementation-specific and only valid for this module. The global state is never zero. Complexity: O(1).

Postcondition: result != 0

`fn set_state(snapshot: Int)`¶

Restores the global RNG state from a state snapshot. The snapshot must be non-zero (every value returned by state is); use seed_from_value(0) to reset the generator to its normalized zero seed. Complexity: O(1).

Precondition: snapshot != 0

`type Xorshift64`¶

Xorshift64 PRNG (Marsaglia, 2003). State: 64-bit unsigned. Period: 2^64 - 1. Triple-xorshift: x ^= x << a; x ^= x >> b; x ^= x << c. Complexity: O(1) per call.

Field	Type
`state`	`Int`

Derives: Clone

`fn new(seed: Int) -> Xorshift64`¶

Creates a new Xorshift64 generator with the given seed. Seed must be non-zero. Zero seed is replaced with 1.

Postcondition: result.state != 0

`fn next_int(self: Self) -> Int`¶

Returns the next pseudo-random integer from this Xorshift64 generator. Uses triple-xorshift: x ^= x << 13; x ^= x >> 7; x ^= x << 17.

Precondition: self.state != 0
Postcondition: result != 0

`fn random_choice[T](items: &Vec[T]) -> Option[&T]`¶

Returns a random element from a vector. Returns None if the vector is empty. Wraps the existing pick function. Complexity: O(1).

Postcondition: (items.len() == 0) => (result.is_none)
Postcondition: (items.len() > 0) => (result.is_some)

`fn random_shuffle[T](items: &mut Vec[T])`¶

Shuffles a vector in place using Fisher-Yates. Wraps the existing shuffle function. Complexity: O(n), n = items length.

Postcondition: items.len() == items.len()@pre

`fn random_fraction() -> Float64`¶

Alias for random(). Returns a Float64 in [0, 1).

Postcondition: result >= 0 && result < 1

`fn gaussian_box_muller(mean: Float64, stddev: Float64) -> Float64`¶

Generates a normally distributed random number using the Box-Muller transform. Mean and stddev parameters control the distribution center and spread. Complexity: O(1).

Postcondition: ((stddev == 0) && (mean == mean)) => (result == mean)

`fn random_bytes_crypto(count: Int) -> Vec[UInt8]`¶

Fills a buffer with cryptographically secure random bytes. Delegates to xiom.crypto.secure_random_bytes. Complexity: O(n), n = count.

Postcondition: (count > 0) => (result.len() == count)
Postcondition: (count <= 0) => (result.len() == 0)

stdlib.rand¶

chacha.xi¶

type ChaChaRng¶

fn chacha_rng_new() -> ChaChaRng¶

fn chacha_rng_from_seed(seed: UInt64) -> ChaChaRng¶

fn chacha_rng_next_u32(r: &mut ChaChaRng) -> UInt32¶

fn chacha_rng_next_int(r: &mut ChaChaRng) -> Int¶

fn chacha_rng_next_float(r: &mut ChaChaRng) -> Float64¶

fn chacha_rng_next_bounded(r: &mut ChaChaRng, hi: Int) -> Int¶

mt19937.xi¶

type Mt19937¶

fn mt19937_new() -> Mt19937¶

fn mt19937_from_seed(seed: UInt32) -> Mt19937¶

fn mt19937_reseed(r: &mut Mt19937, seed: UInt32)¶

fn mt19937_next_u32(r: &mut Mt19937) -> UInt32¶

fn mt19937_next_int(r: &mut Mt19937) -> Int¶

fn mt19937_next_float(r: &mut Mt19937) -> Float64¶

fn mt19937_next_bounded(r: &mut Mt19937, hi: Int) -> Int¶

pcg.xi¶

type Pcg¶

fn pcg_new() -> Pcg¶

fn pcg_from_seed(seed: UInt64) -> Pcg¶

fn pcg_next_u32(r: &mut Pcg) -> UInt32¶

fn pcg_next_int(r: &mut Pcg) -> Int¶

fn pcg_next_float(r: &mut Pcg) -> Float64¶

fn pcg_next_bounded(r: &mut Pcg, hi: Int) -> Int¶

rand.xi¶

type StdRng¶

fn new() -> StdRng¶

fn from_seed(seed: Int) -> StdRng¶

fn random() -> Float64¶

fn random_int(min: Int, max: Int) -> Int¶

fn random_float(min: Float64, max: Float64) -> Float64¶

fn random_bool() -> Bool¶

fn random_bytes(count: Int) -> Vec[UInt8]¶

fn sample_uniform(min: Float64, max: Float64) -> Float64¶

fn sample_normal(mean: Float64, stddev: Float64) -> Float64¶

fn sample_exponential(lambda: Float64) -> Float64¶

fn sample_bernoulli(p: Float64) -> Bool¶

fn sample_binomial(n: Int, p: Float64) -> Int¶

fn sample_poisson(lambda: Float64) -> Int¶

fn sample_gamma(shape: Float64, scale: Float64) -> Float64¶

fn sample_beta(alpha: Float64, beta: Float64) -> Float64¶

fn shuffle[T](items: &mut Vec[T])¶

fn pick[T](items: &Vec[T]) -> Option[&T]¶

fn pick_n[T](items: &Vec[T], n: Int) -> Vec[&T]¶

fn weighted_pick[T](items: &Vec[T], weights: &Vec[Float64]) -> Option[&T]¶

fn uuid_v4() -> Str¶

fn uuid_v7() -> Str¶

fn seed_from_entropy()¶

fn seed_from_time()¶

fn seed_from_value(seed: Int)¶

fn state() -> Int¶

fn set_state(snapshot: Int)¶

type Xorshift64¶

fn new(seed: Int) -> Xorshift64¶

fn next_int(self: Self) -> Int¶

fn random_choice[T](items: &Vec[T]) -> Option[&T]¶

fn random_shuffle[T](items: &mut Vec[T])¶

fn random_fraction() -> Float64¶

fn gaussian_box_muller(mean: Float64, stddev: Float64) -> Float64¶

fn random_bytes_crypto(count: Int) -> Vec[UInt8]¶

`stdlib.rand`¶

`chacha.xi`¶

`type ChaChaRng`¶

`fn chacha_rng_new() -> ChaChaRng`¶

`fn chacha_rng_from_seed(seed: UInt64) -> ChaChaRng`¶

`fn chacha_rng_next_u32(r: &mut ChaChaRng) -> UInt32`¶

`fn chacha_rng_next_int(r: &mut ChaChaRng) -> Int`¶

`fn chacha_rng_next_float(r: &mut ChaChaRng) -> Float64`¶

`fn chacha_rng_next_bounded(r: &mut ChaChaRng, hi: Int) -> Int`¶

`mt19937.xi`¶

`type Mt19937`¶

`fn mt19937_new() -> Mt19937`¶

`fn mt19937_from_seed(seed: UInt32) -> Mt19937`¶

`fn mt19937_reseed(r: &mut Mt19937, seed: UInt32)`¶

`fn mt19937_next_u32(r: &mut Mt19937) -> UInt32`¶

`fn mt19937_next_int(r: &mut Mt19937) -> Int`¶

`fn mt19937_next_float(r: &mut Mt19937) -> Float64`¶

`fn mt19937_next_bounded(r: &mut Mt19937, hi: Int) -> Int`¶

`pcg.xi`¶

`type Pcg`¶

`fn pcg_new() -> Pcg`¶

`fn pcg_from_seed(seed: UInt64) -> Pcg`¶

`fn pcg_next_u32(r: &mut Pcg) -> UInt32`¶

`fn pcg_next_int(r: &mut Pcg) -> Int`¶

`fn pcg_next_float(r: &mut Pcg) -> Float64`¶

`fn pcg_next_bounded(r: &mut Pcg, hi: Int) -> Int`¶

`rand.xi`¶

`type StdRng`¶

`fn new() -> StdRng`¶

`fn from_seed(seed: Int) -> StdRng`¶

`fn random() -> Float64`¶

`fn random_int(min: Int, max: Int) -> Int`¶

`fn random_float(min: Float64, max: Float64) -> Float64`¶

`fn random_bool() -> Bool`¶

`fn random_bytes(count: Int) -> Vec[UInt8]`¶

`fn sample_uniform(min: Float64, max: Float64) -> Float64`¶

`fn sample_normal(mean: Float64, stddev: Float64) -> Float64`¶

`fn sample_exponential(lambda: Float64) -> Float64`¶

`fn sample_bernoulli(p: Float64) -> Bool`¶

`fn sample_binomial(n: Int, p: Float64) -> Int`¶

`fn sample_poisson(lambda: Float64) -> Int`¶

`fn sample_gamma(shape: Float64, scale: Float64) -> Float64`¶

`fn sample_beta(alpha: Float64, beta: Float64) -> Float64`¶

`fn shuffle[T](items: &mut Vec[T])`¶

`fn pick[T](items: &Vec[T]) -> Option[&T]`¶

`fn pick_n[T](items: &Vec[T], n: Int) -> Vec[&T]`¶

`fn weighted_pick[T](items: &Vec[T], weights: &Vec[Float64]) -> Option[&T]`¶

`fn uuid_v4() -> Str`¶

`fn uuid_v7() -> Str`¶

`fn seed_from_entropy()`¶

`fn seed_from_time()`¶

`fn seed_from_value(seed: Int)`¶

`fn state() -> Int`¶

`fn set_state(snapshot: Int)`¶

`type Xorshift64`¶

`fn new(seed: Int) -> Xorshift64`¶

`fn next_int(self: Self) -> Int`¶

`fn random_choice[T](items: &Vec[T]) -> Option[&T]`¶

`fn random_shuffle[T](items: &mut Vec[T])`¶

`fn random_fraction() -> Float64`¶

`fn gaussian_box_muller(mean: Float64, stddev: Float64) -> Float64`¶

`fn random_bytes_crypto(count: Int) -> Vec[UInt8]`¶