# [−] [src] Trait rand_core::RngCore

    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>;
    }

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, [`CryptoRng`]s 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`

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`][impls::next_u32_via_fill].

### `fn next_u64(&mut self) -> u64`

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`][impls::next_u64_via_u32] or via [`fill_bytes`][impls::next_u64_via_fill].

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

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*`][impls::fill_bytes_via_next] or via [`try_fill_bytes`][RngCore::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>`

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

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

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

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

#### `fn read_to_end(&mut self, buf: &mut Vec<u8>) -> 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 Self` 1.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<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...

# 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`)