Trait rand::Rng

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>(&mut self) -> T
    where
        T: Rand,
    { ... }
    fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self>
    where
        T: Rand,
    { ... }
    fn gen_range<T>(&mut self, low: T, high: T) -> T
    where
        T: SampleRange + PartialOrd<T>,
    { ... }
    fn gen_weighted_bool(&mut self, n: u32) -> bool { ... }
    fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self> { ... }
    fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T> { ... }
    fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> { ... }
    fn shuffle<T>(&mut self, values: &mut [T]) { ... }
}

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().

Loading content...

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>(&mut self) -> T where
    T: Rand, 

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)>());

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where
    T: Rand, 

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>(&mut self, low: T, high: T) -> T where
    T: SampleRange + PartialOrd<T>, 

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

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));

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

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<T>(&mut self, values: &'a [T]) -> Option<&'a T>

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<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

Return a mutable pointer to a random element from values.

Return None if values is empty.

fn shuffle<T>(&mut self, values: &mut [T])

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);

Loading content...

Implementations on Foreign Types

impl<'a, R> Rng for &'a mut R where     R: Rng + ?Sized,

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for JitterRng

fn next_u32(&mut self) -> u32

fn next_u64(&mut self) -> u64

fn fill_bytes(&mut self, dest: &mut [u8])

fn next_f32(&mut self) -> f32

fn next_f64(&mut self) -> f64

fn gen<T>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl<R> Rng for Box<R> where     R: Rng + ?Sized,

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

Loading content...

Implementors

impl Rng for ChaChaRng

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for Isaac64Rng

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for IsaacRng

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for OsRng

fn next_u32(&mut self) -> u32

fn next_u64(&mut self) -> u64

fn fill_bytes(&mut self, v: &mut [u8])

fn next_f32(&mut self) -> f32

fn next_f64(&mut self) -> f64

fn gen<T>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for StdRng

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for ThreadRng

fn next_u32(&mut self) -> u32

fn next_u64(&mut self) -> u64

fn fill_bytes(&mut self, bytes: &mut [u8])

fn next_f32(&mut self) -> f32

fn next_f64(&mut self) -> f64

fn gen<T>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl Rng for XorShiftRng

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>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl<R> Rng for ReadRng<R> where     R: Read,

fn next_u32(&mut self) -> u32

fn next_u64(&mut self) -> u64

fn fill_bytes(&mut self, v: &mut [u8])

fn next_f32(&mut self) -> f32

fn next_f64(&mut self) -> f64

fn gen<T>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

impl<R, Rsdr> Rng for ReseedingRng<R, Rsdr> where     R: Rng,     Rsdr: Reseeder<R>,

fn next_u32(&mut self) -> u32

fn next_u64(&mut self) -> u64

fn fill_bytes(&mut self, dest: &mut [u8])

fn next_f32(&mut self) -> f32

fn next_f64(&mut self) -> f64

fn gen<T>(&mut self) -> T where     T: Rand,

Important traits for Generator<'a, T, R>

impl<'a, T, R> Iterator for Generator<'a, T, R> where
    R: Rng,
    T: Rand,  type Item = T;

fn gen_iter<T>(&'a mut self) -> Generator<'a, T, Self> where     T: Rand,

fn gen_range<T>(&mut self, low: T, high: T) -> T where     T: SampleRange + PartialOrd<T>,

fn gen_weighted_bool(&mut self, n: u32) -> bool

Important traits for AsciiGenerator<'a, R>

impl<'a, R> Iterator for AsciiGenerator<'a, R> where
    R: Rng,  type Item = char;

fn gen_ascii_chars(&'a mut self) -> AsciiGenerator<'a, Self>

fn choose<T>(&mut self, values: &'a [T]) -> Option<&'a T>

fn choose_mut<T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>

fn shuffle<T>(&mut self, values: &mut [T])

Loading content...