Skip to main content

TryRng

rand

Trait TryRng 

Source 
pub trait TryRng {
    type Error: Error;

    // Required methods
    fn try_next_u32(&mut self) -> Result<u32, Self::Error>;
    fn try_next_u64(&mut self) -> Result<u64, Self::Error>;
    fn try_fill_bytes(&mut self, dst: &mut [u8]) -> Result<(), Self::Error>;
}
Expand description

Base trait for random number generators and random data sources

This trait provides a base interface designed to support efficient usage of (u32, u64) word generators, block generators and random data sources. There is no required relationship between the output of each method or any requirement to use all generated random bits; for example an implementation of try_fill_bytes may discard some generated bytes to avoid storing a partially used word or block.

§Requirements

§Quality and length

Implementions should produce bits uniformly: each output value should be equally likely, without observable patterns in successive outputs or between the output streams of multiple instances of an implementation using different seeds or streams (where supported by the implementation).

Pathological implementations (e.g. constant or counting generators which rarely change some bits) may cause issues in consumers of random data, for example dead-locks in rejection samplers and obviously non-random output (e.g. a counting generator may result in apparently-constant output from a uniform-ranged distribution).

Cryptographically unpredictable output is not a requirement of this trait, but is a requirement of TryCryptoRng.

In practice, most implementations are pseudo-random number generators with a finite period or cycle length, and (among non-cryptographic PRNGs) statistical anomalies may appear long before a cycle occurs. An implementation should ensure its period is sufficiently long that no anomalies are likely to appear in usage and/or document its limitations.

For more on PRNG quality and period, see The Rust Rand Book: Quality.

§Reproducibility

Algorithmic generators implementing SeedableRng should normally have portable, reproducible output, i.e. fix Endianness when converting values to avoid platform differences, and avoid making any changes which affect output (except by communicating that the release has breaking changes). See also The Rust Rand Book: Reproducibility.

§Usage

Often, usage of the infallible trait Rng or its extension trait rand::Rng is preferred to direct usage of TryRng. Many implementations of TryRng (those with type Error = Infallible) already implement Rng; in other cases UnwrapErr may be used to obtain an implementation of Rng.

§Implementing TryRng

Most algorithmic generators (i.e. pseudo-random number generators or PRNGs) never fail; in this case type Error should be Infallible; in this case trait Rng is implemented automatically. Cycling is not considered an error.

Small PRNGs often yield either u32 or u64 natively. Module crate::utils provides utilities to help implement other methods.

Byte sources may implement try_fill_bytes natively. Module crate::utils provides utilities to help implement other methods.

Block generators (which produce [u32; N] or [u64; N] for some fixed N) should make use of the crate::block module.

With regards to other traits:

  • Do not implement Default for seedable pseudorandom generators, though the trait may be implemented for stateless interfaces and auto-seeding generators.
  • Do implement SeedableRng for seedable pseudorandom generators. See Reproducibility above.
  • Implement Clone for non-cryptographic PRNGs but consider not doing so for cryptographic generators to avoid the risk of key-stream duplication.
  • Do not implement Copy since accidental copies may cause repeated values.
  • Implement Debug, except that cryptographic PRNGs should use a custom implementation which avoids leaking internal state (or the subset of this derived from the key).
  • Eq and PartialEq could be implemented, but are probably not useful.

Required Associated Types§

Source

type Error: Error

The type returned in the event of a RNG error.

Use type Infallible (re-exported by rand_core) for infallible implementations.

Required Methods§

Source

fn try_next_u32(&mut self) -> Result<u32, Self::Error>

Return the next random u32.

Source

fn try_next_u64(&mut self) -> Result<u64, Self::Error>

Return the next random u64.

Source

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

Fill dst entirely with random data.

Implementors§