Struct rand_mt::Mt19937GenRand32

pub struct Mt19937GenRand32 { /* fields omitted */ }

The 32-bit flavor of the Mersenne Twister pseudorandom number generator.

The official name of this RNG is MT19937. It natively outputs u32.

Size

Mt19937GenRand32 requires approximately 2.5KB of internal state.

You may wish to store an Mt19937GenRand32 on the heap in a Box to make it easier to embed in another struct.

Mt19937GenRand32 is also the same size as Mt19937GenRand64.

assert_eq!(2504, mem::size_of::<Mt19937GenRand32>());
assert_eq!(mem::size_of::<Mt19937GenRand64>(), mem::size_of::<Mt19937GenRand32>());

Implementations

impl Mt19937GenRand32

pub const DEFAULT_SEED: u32

Default seed used by Mt19937GenRand32::new_unseeded.

#[must_use]pub fn new(seed: u32) -> Self

Create a new Mersenne Twister random number generator using the given seed.

Examples

Constructing with a u32 seed

let seed = 123_456_789_u32;
let mt1 = Mt19937GenRand32::new(seed);
let mt2 = Mt19937GenRand32::from(seed.to_le_bytes());
assert_eq!(mt1, mt2);

Constructing with default seed

let mt1 = Mt19937GenRand32::new(Mt19937GenRand32::DEFAULT_SEED);
let mt2 = Mt19937GenRand32::new_unseeded();
assert_eq!(mt1, mt2);

#[must_use]pub fn new_with_key<I>(key: I) -> Self where
    I: IntoIterator<Item = u32>,
    I::IntoIter: Clone, 

Create a new Mersenne Twister random number generator using the given key.

Key can have any length.

#[must_use]pub fn new_unseeded() -> Self

Create a new Mersenne Twister random number generator using the default fixed seed.

Examples

// Default MT seed
let seed = 5489_u32;
let mt = Mt19937GenRand32::new(seed);
let unseeded = Mt19937GenRand32::new_unseeded();
assert_eq!(mt, unseeded);

pub fn next_u64(&mut self) -> u64

Generate next u64 output.

This function is implemented by generating two u32s from the RNG and shifting + masking them into a u64 output.

Examples

let mut mt = Mt19937GenRand32::new_unseeded();
assert_ne!(mt.next_u64(), mt.next_u64());

pub fn next_u32(&mut self) -> u32

Generate next u32 output.

u32 is the native output of the generator. This function advances the RNG step counter by one.

Examples

let mut mt = Mt19937GenRand32::new_unseeded();
assert_ne!(mt.next_u32(), mt.next_u32());

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

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

Examples

let mut mt = Mt19937GenRand32::new_unseeded();
let mut buf = [0; 32];
mt.fill_bytes(&mut buf);
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
mt.fill_bytes(&mut buf);
assert_ne!([0; 31], buf);

pub fn recover<I>(key: I) -> Result<Self, RecoverRngError> where
    I: IntoIterator<Item = u32>, 

Attempt to recover the internal state of a Mersenne Twister using the past 624 samples.

This conversion takes a history of samples from a RNG and returns a RNG that will produce identical output to the RNG that supplied the samples.

This constructor is also available as a TryFrom implementation for &[u32].

Errors

If key has less than 624 elements, an error is returned because there is not enough data to fully initialize the RNG.

If key has more than 624 elements, an error is returned because the recovered RNG will not produce identical output to the RNG that supplied the samples.

pub fn reseed(&mut self, seed: u32)

Reseed a Mersenne Twister from a single u32.

Examples

// Default MT seed
let mut mt = Mt19937GenRand32::new_unseeded();
let first = mt.next_u32();
mt.fill_bytes(&mut [0; 512]);
// Default MT seed
mt.reseed(5489_u32);
assert_eq!(first, mt.next_u32());

pub fn reseed_with_key<I>(&mut self, key: I) where
    I: IntoIterator<Item = u32>,
    I::IntoIter: Clone, 

Reseed a Mersenne Twister from am iterator of u32s.

Key can have any length.

Trait Implementations

impl Clone for Mt19937GenRand32

pub fn clone(&self) -> Mt19937GenRand32

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Mt19937GenRand32

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

Formats the value using the given formatter.

impl Default for Mt19937GenRand32

pub fn default() -> Self

Return a new Mt19937GenRand32 with the default seed.

Equivalent to calling Mt19937GenRand32::new_unseeded.

impl Eq for Mt19937GenRand32

impl From<[u32; 624]> for Mt19937GenRand32

pub fn from(key: [u32; 624]) -> Self

Recover the internal state of a Mersenne Twister using the past 624 samples.

This conversion takes a history of samples from a RNG and returns a RNG that will produce identical output to the RNG that supplied the samples.

