Struct rand::rngs::SmallRng

source ·
pub struct SmallRng(/* private fields */);
Expand description

A small-state, fast non-crypto PRNG

SmallRng may be a good choice when a PRNG with small state, cheap initialization, good statistical quality and good performance are required. Note that depending on the application, StdRng may be faster on many modern platforms while providing higher-quality randomness. Furthermore, SmallRng is not a good choice when:

  • Security against prediction is important. Use StdRng instead.
  • Seeds with many zeros are provided. In such cases, it takes SmallRng about 10 samples to produce 0 and 1 bits with equal probability. Either provide seeds with an approximately equal number of 0 and 1 (for example by using SeedableRng::from_entropy or SeedableRng::seed_from_u64), or use StdRng instead.

The algorithm is deterministic but should not be considered reproducible due to dependence on platform and possible replacement in future library versions. For a reproducible generator, use a named PRNG from an external crate, e.g. rand_xoshiro or rand_chacha. Refer also to The Book.

The PRNG algorithm in SmallRng is chosen to be efficient on the current platform, without consideration for cryptography or security. The size of its state is much smaller than StdRng. The current algorithm is Xoshiro256PlusPlus on 64-bit platforms and Xoshiro128PlusPlus on 32-bit platforms. Both are also implemented by the rand_xoshiro crate.

§Examples

Initializing SmallRng with a random seed can be done using SeedableRng::from_entropy:

use rand::{Rng, SeedableRng};
use rand::rngs::SmallRng;

// Create small, cheap to initialize and fast RNG with a random seed.
// The randomness is supplied by the operating system.
let mut small_rng = SmallRng::from_entropy();

When initializing a lot of SmallRng’s, using thread_rng can be more efficient:

use rand::{SeedableRng, thread_rng};
use rand::rngs::SmallRng;

// Create a big, expensive to initialize and slower, but unpredictable RNG.
// This is cached and done only once per thread.
let mut thread_rng = thread_rng();
// Create small, cheap to initialize and fast RNGs with random seeds.
// One can generally assume this won't fail.
let rngs: Vec<SmallRng> = (0..10)
    .map(|_| SmallRng::from_rng(&mut thread_rng).unwrap())
    .collect();

Trait Implementations§

source§

impl Clone for SmallRng

source§

fn clone(&self) -> SmallRng

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for SmallRng

source§

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

Formats the value using the given formatter. Read more
source§

impl PartialEq for SmallRng

source§

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

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

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.
source§

impl RngCore for SmallRng

source§

fn next_u32(&mut self) -> u32

Return the next random u32. Read more
source§

fn next_u64(&mut self) -> u64

Return the next random u64. Read more
source§

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

Fill dest with random data. Read more
source§

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

Fill dest entirely with random data. Read more
source§

impl SeedableRng for SmallRng

§

type Seed = <Xoshiro256PlusPlus as SeedableRng>::Seed

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

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

Create a new PRNG using the given seed. Read more
source§

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

Create a new PRNG seeded from another Rng. Read more
source§

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed. Read more
source§

fn from_entropy() -> Self

Creates a new instance of the RNG seeded via getrandom. Read more
source§

impl Eq for SmallRng

source§

impl StructuralPartialEq for SmallRng

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<R> Rng for R
where R: RngCore + ?Sized,

source§

fn gen<T>(&mut self) -> T

Return a random value supporting the Standard distribution. Read more
source§

fn gen_range<T, R>(&mut self, range: R) -> T
where T: SampleUniform, R: SampleRange<T>,

Generate a random value in the given range. Read more
source§

fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T

Sample a new value, using the given distribution. Read more
source§

fn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T>
where D: Distribution<T>, Self: Sized,

Create an iterator that generates values using the given distribution. Read more
source§

fn fill<T: Fill + ?Sized>(&mut self, dest: &mut T)

Fill any type implementing Fill with random data Read more
source§

fn try_fill<T: Fill + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error>

Fill any type implementing Fill with random data Read more
source§

fn gen_bool(&mut self, p: f64) -> bool

Return a bool with a probability p of being true. Read more
source§

fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool

Return a bool with a probability of numerator/denominator of being true. I.e. gen_ratio(2, 3) has chance of 2 in 3, or about 67%, of returning true. If numerator == denominator, then the returned value is guaranteed to be true. If numerator == 0, then the returned value is guaranteed to be false. Read more
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V