Struct rand::rngs::SmallRng

pub struct SmallRng(/* private fields */);

A small-state, fast, non-crypto, non-portable PRNG

This is the “standard small” RNG, a generator with the following properties:

• Non-portable: any future library version may replace the algorithm and results may be platform-dependent. (For a small portable generator, use the rand_pcg or rand_xoshiro crate.)
• Non-cryptographic: output is easy to predict (insecure)
• Quality: statistically good quality
• Fast: the RNG is fast for both bulk generation and single values, with consistent cost of method calls
• Fast initialization
• Small state: little memory usage (current state size is 16-32 bytes depending on platform)

The current algorithm is Xoshiro256PlusPlus on 64-bit platforms and Xoshiro128PlusPlus on 32-bit platforms. Both are also implemented by the rand_xoshiro crate.

Seeding (construction)

This generator implements the SeedableRng trait. All methods are suitable for seeding, but note that, even with a fixed seed, output is not portable. Some suggestions:

1. Seed from an integer via seed_from_u64. This uses a hash function internally to yield a (typically) good seed from any input.

   let rng = SmallRng::seed_from_u64(1);

2. With a fresh seed, direct from the OS (implies a syscall):

   let rng = SmallRng::from_os_rng();

3. Via SmallRng::from_thread_rng:

   let rng = SmallRng::from_thread_rng();

See also Seeding RNGs in the book.

Generation

The generators implements RngCore and thus also Rng. See also the Random Values chapter in the book.

Implementations

impl SmallRng

pub fn from_thread_rng() -> Self

Construct an instance seeded from the thread-local RNG

Panics

This method panics only if thread_rng fails to initialize.

Trait Implementations

impl Clone for SmallRng

fn clone(&self) -> SmallRng

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SmallRng

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

Formats the value using the given formatter.

impl PartialEq for SmallRng

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

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

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

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

impl RngCore for SmallRng

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, dest: &mut [u8])

Fill dest with random data.

impl SeedableRng for SmallRng

type Seed = [u8; 32]

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(state: u64) -> Self

Create a new PRNG using a u64 seed.

fn from_rng(rng: impl RngCore) -> Self

Create a new PRNG seeded from an infallible Rng.

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

where R: TryRngCore,

Create a new PRNG seeded from a potentially fallible Rng.

fn from_os_rng() -> Self

Creates a new instance of the RNG seeded via getrandom.

fn try_from_os_rng() -> Result<Self, Error>

Creates a new instance of the RNG seeded via getrandom without unwrapping potential getrandom errors.

impl TryRngCore for SmallRng

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 dest entirely with random data.

fn unwrap_err(self) -> UnwrapErr<Self>

where Self: Sized,

Wrap RNG with the UnwrapErr wrapper.

fn read_adapter(&mut self) -> RngReadAdapter<'_, Self>

where Self: Sized,

Convert an RngCore to a RngReadAdapter.

impl Eq for SmallRng

impl StructuralPartialEq for SmallRng