Trait rand::distributions::Distribution
source · [−]pub trait Distribution<T> {
fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> T;
fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>ⓘ
where
R: Rng,
Self: Sized,
{ ... }
fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>
where
F: Fn(T) -> S,
Self: Sized,
{ ... }
}Expand description
Types (distributions) that can be used to create a random instance of T.
It is possible to sample from a distribution through both the
Distribution and Rng traits, via distr.sample(&mut rng) and
rng.sample(distr). They also both offer the sample_iter method, which
produces an iterator that samples from the distribution.
All implementations are expected to be immutable; this has the significant advantage of not needing to consider thread safety, and for most distributions efficient state-less sampling algorithms are available.
Implementations are typically expected to be portable with reproducible
results when used with a PRNG with fixed seed; see the
portability chapter
of The Rust Rand Book. In some cases this does not apply, e.g. the usize
type requires different sampling on 32-bit and 64-bit machines.
Required methods
Provided methods
Create an iterator that generates random values of T, using rng as
the source of randomness.
Note that this function takes self by value. This works since
Distribution<T> is impl’d for &D where D: Distribution<T>,
however borrowing is not automatic hence distr.sample_iter(...) may
need to be replaced with (&distr).sample_iter(...) to borrow or
(&*distr).sample_iter(...) to reborrow an existing reference.
Example
use rand::thread_rng;
use rand::distributions::{Distribution, Alphanumeric, Uniform, Standard};
let mut rng = thread_rng();
// Vec of 16 x f32:
let v: Vec<f32> = Standard.sample_iter(&mut rng).take(16).collect();
// String:
let s: String = Alphanumeric
.sample_iter(&mut rng)
.take(7)
.map(char::from)
.collect();
// Dice-rolling:
let die_range = Uniform::new_inclusive(1, 6);
let mut roll_die = die_range.sample_iter(&mut rng);
while roll_die.next().unwrap() != 6 {
println!("Not a 6; rolling again!");
}Create a distribution of values of ‘S’ by mapping the output of Self
through the closure F
Example
use rand::thread_rng;
use rand::distributions::{Distribution, Uniform};
let mut rng = thread_rng();
let die = Uniform::new_inclusive(1, 6);
let even_number = die.map(|num| num % 2 == 0);
while !even_number.sample(&mut rng) {
println!("Still odd; rolling again!");
}