Struct randomize::AnyPCG

pub struct AnyPCG<T: PCG> { /* fields omitted */ }

A wrapper around PCG types that generates any-size outputs without wasting random bits.

A PCG can be thought of as generating a pseudo-random bit stream, 32 bits at a time for PCG32, 64 bits for PCG64, etc. Even if you currently just need 8 bits of random data, you still get 32. That means, that to get a u8 out of a PCG32, you end up throwing 24 bits away.

AnyPCG keeps all currently unused bits in a buffer. From a single PCG32::next_u32 call it can give you four u8s, two u8s and a u16, a u8 and a char, or other combinations. No bit is wasted. So AnyPCG can be thought of as generating a pseudo-random bit stream for a variable amount of bits at a time.

This "no waste" strategy comes with a mild added cost in random number generation. It is up to you to decide what's more important: Generating a lot of random numbers quickly, or making most out of your random bit stream. In any case, only use this wrapper type if you often need random values of bit sizes other than what the PCG32 and PCG64 naturally produce.

Methods

impl<T: PCG> AnyPCG<T>

pub fn new(pcg: T) -> Self

Creates a new any-size generator from a fixed-size one.

pub fn next_bool(&mut self) -> bool

Runs the generator once, if needed, and gets a bool as output.

pub fn next_char(&mut self) -> char

Runs the generator once, if needed, and gets a char as output.

This function tries to use as few random bits as possible.

There are 1112063, a little over a million, valid Unicode scalar values that could be generated. The largest valid scalar is U+10FFFF. The surrogate scalars in the middle from U+D800 to U+DFFF are invalid.

This amount of state is representable in roughly 20.0848 bits. Given that and rounding up, this function uses at least 21 random bits. If the generated bit pattern does not create a valid char, then the least significant bit will be discarded and a new most significant bit will be generated. This process is repeated until a valid bit pattern has been generated, wasting only one extra bit at a time.

This function will always terminate eventually.

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

Fill a mutable byte slice from this generator.

pub fn next_u8(&mut self) -> u8

Runs the generator once, if needed, and gets a u8 as output.

pub fn next_u16(&mut self) -> u16

Runs the generator once, if needed, and gets a u16 as output.

pub fn next_u32(&mut self) -> u32

Runs the generator once, if needed, and gets a u32 as output.

impl AnyPCG<PCG64>

pub fn next_u64(&mut self) -> u64

Runs the generator once, if needed, and gets a u64 as output.

pub fn next_u128(&mut self) -> u128

Runs the generator one or two times and gets a u128 as output.

impl AnyPCG<PCG32>

pub fn next_u64(&mut self) -> u64

Runs the generator one or two times and gets a u64 as output.

pub fn next_u128(&mut self) -> u128

Runs the generator two to four times and gets a u128 as output.

Trait Implementations

impl<T: PartialEq + PCG> PartialEq<AnyPCG<T>> for AnyPCG<T>

fn eq(&self, other: &AnyPCG<T>) -> bool

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

fn ne(&self, other: &AnyPCG<T>) -> bool

This method tests for !=.

impl<T: Eq + PCG> Eq for AnyPCG<T>

impl<T: Hash + PCG> Hash for AnyPCG<T>

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, 

Feeds a slice of this type into the given [Hasher].

impl<T: Debug + PCG> Debug for AnyPCG<T>

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

Formats the value using the given formatter.

impl<T: Clone + PCG> Clone for AnyPCG<T>

fn clone(&self) -> AnyPCG<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Default + PCG> Default for AnyPCG<T>

fn default() -> AnyPCG<T>

Returns the "default value" for a type.