logo

Trait rand::Rng

source · [−]
pub trait Rng: RngCore {
    fn gen<T>(&mut self) -> T
    where
        Standard: Distribution<T>,
    { ... }

    fn gen_range<T: SampleUniform, B1, B2>(&mut self, low: B1, high: B2) -> T
    where
        B1: SampleBorrow<T> + Sized,
        B2: SampleBorrow<T> + Sized,
    { ... }

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

    fn sample_iter<'a, T, D: Distribution<T>>(
        &'a mut self, 
        distr: &'a D
    ) -> DistIter<'a, D, Self, T>ⓘNotable traits for DistIter<'a, D, R, T>impl<'a, D, R, T> Iterator for DistIter<'a, D, R, T> where
    D: Distribution<T>,
    R: Rng + 'a,     type Item = T;
    where
        Self: Sized,
    { ... }

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

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

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

    fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool { ... }

    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]) { ... }
}
Expand description

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

Provided methods

Return a random value supporting the Standard distribution.

Example
use rand::{thread_rng, Rng};

let mut rng = thread_rng();
let x: u32 = rng.gen();
println!("{}", x);
println!("{:?}", rng.gen::<(f64, bool)>());

Generate a random value in the range [low, high), i.e. inclusive of low and exclusive of high.

This function is optimised for the case that only a single sample is made from the given range. See also the Uniform distribution type which may be faster if sampling from the same range repeatedly.

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

Sample a new value, using the given distribution.

Example
use rand::{thread_rng, Rng};
use rand::distributions::Uniform;

let mut rng = thread_rng();
let x = rng.sample(Uniform::new(10u32, 15));
// Type annotation requires two types, the type and distribution; the
// distribution can be inferred.
let y = rng.sample::<u16, _>(Uniform::new(10, 15));

Create an iterator that generates values using the given distribution.

Example
use rand::{thread_rng, Rng};
use rand::distributions::{Alphanumeric, Uniform, Standard};

let mut rng = thread_rng();

// Vec of 16 x f32:
let v: Vec<f32> = thread_rng().sample_iter(&Standard).take(16).collect();

// String:
let s: String = rng.sample_iter(&Alphanumeric).take(7).collect();

// Combined values
println!("{:?}", thread_rng().sample_iter(&Standard).take(5)
                             .collect::<Vec<(f64, bool)>>());

// Dice-rolling:
let die_range = Uniform::new_inclusive(1, 6);
let mut roll_die = rng.sample_iter(&die_range);
while roll_die.next().unwrap() != 6 {
    println!("Not a 6; rolling again!");
}

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().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[..])?;

Return a bool with a probability p of being true.

See also the Bernoulli distribution, which may be faster if sampling from the same probability repeatedly.

Example
use rand::{thread_rng, Rng};

let mut rng = thread_rng();
println!("{}", rng.gen_bool(1.0 / 3.0));
Panics

If p < 0 or p > 1.

Return a bool with a probability of numerator/denominator of being true. I.e. gen_ratio(2, 3) has chance of 2 in 3, or about 67%, of returning true. If numerator == denominator, then the returned value is guaranteed to be true. If numerator == 0, then the returned value is guaranteed to be false.

See also the Bernoulli distribution, which may be faster if sampling from the same numerator and denominator repeatedly.

Panics

If denominator == 0 or numerator > denominator.

Example
use rand::{thread_rng, Rng};

let mut rng = thread_rng();
println!("{}", rng.gen_ratio(2, 3));
👎 Deprecated since 0.6.0:

use SliceRandom::choose instead

Return a random element from values.

Deprecated: use seq::SliceRandom::choose instead.

👎 Deprecated since 0.6.0:

use SliceRandom::choose_mut instead

Return a mutable pointer to a random element from values.

Deprecated: use seq::SliceRandom::choose_mut instead.

👎 Deprecated since 0.6.0:

use SliceRandom::shuffle instead

Shuffle a mutable slice in place.

Deprecated: use seq::SliceRandom::shuffle instead.

Implementors