Trait rand::Rng [−] [src]

pub trait Rng: RngCore {
    fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) { ... }

    fn try_fill<T: AsByteSliceMut + ?Sized>(
        &mut self, 
        dest: &mut T
    ) -> Result<(), Error> { ... }

    fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T { ... }

    fn gen<T>(&mut self) -> T
    where
        Uniform: Distribution<T>,
    { ... }

    fn gen_iter<T>(&mut self) -> Generator<T, &mut Self>
    where
        Uniform: Distribution<T>,
    { ... }

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

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

    fn gen_bool(&mut self, p: f64) -> bool { ... }

    fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self> { ... }

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

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

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

An automatically-implemented extension trait on RngCore providing high-level generic methods for sampling values and other convenience methods.

This is the primary trait to use when generating random values.

Generic usage

The basic pattern is fn foo<R: Rng + ?Sized>(rng: &mut R). Some things are worth noting here:

  • Since Rng: RngCore and every RngCore implements Rng, it makes no difference whether we use R: Rng or R: RngCore.
  • The + ?Sized un-bounding allows functions to be called directly on type-erased references; i.e. foo(r) where r: &mut RngCore. Without this it would be necessary to write foo(&mut r).

An alternative pattern is possible: fn foo<R: Rng>(rng: R). This has some trade-offs. It allows the argument to be consumed directly without a &mut (which is how from_rng(thread_rng()) works); also it still works directly on references (including type-erased references). Unfortunately within the function foo it is not known whether rng is a reference type or not, hence many uses of rng require an extra reference, either explicitly (distr.sample(&mut rng)) or implicitly (rng.gen()); one may hope the optimiser can remove redundant references later.

Example:

use rand::Rng;
 
fn foo<R: Rng + ?Sized>(rng: &mut R) -> f32 {
    rng.gen()
}

Iteration

Iteration over an Rng can be achieved using iter::repeat as follows:

use std::iter;
use rand::{Rng, thread_rng};
use rand::distributions::{Alphanumeric, Range};
 
let mut rng = thread_rng();
 
// Vec of 16 x f32:
let v: Vec<f32> = iter::repeat(()).map(|()| rng.gen()).take(16).collect();
 
// String:
let s: String = iter::repeat(())
        .map(|()| rng.sample(Alphanumeric))
        .take(7).collect();
 
// Dice-rolling:
let die_range = Range::new_inclusive(1, 6);
let mut roll_die = iter::repeat(()).map(|()| rng.sample(die_range));
while roll_die.next().unwrap() != 6 {
    println!("Not a 6; rolling again!");
}

Provided Methods

Fill dest entirely with random bytes (uniform value distribution), where dest is any type supporting AsByteSliceMut, namely slices and arrays over primitive integer types (i8, i16, u32, etc.).

On big-endian platforms this performs byte-swapping to ensure portability of results from reproducible generators.

This uses fill_bytes internally which may handle some RNG errors implicitly (e.g. waiting if the OS generator is not ready), but panics on other errors. See also try_fill which returns errors.

Example

use rand::{thread_rng, Rng};
 
let mut arr = [0i8; 20];
thread_rng().try_fill(&mut arr[..]);

Fill dest entirely with random bytes (uniform value distribution), where dest is any type supporting AsByteSliceMut, namely slices and arrays over primitive integer types (i8, i16, u32, etc.).

On big-endian platforms this performs byte-swapping to ensure portability of results from reproducible generators.

This uses try_fill_bytes internally and forwards all RNG errors. In some cases errors may be resolvable; see ErrorKind and documentation for the RNG in use. If you do not plan to handle these errors you may prefer to use fill.

Example

use rand::{thread_rng, Rng};
 
let mut arr = [0u64; 4];
thread_rng().try_fill(&mut arr[..])?;

Sample a new value, using the given distribution.

Example

use rand::{thread_rng, Rng};
use rand::distributions::Range;
 
let mut rng = thread_rng();
let x: i32 = rng.sample(Range::new(10, 15));

Return a random value supporting the Uniform distribution.

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<T, R>

Deprecated since 0.5.0

: use iter::repeat instead

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

Generate a random value in the range [low, high), i.e. inclusive of low and exclusive of 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 when constructing the Range.

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

Deprecated since 0.5.0

: use gen_bool instead

Return a bool with a 1 in n chance of true

Example

#[allow(deprecated)]
use rand::{thread_rng, Rng};

let mut rng = thread_rng();
assert_eq!(rng.gen_weighted_bool(0), true);
assert_eq!(rng.gen_weighted_bool(1), true);
// Just like `rng.gen::<bool>()` a 50-50% chance, but using a slower
// method with different results.
println!("{}", rng.gen_weighted_bool(2));
// First meaningful use of `gen_weighted_bool`.
println!("{}", rng.gen_weighted_bool(3));

Return a bool with a probability p of being true.

Example

use rand::{thread_rng, Rng};

let mut rng = thread_rng();
println!("{}", rng.gen_bool(1.0 / 3.0));
ⓘImportant traits for AsciiGenerator<R>

Deprecated since 0.5.0

: use distributions::Alphanumeric instead

Return an iterator of random characters from the set A-Z,a-z,0-9.

Example

#[allow(deprecated)]
use rand::{thread_rng, Rng};

let s: String = thread_rng().gen_ascii_chars().take(10).collect();
println!("{}", s);

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

Return a mutable pointer to a random element from values.

Return None if values is empty.

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

Implementors