Trait rand::RngCore [−][src]
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.
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 throughDebug
).Serialize
andDeserialize
(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 implementSeedableRng
, to guide users towards proper seeding. External / hardware RNGs can choose to implementDefault
. Eq
andPartialEq
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
pub fn next_u32(&mut self) -> u32
[src]
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
.
pub fn next_u64(&mut self) -> u64
[src]
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
.
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
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
or
via 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).
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
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 RngCore::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.
Trait Implementations
impl Read for dyn RngCore + 'static
[src]
pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
[src]
pub fn read_vectored(
&mut self,
bufs: &mut [IoSliceMut<'_>]
) -> Result<usize, Error>
1.36.0[src]
&mut self,
bufs: &mut [IoSliceMut<'_>]
) -> Result<usize, Error>
pub fn is_read_vectored(&self) -> bool
[src]
pub unsafe fn initializer(&self) -> Initializer
[src]
pub fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
1.0.0[src]
pub fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
1.0.0[src]
pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
1.6.0[src]
pub fn by_ref(&mut self) -> &mut Self
1.0.0[src]
pub fn bytes(self) -> Bytes<Self>
1.0.0[src]
pub fn chain<R>(self, next: R) -> Chain<Self, R> where
R: Read,
1.0.0[src]
R: Read,
pub fn take(self, limit: u64) -> Take<Self>
1.0.0[src]
Implementations on Foreign Types
impl<R> RngCore for BlockRng64<R> where
R: BlockRngCore<Item = u64>,
<R as BlockRngCore>::Results: AsRef<[u64]>,
<R as BlockRngCore>::Results: AsMut<[u64]>,
[src]
R: BlockRngCore<Item = u64>,
<R as BlockRngCore>::Results: AsRef<[u64]>,
<R as BlockRngCore>::Results: AsMut<[u64]>,
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
impl<'a, R> RngCore for &'a mut R where
R: RngCore + ?Sized,
[src]
R: RngCore + ?Sized,
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
impl<R> RngCore for Box<R, Global> where
R: RngCore + ?Sized,
[src]
R: RngCore + ?Sized,
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
impl<R> RngCore for BlockRng<R> where
R: BlockRngCore<Item = u32>,
<R as BlockRngCore>::Results: AsRef<[u32]>,
<R as BlockRngCore>::Results: AsMut<[u32]>,
[src]
R: BlockRngCore<Item = u32>,
<R as BlockRngCore>::Results: AsRef<[u32]>,
<R as BlockRngCore>::Results: AsMut<[u32]>,
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
impl RngCore for ChaCha8Rng
[src]
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, bytes: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, bytes: &mut [u8]) -> Result<(), Error>
[src]
impl RngCore for ChaCha12Rng
[src]
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, bytes: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, bytes: &mut [u8]) -> Result<(), Error>
[src]
impl RngCore for ChaCha20Rng
[src]
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, bytes: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, bytes: &mut [u8]) -> Result<(), Error>
[src]
Implementors
impl RngCore for StepRng
[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 RngCore for OsRng
[src]
pub fn next_u32(&mut self) -> u32
[src]
pub fn next_u64(&mut self) -> u64
[src]
pub fn fill_bytes(&mut self, dest: &mut [u8])
[src]
pub fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
impl RngCore for SmallRng
[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 RngCore for StdRng
[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 RngCore for ThreadRng
[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, Rsdr: RngCore> RngCore for ReseedingRng<R, Rsdr> where
R: BlockRngCore<Item = u32> + SeedableRng,
<R as BlockRngCore>::Results: AsRef<[u32]> + AsMut<[u32]>,
[src]
R: BlockRngCore<Item = u32> + SeedableRng,
<R as BlockRngCore>::Results: AsRef<[u32]> + AsMut<[u32]>,