Struct Mt64

pub struct Mt64 { /* private fields */ }

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

Size

Mt64 requires approximately 2.5 kilobytes of internal state.

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

Mt64 is also the same size as Mt.

assert_eq!(2504, size_of::<Mt64>());
assert_eq!(size_of::<Mt>(), size_of::<Mt64>());

Implementations

impl Mt64

pub const DEFAULT_SEED: u64 = 5_489u64

Default seed used by Mt64::new_unseeded.

pub fn new(seed: u64) -> Self

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

Examples

Constructing with a u64 seed

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

Constructing with default seed

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

pub fn new_with_key<I>(key: I) -> Self

where I: IntoIterator<Item = u64>, I::IntoIter: Clone,

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

Key can have any length.

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_u64;
let mt = Mt64::new(seed);
let unseeded = Mt64::new_unseeded();
assert_eq!(mt, unseeded);

pub fn next_u64(&mut self) -> u64

Generate next u64 output.

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

Examples

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

pub fn next_u32(&mut self) -> u32

Generate next u32 output.

This function is implemented by generating one u64 from the RNG and performing shifting and masking to turn it into a u32 output.

Examples

let mut mt = Mt64::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 u64s (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 8.

Examples

let mut mt = Mt64::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 = u64>,

Attempt to recover the internal state of a Mersenne Twister using the past 312 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 312 elements, an error is returned because there is not enough data to fully initialize the RNG.

If key has more than 312 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: u64)

Reseed a Mersenne Twister from a single u64.

Examples

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

pub fn reseed_with_key<I>(&mut self, key: I)

where I: IntoIterator<Item = u64>, I::IntoIter: Clone,

Reseed a Mersenne Twister from am iterator of u64s.

Key can have any length.

Trait Implementations

impl Clone for Mt64

fn clone(&self) -> Mt64

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Mt64

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

Formats the value using the given formatter.

impl Default for Mt64

fn default() -> Self

Return a new Mt64 with the default seed.

Equivalent to calling Mt64::new_unseeded.

impl From<[u64; 312]> for Mt64

fn from(key: [u64; 312]) -> Self

Recover the internal state of a Mersenne Twister using the past 312 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; 8]> for Mt64

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

Construct a Mersenne Twister RNG from 8 bytes.

Examples

// Default MT seed
let seed = 5489_u64.to_le_bytes();
let mut mt = Mt64::from(seed);
assert_ne!(mt.next_u64(), mt.next_u64());

impl From<u64> for Mt64

fn from(seed: u64) -> Self

Construct a Mersenne Twister RNG from a u64 seed.

This function is equivalent to new.

Examples

// Default MT seed
let seed = 5489_u64;
let mt1 = Mt64::from(seed);
let mt2 = Mt64::new(seed);
assert_eq!(mt1, mt2);

// Non-default MT seed
let seed = 9927_u64;
let mt1 = Mt64::from(seed);
let mt2 = Mt64::new(seed);
assert_eq!(mt1, mt2);

impl Hash for Mt64

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Mt64

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Mt64

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Mt64

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl TryFrom<&[u64]> for Mt64

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

Attempt to recover the internal state of a Mersenne Twister using the past 312 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 Mt64::recover.

Errors

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

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

type Error = RecoverRngError

The type returned in the event of a conversion error.

impl Eq for Mt64

impl StructuralPartialEq for Mt64