You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
136 lines
5.8 KiB
Plaintext
136 lines
5.8 KiB
Plaintext
---
|
|
source: tests/output.rs
|
|
expression: "get_stdout(path, &[\"rand_core::RngCore\"])"
|
|
|
|
---
|
|
rand_core Trait rand_core::RngCore rusty-man
|
|
|
|
SYNOPSIS
|
|
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>;
|
|
}
|
|
|
|
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`][1] 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))
|
|
}
|
|
}
|
|
|
|
[1] https://docs.rs/rand
|
|
|
|
METHODS
|
|
Required Methods
|
|
next_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 `fill_bytes`.
|
|
|
|
next_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 `next_u32` or via
|
|
`fill_bytes`.
|
|
|
|
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).
|
|
|
|
try_fill_bytes
|
|
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.
|
|
|
|
IMPLEMENTATIONS
|
|
Trait Implementations
|
|
Read
|
|
impl Read for dyn RngCore
|
|
|
|
|