pub trait Distribution<T> {
    fn sample<R>(&self, rng: &mut R) -> T
    where
        R: Rng + ?Sized
; 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§

source

fn sample<R>(&self, rng: &mut R) -> Twhere
    R: Rng + ?Sized,

Generate a random value of T, using rng as the source of randomness.

Provided Methods§

source

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T> where
    R: Rng,
    Self: Sized,

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

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>where
    F: Fn(T) -> S,
    Self: Sized,

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

Implementations on Foreign Types§

source§

impl<'a, T, D> Distribution<T> for &'a Dwhere
    D: Distribution<T> + ?Sized,

source§

fn sample<R>(&self, rng: &mut R) -> Twhere
    R: Rng + ?Sized,

Implementors§

source§

impl Distribution<bool> for Bernoulli

source§

impl Distribution<bool> for Standard

source§

impl Distribution<char> for Standard

source§

impl Distribution<f32> for Exp1

source§

impl Distribution<f32> for Open01

source§

impl Distribution<f32> for OpenClosed01

source§

impl Distribution<f32> for Standard

source§

impl Distribution<f32> for StandardNormal

source§

impl Distribution<f64> for Exp1

source§

impl Distribution<f64> for Open01

source§

impl Distribution<f64> for OpenClosed01

source§

impl Distribution<f64> for Standard

source§

impl Distribution<f64> for StandardNormal

source§

impl Distribution<i8> for Standard

source§

impl Distribution<i16> for Standard

source§

impl Distribution<i32> for Standard

source§

impl Distribution<i64> for Standard

source§

impl Distribution<i128> for Standard

source§

impl Distribution<isize> for Standard

source§

impl Distribution<u8> for Alphanumeric

source§

impl Distribution<u8> for Standard

source§

impl Distribution<u16> for Standard

source§

impl Distribution<u32> for Standard

source§

impl Distribution<u64> for Binomial

source§

impl Distribution<u64> for Geometric

source§

impl Distribution<u64> for Hypergeometric

source§

impl Distribution<u64> for Standard

source§

impl Distribution<u64> for StandardGeometric

source§

impl Distribution<u128> for Standard

source§

impl Distribution<()> for Standard

source§

impl Distribution<usize> for Standard

source§

impl Distribution<__m128i> for Standard

Available only on x86/64 platforms

source§

impl Distribution<__m256i> for Standard

Available only on x86/64 platforms

source§

impl Distribution<NonZeroU8> for Standard

source§

impl Distribution<NonZeroU16> for Standard

source§

impl Distribution<NonZeroU32> for Standard

source§

impl Distribution<NonZeroU64> for Standard

source§

impl Distribution<NonZeroU128> for Standard

source§

impl Distribution<NonZeroUsize> for Standard

source§

impl<'a, T> Distribution<&'a T> for Slice<'a, T>

source§

impl<A> Distribution<(A,)> for Standardwhere
    Standard: Distribution<A>,

source§

impl<A, B> Distribution<(A, B)> for Standardwhere
    Standard: Distribution<A> + Distribution<B>,

source§

impl<A, B, C> Distribution<(A, B, C)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C>,

source§

impl<A, B, C, D> Distribution<(A, B, C, D)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

source§

impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E>,

source§

impl<A, B, C, D, E, F> Distribution<(A, B, C, D, E, F)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F>,

source§

impl<A, B, C, D, E, F, G> Distribution<(A, B, C, D, E, F, G)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G>,

source§

impl<A, B, C, D, E, F, G, H> Distribution<(A, B, C, D, E, F, G, H)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H>,

source§

impl<A, B, C, D, E, F, G, H, I> Distribution<(A, B, C, D, E, F, G, H, I)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I>,

source§

impl<A, B, C, D, E, F, G, H, I, J> Distribution<(A, B, C, D, E, F, G, H, I, J)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J>,

source§

impl<A, B, C, D, E, F, G, H, I, J, K> Distribution<(A, B, C, D, E, F, G, H, I, J, K)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K>,

source§

impl<A, B, C, D, E, F, G, H, I, J, K, L> Distribution<(A, B, C, D, E, F, G, H, I, J, K, L)> for Standardwhere
    Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K> + Distribution<L>,

source§

impl<D, F, T, S> Distribution<S> for DistMap<D, F, T, S>where
    D: Distribution<T>,
    F: Fn(T) -> S,

source§

impl<F> Distribution<Vec<F, Global>> for Dirichlet<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Beta<F>where
    F: Float,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Cauchy<F>where
    F: Float + FloatConst,
    Standard: Distribution<F>,

source§

impl<F> Distribution<F> for ChiSquared<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Exp<F>where
    F: Float,
    Exp1: Distribution<F>,

source§

impl<F> Distribution<F> for FisherF<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Frechet<F>where
    F: Float,
    OpenClosed01: Distribution<F>,

source§

impl<F> Distribution<F> for Gamma<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Gumbel<F>where
    F: Float,
    OpenClosed01: Distribution<F>,

source§

impl<F> Distribution<F> for InverseGaussian<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Standard: Distribution<F>,

source§

impl<F> Distribution<F> for LogNormal<F>where
    F: Float,
    StandardNormal: Distribution<F>,

source§

impl<F> Distribution<F> for Normal<F>where
    F: Float,
    StandardNormal: Distribution<F>,

source§

impl<F> Distribution<F> for NormalInverseGaussian<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Standard: Distribution<F>,

source§

impl<F> Distribution<F> for Pareto<F>where
    F: Float,
    OpenClosed01: Distribution<F>,

source§

impl<F> Distribution<F> for Pert<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Poisson<F>where
    F: Float + FloatConst,
    Standard: Distribution<F>,

source§

impl<F> Distribution<F> for SkewNormal<F>where
    F: Float,
    StandardNormal: Distribution<F>,

source§

impl<F> Distribution<F> for StudentT<F>where
    F: Float,
    StandardNormal: Distribution<F>,
    Exp1: Distribution<F>,
    Open01: Distribution<F>,

source§

impl<F> Distribution<F> for Triangular<F>where
    F: Float,
    Standard: Distribution<F>,

source§

impl<F> Distribution<F> for Weibull<F>where
    F: Float,
    OpenClosed01: Distribution<F>,

source§

impl<F> Distribution<F> for Zeta<F>where
    F: Float,
    Standard: Distribution<F>,
    OpenClosed01: Distribution<F>,

source§

impl<F> Distribution<F> for Zipf<F>where
    F: Float,
    Standard: Distribution<F>,

source§

impl<F: Float + SampleUniform> Distribution<[F; 2]> for UnitCircle

source§

impl<F: Float + SampleUniform> Distribution<[F; 2]> for UnitDisc

source§

impl<F: Float + SampleUniform> Distribution<[F; 3]> for UnitBall

source§

impl<F: Float + SampleUniform> Distribution<[F; 3]> for UnitSphere

source§

impl<T> Distribution<Option<T>> for Standardwhere
    Standard: Distribution<T>,

source§

impl<T> Distribution<Wrapping<T>> for Standardwhere
    Standard: Distribution<T>,

source§

impl<T, const N: usize> Distribution<[T; N]> for Standardwhere
    Standard: Distribution<T>,

source§

impl<W: AliasableWeight> Distribution<usize> for WeightedAliasIndex<W>

Available on crate feature alloc only.
source§

impl<X> Distribution<usize> for WeightedIndex<X>where
    X: SampleUniform + PartialOrd<X>,

source§

impl<X> Distribution<X> for Uniform<X>where
    X: SampleUniform,