# [−][src]Trait rand::SeedableRng

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

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

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).

The `FromEntropy` trait from the `rand` crate is automatically implemented for every type implementing `SeedableRng`, providing a convenient `from_entropy()` constructor.

## Associated Types

### `type Seed: Sized + Default + AsMut<[u8]>`

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]`.

# Implementing `SeedableRng` for RNGs with large seeds

Note that the required traits `core::default::Default` and `core::convert::AsMut<u8>` are not implemented for large arrays `[u8; N]` with `N` > 32. To be able to implement the traits required by `SeedableRng` for RNGs with such large seeds, the newtype pattern can be used:

    use rand_core::SeedableRng;

    const N: usize = 64;
    pub struct MyRngSeed(pub [u8; N]);
    pub struct MyRng(MyRngSeed);

    impl Default for MyRngSeed {
        fn default() -> MyRngSeed {
            MyRngSeed([0; N])
        }
    }

    impl AsMut<[u8]> for MyRngSeed {
        fn as_mut(&mut self) -> &mut [u8] {
            &mut self.0
        }
    }

    impl SeedableRng for MyRng {
        type Seed = MyRngSeed;

        fn from_seed(seed: MyRngSeed) -> MyRng {
            MyRng(seed)
        }
    }

Loading content...

## Required methods

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

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.

PRNG implementations should make sure `from_seed` never panics. In the case that some special values (like an all zero seed) are not viable seeds it is preferable to map these to alternative constant value(s), for example `0xBAD5EEDu32` or `0x0DDB1A5E5BAD5EEDu64` ("odd biases? bad seed"). This is assuming only a small number of values must be rejected.

Loading content...

## Provided methods

### `fn seed_from_u64(state: u64) -> Self`

Create a new PRNG using a `u64` seed.

This is a convenience-wrapper around `from_seed` to allow construction of any `SeedableRng` from a simple `u64` value. It is designed such that low Hamming Weight numbers like 0 and 1 can be used and should still result in good, independent seeds to the PRNG which is returned.

This is not suitable for cryptography, as should be clear given that the input size is only 64 bits.

Implementations for PRNGs may provide their own implementations of this function, but the default implementation should be good enough for all purposes. Changing the implementation of this function should be considered a value-breaking change.

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

Create a new PRNG seeded from another `Rng`.

This is the recommended way to initialize PRNGs with fresh entropy. The `FromEntropy` trait from the `rand` crate provides a convenient `from_entropy` 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` from the `rand_os` crate 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 Xorshift RNG from another Xorshift RNG, 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.

Loading content...

## Implementations on Foreign Types

