Trait rand_core::RngCore[][src]

pub trait RngCore {
    fn next_u32(&mut self) -> u32;
fn next_u64(&mut self) -> u64;
fn fill_bytes(&mut self, dest: &mut [u8]);
fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>; }
Expand description

The core of a random number generator.

This trait encapsulates the low-level functionality common to all generators, and is the “back end”, to be implemented by generators. End users should normally use the Rng trait from the rand crate, which is automatically implemented for every type implementing RngCore.

Three different methods for generating random data are provided since the optimal implementation of each is dependent on the type of generator. There is no required relationship between the output of each; e.g. many implementations of fill_bytes consume a whole number of u32 or u64 values and drop any remaining unused bytes.

The try_fill_bytes method is a variant of fill_bytes allowing error handling; it is not deemed sufficiently useful to add equivalents for next_u32 or next_u64 since the latter methods are almost always used with algorithmic generators (PRNGs), which are normally infallible.

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

Typically implementators will implement only one of the methods available in this trait directly, then use the helper functions from the impls module to implement the other methods.

It is recommended that implementations also implement:

  • Debug with a custom implementation which does not print any internal state (at least, CryptoRngs should not risk leaking state through Debug).
  • Serialize and Deserialize (from Serde), preferably making Serde support optional at the crate level in PRNG libs.
  • Clone, if possible.
  • never implement Copy (accidental copies may cause repeated values).
  • do not implement Default for pseudorandom generators, but instead implement SeedableRng, to guide users towards proper seeding. External / hardware RNGs can choose to implement Default.
  • Eq and PartialEq could be implemented, but are probably not useful.

Example

A simple example, obviously not generating very random output:

#![allow(dead_code)]
use rand_core::{RngCore, Error, impls};

struct CountingRng(u64);

impl RngCore for CountingRng {
    fn next_u32(&mut self) -> u32 {
        self.next_u64() as u32
    }

    fn next_u64(&mut self) -> u64 {
        self.0 += 1;
        self.0
    }

    fn fill_bytes(&mut self, dest: &mut [u8]) {
        impls::fill_bytes_via_next(self, dest)
    }

    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        Ok(self.fill_bytes(dest))
    }
}

Required methods

fn next_u32(&mut self) -> u32[src]

Expand description

Return the next random u32.

RNGs must implement at least one method from this trait directly. In the case this method is not implemented directly, it can be implemented using self.next_u64() as u32 or via fill_bytes.

fn next_u64(&mut self) -> u64[src]

Expand description

Return the next random u64.

RNGs must implement at least one method from this trait directly. In the case this method is not implemented directly, it can be implemented via next_u32 or via fill_bytes.

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

Expand description

Fill dest with random data.

RNGs must implement at least one method from this trait directly. In the case this method is not implemented directly, it can be implemented via next_u* or via try_fill_bytes; if this generator can fail the implementation must choose how best to handle errors here (e.g. panic with a descriptive message or log a warning and retry a few times).

This method should guarantee that dest is entirely filled with new data, and may panic if this is impossible (e.g. reading past the end of a file that is being used as the source of randomness).

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

Expand description

Fill dest entirely with random data.

This is the only method which allows an RNG to report errors while generating random data thus making this the primary method implemented by external (true) RNGs (e.g. OsRng) which can fail. It may be used directly to generate keys and to seed (infallible) PRNGs.

Other than error handling, this method is identical to fill_bytes; thus this may be implemented using Ok(self.fill_bytes(dest)) or fill_bytes may be implemented with self.try_fill_bytes(dest).unwrap() or more specific error handling.

Loading content...

Trait Implementations

impl Read for dyn RngCore[src]

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>[src]

Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>1.36.0[src]

Like read, except that it reads into a slice of buffers. Read more

fn is_read_vectored(&self) -> bool[src]

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation. Read more

unsafe fn initializer(&self) -> Initializer[src]

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory. Read more

fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>1.0.0[src]

Read all bytes until EOF in this source, placing them into buf. Read more

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>1.0.0[src]

Read all bytes until EOF in this source, appending them to buf. Read more

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>1.6.0[src]

Read the exact number of bytes required to fill buf. Read more

fn by_ref(&mut self) -> &mut Self1.0.0[src]

Creates a “by reference” adaptor for this instance of Read. Read more

fn bytes(self) -> Bytes<Self>1.0.0[src]

Transforms this Read instance to an Iterator over its bytes. Read more

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read
1.0.0[src]

Creates an adaptor which will chain this stream with another. Read more

fn take(self, limit: u64) -> Take<Self>1.0.0[src]

Creates an adaptor which will read at most limit bytes from it. Read more

Implementations on Foreign Types

impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R[src]

fn next_u32(&mut self) -> u32[src]

fn next_u64(&mut self) -> u64[src]

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

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

impl<R: RngCore + ?Sized> RngCore for Box<R>[src]

fn next_u32(&mut self) -> u32[src]

fn next_u64(&mut self) -> u64[src]

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

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

Loading content...

Implementors

impl RngCore for OsRng[src]

fn next_u32(&mut self) -> u32[src]

fn next_u64(&mut self) -> u64[src]

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

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

impl<R: BlockRngCore<Item = u32>> RngCore for BlockRng<R> where
    <R as BlockRngCore>::Results: AsRef<[u32]> + AsMut<[u32]>, 
[src]

fn next_u32(&mut self) -> u32[src]

fn next_u64(&mut self) -> u64[src]

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

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

impl<R: BlockRngCore<Item = u64>> RngCore for BlockRng64<R> where
    <R as BlockRngCore>::Results: AsRef<[u64]> + AsMut<[u64]>, 
[src]

fn next_u32(&mut self) -> u32[src]

fn next_u64(&mut self) -> u64[src]

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

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

Loading content...