Struct Rng

pub struct Rng { /* private fields */ }

A high performance non-cryptographic random number generator.

Implementations

impl Rng

pub const fn new(seed: [u8; 15]) -> Self

Creates a random number generator with an initial state derived by hashing the given byte array.

pub const fn from_u64(seed: u64) -> Self

Creates a random number generator with an initial state derived by hashing the given u64 seed.

pub const fn state(&self) -> NonZeroU128

Retrieves the current state of the random number generator.

pub const fn from_state(state: NonZeroU128) -> Self

Creates a random number generator with a particular initial state.

If you want to deterministically initialize a generator from a small integer or other weak seed, you should NOT use this function and should instead use Rng::new or Rng::from_u64 which hash their arguments.

pub fn from_operating_system() -> Self

Creates a random number generator with a random seed retrieved from the operating system.

pub fn split(&mut self) -> Self

Splits off a new random number generator that may be used along with the original.

pub fn bernoulli(&mut self, p: f64) -> bool

Samples a bool from the Bernoulli distribution where true appears with probability approximately equal to p.

Probabilities p <= 0 or NaN are treated as 0, and p >= 1 are treated as 1.

pub fn bool(&mut self) -> bool

Samples a bool from the uniform distribution.

pub fn i32(&mut self) -> i32

Samples a i32 from the uniform distribution.

pub fn i64(&mut self) -> i64

Samples a i64 from the uniform distribution.

pub fn u32(&mut self) -> u32

Samples a u32 from the uniform distribution.

pub fn u64(&mut self) -> u64

Samples a u64 from the uniform distribution.

pub fn bounded_u32(&mut self, n: u32) -> u32

Samples a u32 from the uniform distribution over the range 0 ... n.

The upper bound is inclusive.

pub fn bounded_u64(&mut self, n: u64) -> u64

Samples a u64 from the uniform distribution over the range 0 ... n.

The upper bound is inclusive.

pub fn between_i32(&mut self, lo: i32, hi: i32) -> i32

Samples a i32 from the uniform distribution over the range lo ... hi.

The lower and upper bounds are inclusive, and the range can wrap around from i32::MAX to i32::MIN.

pub fn between_i64(&mut self, lo: i64, hi: i64) -> i64

Samples a i64 from the uniform distribution over the range lo ... hi.

The lower and upper bounds are inclusive, and the range can wrap around from i64::MAX to i64::MIN.

pub fn between_u32(&mut self, lo: u32, hi: u32) -> u32

Samples a u32 from the uniform distribution over the range lo ... hi.

The lower and upper bounds are inclusive, and the range can wrap around from u32::MAX to u32::MIN.

pub fn between_u64(&mut self, lo: u64, hi: u64) -> u64

Samples a u64 from the uniform distribution over the range lo ... hi.

The lower and upper bounds are inclusive, and the range can wrap around from u64::MAX to u64::MIN.

pub fn f32(&mut self) -> f32

Samples a f32 from a distribution that approximates the uniform distribution over the real interval [0, 1].

The distribution is the same as the one produced by the following procedure:

• Sample a real number from the uniform distribution on [0, 1].
• Round to the nearest multiple of 2⁻⁶³.
• Round to a f32 using the default rounding mode.

A zero output will always be +0, never -0.

pub fn f64(&mut self) -> f64

Samples a f64 from a distribution that approximates the uniform distribution over the real interval [0, 1].

The distribution is the same as the one produced by the following procedure:

• Sample a real number from the uniform distribution on [0, 1].
• Round to the nearest multiple of 2⁻⁶³.
• Round to a f64 using the default rounding mode.

A zero output will always be +0, never -0.

pub fn bytes(&mut self, dst: &mut [u8])

Fills the provided buffer with independent uniformly distributed bytes.

pub fn byte_array<const N: usize>(&mut self) -> [u8; N]

Samples an array of independent uniformly distributed bytes.

Trait Implementations

impl Clone for Rng

fn clone(&self) -> Rng

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl RngCore for Rng

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dst: &mut [u8])

Fill dest with random data.

impl SeedableRng for Rng

type Seed = [u8; 16]

Seed type, which is restricted to types mutably-dereferenceable as u8 arrays (we recommend [u8; N] for some N).

fn from_seed(seed: Self::Seed) -> Self

Create a new PRNG using the given seed.

fn seed_from_u64(seed: u64) -> Self

Create a new PRNG using a u64 seed.

fn from_rng(rng: &mut impl RngCore) -> Self

Create a new PRNG seeded from an infallible Rng.

fn try_from_rng<R>(rng: &mut R) -> Result<Self, <R as TryRngCore>::Error>

where R: TryRngCore,

Create a new PRNG seeded from a potentially fallible Rng.