### `impl<R> SeedableRng for BlockRng<R> where
R: BlockRngCore + SeedableRng,` [src]

#### `type Seed = <R as SeedableRng>::Seed`

#### `fn from_seed(seed: <BlockRng<R> as SeedableRng>::Seed) -> BlockRng<R>`[src]

#### `fn seed_from_u64(seed: u64) -> BlockRng<R>`[src]

#### `fn from_rng<S>(rng: S) -> Result<BlockRng<R>, Error> where
S: RngCore,` [src]

### `impl<R> SeedableRng for BlockRng64<R> where
R: BlockRngCore + SeedableRng,` [src]

#### `type Seed = <R as SeedableRng>::Seed`

#### `fn from_seed(seed: <BlockRng64<R> as SeedableRng>::Seed) -> BlockRng64<R>`[src]

#### `fn seed_from_u64(seed: u64) -> BlockRng64<R>`[src]

#### `fn from_rng<S>(rng: S) -> Result<BlockRng64<R>, Error> where
S: RngCore,` [src]

### `impl SeedableRng for IsaacCore`[src]

#### `type Seed = [u8; 32]`

#### `fn from_seed(seed: <IsaacCore as SeedableRng>::Seed) -> IsaacCore`[src]

#### `fn seed_from_u64(seed: u64) -> IsaacCore`[src]

Create an ISAAC random number generator using an `u64` as seed. If `seed == 0` this will produce the same stream of random numbers as the reference implementation when used unseeded.

#### `fn from_rng<R>(rng: R) -> Result<IsaacCore, Error> where
R: RngCore,` [src]

### `impl SeedableRng for IsaacRng`[src]

#### `type Seed = <IsaacCore as SeedableRng>::Seed`

#### `fn from_seed(seed: <IsaacRng as SeedableRng>::Seed) -> IsaacRng`[src]

#### `fn seed_from_u64(seed: u64) -> IsaacRng`[src]

Create an ISAAC random number generator using an `u64` as seed. If `seed == 0` this will produce the same stream of random numbers as the reference implementation when used unseeded.

#### `fn from_rng<S>(rng: S) -> Result<IsaacRng, Error> where
S: RngCore,` [src]

### `impl SeedableRng for Isaac64Rng`[src]

#### `type Seed = <Isaac64Core as SeedableRng>::Seed`

#### `fn from_seed(seed: <Isaac64Rng as SeedableRng>::Seed) -> Isaac64Rng`[src]

#### `fn seed_from_u64(seed: u64) -> Isaac64Rng`[src]

Create an ISAAC random number generator using an `u64` as seed. If `seed == 0` this will produce the same stream of random numbers as the reference implementation when used unseeded.

#### `fn from_rng<S>(rng: S) -> Result<Isaac64Rng, Error> where
S: RngCore,` [src]

### `impl SeedableRng for Isaac64Core`[src]

#### `type Seed = [u8; 32]`

#### `fn from_seed(seed: <Isaac64Core as SeedableRng>::Seed) -> Isaac64Core`[src]

#### `fn seed_from_u64(seed: u64) -> Isaac64Core`[src]

#### `fn from_rng<R>(rng: R) -> Result<Isaac64Core, Error> where
R: RngCore,` [src]

### `impl SeedableRng for ChaChaCore`[src]

#### `type Seed = [u8; 32]`

#### `fn from_seed(seed: <ChaChaCore as SeedableRng>::Seed) -> ChaChaCore`[src]

### `impl SeedableRng for ChaChaRng`[src]

#### `type Seed = <ChaChaCore as SeedableRng>::Seed`

#### `fn from_seed(seed: <ChaChaRng as SeedableRng>::Seed) -> ChaChaRng`[src]

#### `fn from_rng<R>(rng: R) -> Result<ChaChaRng, Error> where
R: RngCore,` [src]

### `impl SeedableRng for Hc128Core`[src]

#### `type Seed = [u8; 32]`

#### `fn from_seed(seed: <Hc128Core as SeedableRng>::Seed) -> Hc128Core`[src]

Create an HC-128 random number generator with a seed. The seed has to be 256 bits in length, matching the 128 bit `key` followed by 128 bit `iv` when HC-128 where to be used as a stream cipher.

### `impl SeedableRng for Hc128Rng`[src]

#### `type Seed = <Hc128Core as SeedableRng>::Seed`

#### `fn from_seed(seed: <Hc128Rng as SeedableRng>::Seed) -> Hc128Rng`[src]

#### `fn from_rng<R>(rng: R) -> Result<Hc128Rng, Error> where
R: RngCore,` [src]

### `impl SeedableRng for Lcg64Xsh32`[src]

We use a single 127-bit seed to initialise the state and select a stream. One `seed` bit (lowest bit of `seed[8]`) is ignored.

#### `type Seed = [u8; 16]`

#### `fn from_seed(seed: <Lcg64Xsh32 as SeedableRng>::Seed) -> Lcg64Xsh32`[src]

### `impl SeedableRng for Mcg128Xsl64`[src]

We use a single 126-bit seed to initialise the state and select a stream. Two `seed` bits (lowest order of last byte) are ignored.

#### `type Seed = [u8; 16]`

#### `fn from_seed(seed: <Mcg128Xsl64 as SeedableRng>::Seed) -> Mcg128Xsl64`[src]

### `impl SeedableRng for XorShiftRng`[src]

#### `type Seed = [u8; 16]`

#### `fn from_seed(seed: <XorShiftRng as SeedableRng>::Seed) -> XorShiftRng`[src]

#### `fn from_rng<R>(rng: R) -> Result<XorShiftRng, Error> where
R: RngCore,` [src]

Loading content...

## Implementors

### `impl SeedableRng for SmallRng`[src]

#### `type Seed = <Pcg64Mcg as SeedableRng>::Seed`

#### `fn from_seed(seed: Self::Seed) -> Self`[src]

#### `fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error>`[src]

### `impl SeedableRng for StdRng`[src]

#### `type Seed = <Hc128Rng as SeedableRng>::Seed`

#### `fn from_seed(seed: Self::Seed) -> Self`[src]

#### `fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error>`[src]

Loading content...

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)