pub trait RngCore {
// Required methods
fn next_u32(&mut self) -> u32;
fn next_u64(&mut self) -> u64;
fn fill_bytes(&mut self, dst: &mut [u8]);
}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 same can happen with the
next_u32 and next_u64 methods, implementations may discard some
random bits for efficiency.
Implementers should produce bits uniformly. Pathological RNGs (e.g. always
returning the same value, or never setting certain bits) can break rejection
sampling used by random distributions, and also break other RNGs when
seeding them via SeedableRng::from_rng.
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 an RNG 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.
Implementors of RngCore SHOULD also implement the TryRngCore
trait with the Error associated type being equal to Infallible.
It can be done using the impl_try_rng_from_rng_core! macro.
It is recommended that implementations also implement:
Debugwith a custom implementation which does not print any internal state (at least,CryptoRngs should not risk leaking state throughDebug).SerializeandDeserialize(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
Defaultfor pseudorandom generators, but instead implementSeedableRng, to guide users towards proper seeding. External / hardware RNGs can choose to implementDefault. EqandPartialEqcould be implemented, but are probably not useful.
§Example
A simple example, obviously not generating very random output:
#![allow(dead_code)]
use rand_core::{RngCore, 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, dst: &mut [u8]) {
impls::fill_bytes_via_next(self, dst)
}
}
rand_core::impl_try_rng_from_rng_core!(CountingRng);Required Methods§
sourcefn next_u32(&mut self) -> u32
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 impls::next_u32_via_fill.
sourcefn next_u64(&mut self) -> u64
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 impls::next_u64_via_u32 or via impls::next_u64_via_fill.
sourcefn fill_bytes(&mut self, dst: &mut [u8])
fn fill_bytes(&mut self, dst: &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 impls::fill_bytes_via_next.
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).