impl From<[u8; 4]> for Mt19937GenRand32

pub fn from(seed: [u8; 4]) -> Self

Construct a Mersenne Twister RNG from 4 bytes.

The given bytes are treated as a little endian encoded u32.

Examples

// Default MT seed
let seed = 5489_u32.to_le_bytes();
let mut mt = Mt19937GenRand32::from(seed);
assert_ne!(mt.next_u32(), mt.next_u32());

This constructor is equivalent to passing a little endian encoded u32.

// Default MT seed
let seed = 5489_u32.to_le_bytes();
let mt1 = Mt19937GenRand32::from(seed);
let mt2 = Mt19937GenRand32::new(5489_u32);
assert_eq!(mt1, mt2);

impl From<u32> for Mt19937GenRand32

pub fn from(seed: u32) -> Self

Construct a Mersenne Twister RNG from a u32 seed.

This function is equivalent to new.

impl Hash for Mt19937GenRand32

pub fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for Mt19937GenRand32

pub fn cmp(&self, other: &Mt19937GenRand32) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Mt19937GenRand32> for Mt19937GenRand32

pub fn eq(&self, other: &Mt19937GenRand32) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Mt19937GenRand32) -> bool

This method tests for !=.

impl PartialOrd<Mt19937GenRand32> for Mt19937GenRand32

pub fn partial_cmp(&self, other: &Mt19937GenRand32) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

pub fn lt(&self, other: &Mt19937GenRand32) -> bool

This method tests less than (for self and other) and is used by the < operator.

pub fn le(&self, other: &Mt19937GenRand32) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

pub fn gt(&self, other: &Mt19937GenRand32) -> bool

This method tests greater than (for self and other) and is used by the > operator.

pub fn ge(&self, other: &Mt19937GenRand32) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl RngCore for Mt19937GenRand32

pub fn next_u64(&mut self) -> u64

Generate next u64 output.

This function is implemented by generating two u32s from the RNG and shifting + masking them into a u64 output.

Examples

use rand_core::RngCore;
use rand_mt::Mt19937GenRand32;

let mut rng = Mt19937GenRand32::new_unseeded();
assert_ne!(rng.next_u64(), rng.next_u64());

pub fn next_u32(&mut self) -> u32

Generate next u32 output.

u32 is the native output of the generator. This function advances the RNG step counter by one.

Examples

use rand_core::RngCore;
use rand_mt::Mt19937GenRand32;

let mut rng = Mt19937GenRand32::new_unseeded();
assert_ne!(rng.next_u32(), rng.next_u32());

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

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

Examples

use rand_core::RngCore;
use rand_mt::Mt19937GenRand32;

let mut rng = Mt19937GenRand32::new_unseeded();
let mut buf = [0; 32];
rng.fill_bytes(&mut buf);
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
rng.fill_bytes(&mut buf);
assert_ne!([0; 31], buf);

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

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

try_fill_bytes is implemented with fill_bytes and is infallible.

Examples

use rand_core::RngCore;
use rand_mt::Mt19937GenRand32;

let mut rng = Mt19937GenRand32::new_unseeded();
let mut buf = [0; 32];
rng.try_fill_bytes(&mut buf)?;
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
rng.try_fill_bytes(&mut buf)?;
assert_ne!([0; 31], buf);

impl SeedableRng for Mt19937GenRand32

type Seed = [u8; 4]

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

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

Reseed from a little endian encoded u32.

Examples

use rand_core::{RngCore, SeedableRng};
use rand_mt::Mt19937GenRand32;

// Default MT seed
let seed = 5489_u32.to_le_bytes();
let mut rng = Mt19937GenRand32::from_seed(seed);
assert_ne!(rng.next_u32(), rng.next_u32());

pub fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed.

pub fn from_rng<R>(rng: R) -> Result<Self, Error> where
    R: RngCore, 

Create a new PRNG seeded from another Rng.

impl StructuralEq for Mt19937GenRand32

impl StructuralPartialEq for Mt19937GenRand32

impl TryFrom<&'_ [u32]> for Mt19937GenRand32

type Error = RecoverRngError

The type returned in the event of a conversion error.

pub fn try_from(key: &[u32]) -> Result<Self, Self::Error>

Attempt to recover the internal state of a Mersenne Twister using the past 624 samples.

This conversion takes a history of samples from a RNG and returns a RNG that will produce identical output to the RNG that supplied the samples.

This conversion is implemented with Mt19937GenRand32::recover.

Errors

If key has less than 624 elements, an error is returned because there is not enough data to fully initialize the RNG.

If key has more than 624 elements, an error is returned because the recovered RNG will not produce identical output to the RNG that supplied the samples.