pub trait Distribution<T> {
// Required method
fn sample<R>(&self, rng: &mut R) -> T
where R: Rng + ?Sized;
// Provided methods
fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>
where R: Rng,
Self: Sized { ... }
fn map<F, S>(self, func: F) -> Map<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 [RngExt] 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§
Sourcefn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>
fn sample_iter<R>(self, rng: R) -> Iter<Self, R, T>
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::distr::{Distribution, Alphanumeric, Uniform, StandardUniform};
let mut rng = rand::rng();
// Vec of 16 x f32:
let v: Vec<f32> = StandardUniform.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).unwrap();
let mut roll_die = die_range.sample_iter(&mut rng);
while roll_die.next().unwrap() != 6 {
println!("Not a 6; rolling again!");
}Sourcefn map<F, S>(self, func: F) -> Map<Self, F, T, S>
fn map<F, S>(self, func: F) -> Map<Self, F, T, S>
Map sampled values to type S
§Example
use rand::distr::{Distribution, Uniform};
let die = Uniform::new_inclusive(1, 6).unwrap();
let even_number = die.map(|num| num % 2 == 0);
while !even_number.sample(&mut rand::rng()) {
println!("Still odd; rolling again!");
}Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementations on Foreign Types§
Source§impl Distribution<f32> for Exp1
impl Distribution<f32> for Exp1
Source§impl Distribution<f64> for Exp1
impl Distribution<f64> for Exp1
Source§impl Distribution<u64> for StandardGeometric
impl Distribution<u64> for StandardGeometric
Source§impl<F> Distribution<F> for Frechet<F>
impl<F> Distribution<F> for Frechet<F>
Source§impl<F> Distribution<F> for Gumbel<F>
impl<F> Distribution<F> for Gumbel<F>
Source§impl<F> Distribution<F> for NormalInverseGaussian<F>
impl<F> Distribution<F> for NormalInverseGaussian<F>
Source§impl<F> Distribution<F> for SkewNormal<F>
impl<F> Distribution<F> for SkewNormal<F>
Source§impl<T, D> Distribution<T> for &Dwhere
D: Distribution<T> + ?Sized,
impl<T, D> Distribution<T> for &Dwhere
D: Distribution<T> + ?Sized,
Source§impl<W> Distribution<usize> for WeightedAliasIndex<W>where
W: AliasableWeight,
impl<W> Distribution<usize> for WeightedAliasIndex<W>where
W: AliasableWeight,
Source§impl<W> Distribution<usize> for WeightedTreeIndex<W>
Samples a randomly selected index from the weighted distribution.
impl<W> Distribution<usize> for WeightedTreeIndex<W>
Samples a randomly selected index from the weighted distribution.
Caution: This method panics if there are no elements or all weights are zero. However,
it is guaranteed that this method will not panic if a call to WeightedTreeIndex::is_valid
returns true.
Implementors§
impl Distribution<()> for rand::distr::StandardUniform
impl Distribution<NonZero<i8>> for rand::distr::StandardUniform
impl Distribution<NonZero<i16>> for rand::distr::StandardUniform
impl Distribution<NonZero<i32>> for rand::distr::StandardUniform
impl Distribution<NonZero<i64>> for rand::distr::StandardUniform
impl Distribution<NonZero<i128>> for rand::distr::StandardUniform
impl Distribution<NonZero<u8>> for rand::distr::StandardUniform
impl Distribution<NonZero<u16>> for rand::distr::StandardUniform
impl Distribution<NonZero<u32>> for rand::distr::StandardUniform
impl Distribution<NonZero<u64>> for rand::distr::StandardUniform
impl Distribution<NonZero<u128>> for rand::distr::StandardUniform
impl Distribution<Vec<f64>> for UnifiedDirichlet
impl Distribution<__m128i> for rand::distr::StandardUniform
Available on x86 or x86-64 only.
impl Distribution<__m256i> for rand::distr::StandardUniform
Available on x86 or x86-64 only.