[][src]Trait rand::Rng

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

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

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

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

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

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

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

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>

fn sample_iter<'a, T, D: Distribution<T>>(
    &'a mut self,
    distr: &'a D
) -> DistIter<'a, D, Self, T> where
    Self: Sized

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!");
}

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

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

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

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

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

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.

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

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

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

Deprecated since 0.6.0:

use SliceRandom::choose instead

Return a random element from values.

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

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

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.

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

Deprecated since 0.6.0:

use SliceRandom::shuffle instead

Shuffle a mutable slice in place.

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

Loading content...

Implementors

impl<R: RngCore + ?Sized> Rng for R
[src]

fn gen<T>(&mut self) -> T where
    Standard: Distribution<T>, 
[src]

fn gen_range<T: SampleUniform, B1, B2>(&mut self, low: B1, high: B2) -> T where
    B1: SampleBorrow<T> + Sized,
    B2: SampleBorrow<T> + Sized
[src]

fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T
[src]

Important traits for DistIter<'a, D, R, T>
fn sample_iter<'a, T, D: Distribution<T>>(
    &'a mut self,
    distr: &'a D
) -> DistIter<'a, D, Self, T> where
    Self: Sized
[src]

fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T)
[src]

fn try_fill<T: AsByteSliceMut + ?Sized>(
    &mut self,
    dest: &mut T
) -> Result<(), Error>
[src]

fn gen_bool(&mut self, p: f64) -> bool
[src]

fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool
[src]

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

Deprecated since 0.6.0:

use SliceRandom::choose instead

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

Deprecated since 0.6.0:

use SliceRandom::choose_mut instead

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

Deprecated since 0.6.0:

use SliceRandom::shuffle instead

Loading content...