Trait rand::Rng[−][src]

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

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

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

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

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

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

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));
ⓘImportant traits for DistIter<'a, D, R, T>

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.

This is a wrapper around distributions::Bernoulli.

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 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);
ⓘImportant traits for Generator<T, R>

Deprecated since 0.5.0

: use Rng::sample_iter(&Standard) 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)>>());

Deprecated since 0.5.0

: use gen_bool instead

Return a bool with a 1 in n chance of true

Example

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));
ⓘImportant traits for AsciiGenerator<R>

Deprecated since 0.5.0

: use sample_iter(&Alphanumeric) instead

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

Implementors