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 gen<T: Rand>(&mut self) -> T
where
Self: Sized, { ... } fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self>
where
Self: Sized, { ... } fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T
where
Self: Sized, { ... } fn gen_weighted_bool(&mut self, n: u32) -> bool
where
Self: Sized, { ... } fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self>
where
Self: Sized, { ... } fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>
where
Self: Sized, { ... } fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
where
Self: Sized, { ... } fn shuffle<T>(&mut self, values: &mut [T])
where
Self: Sized, { ... } }
A random number generator.
Required Methods
fn next_u32(&mut self) -> u32
Return the next random u32.
This rarely needs to be called directly, prefer r.gen()
to
r.next_u32()
.
Provided Methods
fn next_u64(&mut self) -> u64
Return the next random u64.
By default this is implemented in terms of next_u32
. An
implementation of this trait must provide at least one of
these two methods. Similarly to next_u32
, this rarely needs
to be called directly, prefer r.gen()
to r.next_u64()
.
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.
This has a default implementation in terms of next_u64
and
next_u32
, but should be overridden by implementations that
offer a more efficient solution than just calling those
methods repeatedly.
This method does not have a requirement to bear any fixed
relationship to the other methods, for example, it does not
have to result in the same output as progressively filling
dest
with self.gen::<u8>()
, and any such behaviour should
not be relied upon.
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 gen<T: Rand>(&mut self) -> T where
Self: Sized,
Self: Sized,
Return a random value of a Rand
type.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); let x: u32 = rng.gen(); println!("{}", x); println!("{:?}", rng.gen::<(f64, bool)>());
fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> where
Self: Sized,
Self: Sized,
Return an iterator that will yield an infinite number of randomly generated items.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); let x = rng.gen_iter::<u32>().take(10).collect::<Vec<u32>>(); println!("{:?}", x); println!("{:?}", rng.gen_iter::<(f64, bool)>().take(5) .collect::<Vec<(f64, bool)>>());
fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T where
Self: Sized,
Self: Sized,
Generate a random value in the range [low
, high
).
This is a convenience wrapper around
distributions::Range
. If this function will be called
repeatedly with the same arguments, one should use Range
, as
that will amortize the computations that allow for perfect
uniformity, as they only happen on initialization.
Panics
Panics if low >= high
.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); let n: u32 = rng.gen_range(0, 10); println!("{}", n); let m: f64 = rng.gen_range(-40.0f64, 1.3e5f64); println!("{}", m);
fn gen_weighted_bool(&mut self, n: u32) -> bool where
Self: Sized,
Self: Sized,
Return a bool with a 1 in n chance of true
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); println!("{}", rng.gen_weighted_bool(3));
fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> where
Self: Sized,
Self: Sized,
Return an iterator of random characters from the set A-Z,a-z,0-9.
Example
use rand::{thread_rng, Rng}; let s: String = thread_rng().gen_ascii_chars().take(10).collect(); println!("{}", s);
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> where
Self: Sized,
Self: Sized,
Return a random element from values
.
Return None
if values
is empty.
Example
use rand::{thread_rng, Rng}; let choices = [1, 2, 4, 8, 16, 32]; let mut rng = thread_rng(); println!("{:?}", rng.choose(&choices)); assert_eq!(rng.choose(&choices[..0]), None);
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> where
Self: Sized,
Self: Sized,
Return a mutable pointer to a random element from values
.
Return None
if values
is empty.
fn shuffle<T>(&mut self, values: &mut [T]) where
Self: Sized,
Self: Sized,
Shuffle a mutable slice in place.
This applies Durstenfeld's algorithm for the Fisher–Yates shuffle which produces an unbiased permutation.
Example
use rand::{thread_rng, Rng}; let mut rng = thread_rng(); let mut y = [1, 2, 3]; rng.shuffle(&mut y); println!("{:?}", y); rng.shuffle(&mut y); println!("{:?}", y);
Implementations on Foreign Types
impl<'a, R: ?Sized> Rng for &'a mut R where
R: Rng,
[src]
R: Rng,
fn next_u32(&mut self) -> u32
[src]
fn next_u64(&mut self) -> u64
[src]
fn next_f32(&mut self) -> f32
[src]
fn next_f64(&mut self) -> f64
[src]
fn fill_bytes(&mut self, dest: &mut [u8])
[src]
fn gen<T: Rand>(&mut self) -> T where
Self: Sized,
[src]
Self: Sized,
fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> where
Self: Sized,
[src]
Self: Sized,
fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T where
Self: Sized,
[src]
Self: Sized,
fn gen_weighted_bool(&mut self, n: u32) -> bool where
Self: Sized,
[src]
Self: Sized,
fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> where
Self: Sized,
[src]
Self: Sized,
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> where
Self: Sized,
[src]
Self: Sized,
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> where
Self: Sized,
[src]
Self: Sized,
fn shuffle<T>(&mut self, values: &mut [T]) where
Self: Sized,
[src]
Self: Sized,
impl<R: ?Sized> Rng for Box<R> where
R: Rng,
[src]
R: Rng,
fn next_u32(&mut self) -> u32
[src]
fn next_u64(&mut self) -> u64
[src]
fn next_f32(&mut self) -> f32
[src]
fn next_f64(&mut self) -> f64
[src]
fn fill_bytes(&mut self, dest: &mut [u8])
[src]
fn gen<T: Rand>(&mut self) -> T where
Self: Sized,
[src]
Self: Sized,
fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> where
Self: Sized,
[src]
Self: Sized,
fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T where
Self: Sized,
[src]
Self: Sized,
fn gen_weighted_bool(&mut self, n: u32) -> bool where
Self: Sized,
[src]
Self: Sized,
fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> where
Self: Sized,
[src]
Self: Sized,
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> where
Self: Sized,
[src]
Self: Sized,
fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> where
Self: Sized,
[src]
Self: Sized,
fn shuffle<T>(&mut self, values: &mut [T]) where
Self: Sized,
[src]
Self: Sized,
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 IsaacRng
impl Rng for Isaac64Rng
impl Rng for XorShiftRng
impl Rng for StdRng
impl Rng for ThreadRng