Struct Rng 

pub struct Rng { /* private fields */ }

A high performance non-cryptographic random number generator.

Implementations

impl Rng

pub const fn new(seed: NonZeroU128) -> Self

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

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 bernoulli(&mut self, p: f64) -> bool

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

A probability p <= 0 or NaN is treated as 0, and a probability p >= 1 is 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 i128(&mut self) -> i128

Samples a i128 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 u128(&mut self) -> u128

Samples a u128 from the uniform distribution.

pub fn non_zero_u32(&mut self) -> NonZeroU32

Samples a NonZeroU32 from the uniform distribution.

pub fn non_zero_u64(&mut self) -> NonZeroU64

Samples a NonZeroU64 from the uniform distribution.

pub fn non_zero_u128(&mut self) -> NonZeroU128

Samples a NonZeroU128 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 bounded_usize(&mut self, n: usize) -> usize

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

The upper bound is inclusive.

pub fn range_i32(&mut self, a: i32, b: i32) -> i32

Samples a i32 from the uniform distribution over the range a ... b.

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

pub fn range_i64(&mut self, a: i64, b: i64) -> i64

Samples a i64 from the uniform distribution over the range a ... b.

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

pub fn range_isize(&mut self, a: isize, b: isize) -> isize

Samples a isize from the uniform distribution over the range a ... b.

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

pub fn range_u32(&mut self, a: u32, b: u32) -> u32

Samples a u32 from the uniform distribution over the range a ... b.

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

pub fn range_u64(&mut self, a: u64, b: u64) -> u64

Samples a u64 from the uniform distribution over the range a ... b.

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

pub fn range_usize(&mut self, a: usize, b: usize) -> usize

Samples a usize from the uniform distribution over the range a ... b.

The lower and upper bounds are inclusive, and the range can wrap around from usize::MAX to usize::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.

Every output, including zero, has a positive sign bit.

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.

Every output, including zero, has a positive sign bit.

pub fn biunit_f32(&mut self) -> f32

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

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

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

pub fn biunit_f64(&mut self) -> f64

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

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

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

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

Fills the provided buffer with independent uniformly distributed bytes.

pub unsafe fn fill_unchecked(&mut self, dst: *mut u8, len: usize)

Fills the provided buffer with independent uniformly distributed bytes.

Safety

It must be valid to write len arbitrary bytes at dst.

pub fn fill_uninit<'a>( &mut self, dst: &'a mut [MaybeUninit<u8>], ) -> &'a mut [u8]

Fills the provided buffer with independent uniformly distributed bytes, returning a reference to the initialized buffer. The returned buffer is a reference the same memory and has the same length as the input buffer.

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

Samples an array of independent uniformly distributed bytes.

pub fn shuffle<T>(&mut self, slice: &mut [T])

Shuffles a mutable slice in place with a random permutation.

Trait Implementations

impl Clone for Rng

fn clone(&self) -> Rng

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Rng

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SeedableRng for Rng

Available on crate feature rand_core only.

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<T: Rng + ?Sized>(g: &mut T) -> Self

Create a new PRNG seeded from an infallible Rng.

fn try_from_rng<T: TryRng + ?Sized>(g: &mut T) -> Result<Self, T::Error>

Create a new PRNG seeded from a potentially fallible Rng.

fn fork(&mut self) -> Self

where Self: Rng,

Fork this PRNG

fn try_fork(&mut self) -> Result<Self, Self::Error>

where Self: TryRng,

Fork this PRNG

impl TryRng for Rng

Available on crate feature rand_core only.

type Error = Infallible

The type returned in the event of a RNG error.

fn try_next_u32(&mut self) -> Result<u32, Self::Error>

Return the next random u32.

fn try_next_u64(&mut self) -> Result<u64, Self::Error>

Return the next random u64.

fn try_fill_bytes(&mut self, dst: &mut [u8]) -> Result<(), Self::Error>

Fill dst entirely with random data.