Trait rand::Rng
[−]
[src]
pub trait Rng { fn next_u32(&mut self) -> u32; fn next_u64(&mut self) -> u64 { ... } fn next_f32(&mut self) -> f32 { ... } fn next_f64(&mut self) -> f64 { ... } fn fill_bytes(&mut self, dest: &mut [u8]) { ... } fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> { ... } }
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. Several extension traits exist:
-
SampleRng
provides high-level generic functionality built on top ofRng
-
SeedableRng
is another "back end" trait covering creation and seeding of algorithmic RNGs (PRNGs) -
NewRng
is a high-level trait providing a convenient way to create freshly-seeded PRNGs
Required Methods
fn next_u32(&mut self) -> u32
Return the next random u32
.
Implementations of this trait must implement at least one of
next_u32
, next_u64
and fill_bytes
directly. In the case this
function is not implemented directly, it can be implemented using
self.next_u64() as u32
or via fill_bytes
(TODO: expose helper
function).
Provided Methods
fn next_u64(&mut self) -> u64
Return the next random u64
.
Implementations of this trait must implement at least one of
next_u32
, next_u64
and fill_bytes
directly. In the case this
function is not implemented directly, the default implementation will
generate values via next_u32
in little-endian fashion, or this
function can be implemented via fill_bytes
(TODO: expose helper
function).
Types wrapping an inner RNG must not use the default implementation, since the inner RNG's implementation may produce different values.
fn next_f32(&mut self) -> f32
Return the next random f32 selected from the half-open
interval [0, 1)
.
This uses a technique described by Saito and Matsumoto at MCQMC'08. Given that the IEEE floating point numbers are uniformly distributed over [1,2), we generate a number in this range and then offset it onto the range [0,1). Our choice of bits (masking v. shifting) is arbitrary and should be immaterial for high quality generators. For low quality generators (ex. LCG), prefer bitshifting due to correlation between sequential low order bits.
See: A PRNG specialized in double precision floating point numbers using an affine transition
- http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/dSFMT.pdf
- http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/dSFMT-slide-e.pdf
By default this is implemented in terms of next_u32
, but a
random number generator which can generate numbers satisfying
the requirements directly can overload this for performance.
It is required that the return value lies in [0, 1)
.
See Closed01
for the closed interval [0,1]
, and
Open01
for the open interval (0,1)
.
fn next_f64(&mut self) -> f64
Return the next random f64 selected from the half-open
interval [0, 1)
.
By default this is implemented in terms of next_u64
, but a
random number generator which can generate numbers satisfying
the requirements directly can overload this for performance.
It is required that the return value lies in [0, 1)
.
See Closed01
for the closed interval [0,1]
, and
Open01
for the open interval (0,1)
.
fn fill_bytes(&mut self, dest: &mut [u8])
Fill dest
with random data.
Implementations of this trait must implement at least one of
next_u32
, next_u64
and fill_bytes
directly. In the case this
function is not implemented directly, the default implementation will
generate values via next_u64
in little-endian fashion.
(TODO: expose helper function to allow implementation via next_u32
.)
There is no requirement on how this method generates values relative to
next_u32
or next_u64
; e.g. a u64
cast to bytes is not required to
have the same value as eight bytes filled via this function. There is
a requirement of portability for reproducible generators which implies
that any seedable generator must fix endianness when generating bytes.
Types wrapping an inner RNG must not use the default implementation, since the inner RNG's implementation may produce different values.
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).
Example
use rand::{thread_rng, Rng}; let mut v = [0u8; 13579]; thread_rng().fill_bytes(&mut v); println!("{:?}", &v[..]);
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; other methods either handle the error
internally or panic. This method is
the intended way to use external (true) RNGs, like OsRng
. Its main
use-cases are to generate keys and to seed (infallible) PRNGs.
Other than error handling, this method is identical to fill_bytes
, and
has a default implementation simply wrapping fill_bytes
.
Implementations on Foreign Types
impl<'a, R: ?Sized> Rng for &'a mut R where
R: Rng,
[src]
R: Rng,
impl<R: ?Sized> Rng for Box<R> where
R: Rng,
[src]
R: Rng,
Implementors
impl Rng for JitterRng
impl Rng for OsRng
impl<R: Read> Rng for ReadRng<R>
impl<R: Rng, Rsdr: Reseeder<R>> Rng for ReseedingRng<R, Rsdr>
impl Rng for ChaChaRng
impl Rng for Hc128Rng
impl Rng for IsaacRng
impl Rng for Isaac64Rng
impl Rng for XorShiftRng
impl Rng for StdRng
impl Rng for ThreadRng