[−][src]Trait rand_core::RngCore
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 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 implement [SeedableRng
], 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
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
.
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
or via
fill_bytes
.
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*
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>
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.
Trait Implementations
impl Read for dyn RngCore
[src]
fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
[src]
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]
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]
R: Read,
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]
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]
<R as BlockRngCore>::Results: AsRef<[u32]> + AsMut<[u32]>,
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]
<R as BlockRngCore>::Results: AsRef<[u64]> + AsMut<[u64]>,