Trait rand_core::SeedableRng [−] [src]

pub trait SeedableRng: Sized {
    type Seed: Sized + Default + AsMut<[u8]>;
    fn from_seed(seed: Self::Seed) -> Self;

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

A random number generator that can be explicitly seeded.

This trait encapsulates the low-level functionality common to all pseudo-random number generators (PRNGs, or algorithmic generators).

rand's NewRng trait is automatically implemented for every type implementing SeedableRng, providing a convenient new() method.

Associated Types

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

It is recommended to seed PRNGs with a seed of at least circa 100 bits, which means an array of [u8; 12] or greater to avoid picking RNGs with partially overlapping periods.

For cryptographic RNG's a seed of 256 bits is recommended, [u8; 32].

Required Methods

Create a new PRNG using the given seed.

PRNG implementations are allowed to assume that bits in the seed are well distributed. That means usually that the number of one and zero bits are about equal, and values like 0, 1 and (size - 1) are unlikely.

PRNG implementations are recommended to be reproducible. A PRNG seeded using this function with a fixed seed should produce the same sequence of output in the future and on different architectures (with for example different endianness).

It is however not required that this function yield the same state as a reference implementation of the PRNG given equivalent seed; if necessary another constructor replicating behaviour from a reference implementation can be added.

Provided Methods

Create a new PRNG seeded from another Rng.

This is the recommended way to initialize PRNGs with fresh entropy. The NewRng trait provides a convenient new method based on from_rng.

Usage of this method is not recommended when reproducibility is required since implementing PRNGs are not required to fix Endianness and are allowed to modify implementations in new releases.

It is important to use a good source of randomness to initialize the PRNG. Cryptographic PRNG may be rendered insecure when seeded from a non-cryptographic PRNG or with insufficient entropy. Many non-cryptographic PRNGs will show statistical bias in their first results if their seed numbers are small or if there is a simple pattern between them.

Prefer to seed from a strong external entropy source like OsRng or from a cryptographic PRNG; if creating a new generator for cryptographic uses you must seed from a strong source.

Seeding a small PRNG from another small PRNG is possible, but something to be careful with. An extreme example of how this can go wrong is seeding an XorShiftRng from another XorShiftRng, which will effectively clone the generator. In general seeding from a generator which is hard to predict is probably okay.

PRNG implementations are allowed to assume that a good RNG is provided for seeding, and that it is cryptographically secure when appropriate.

Implementors