Trait Distribution 

pub trait Distribution<T> {
    // Required method
    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> T;

    // 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 { ... }
}

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

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

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

Provided Methods

fn sample_iter<R>(self, rng: R) -> Iter<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::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!");
}

fn map<F, S>(self, func: F) -> Map<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

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

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

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

Implementors

impl Distribution<()> for StandardUniform

impl Distribution<NonZero<i8>> for StandardUniform

impl Distribution<NonZero<i16>> for StandardUniform

impl Distribution<NonZero<i32>> for StandardUniform

impl Distribution<NonZero<i64>> for StandardUniform

impl Distribution<NonZero<i128>> for StandardUniform

impl Distribution<NonZero<u8>> for StandardUniform

impl Distribution<NonZero<u16>> for StandardUniform

impl Distribution<NonZero<u32>> for StandardUniform

impl Distribution<NonZero<u64>> for StandardUniform

impl Distribution<NonZero<u128>> for StandardUniform

impl Distribution<Simd<f32, 2>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 2>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 2>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 4>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 4>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 4>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 8>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 8>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 8>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 16>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 16>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f32, 16>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 2>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 2>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 2>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 4>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 4>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 4>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 8>> for Open01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 8>> for OpenClosed01

Available on crate feature simd_support only.

impl Distribution<Simd<f64, 8>> for StandardUniform

Available on crate feature simd_support only.

impl Distribution<__m128i> for StandardUniform

Available on x86 or x86-64 only.

impl Distribution<__m256i> for StandardUniform

Available on x86 or x86-64 only.

impl Distribution<__m512i> for StandardUniform

Available on crate feature simd_support and (x86 or x86-64) only.

impl Distribution<bool> for Bernoulli

impl Distribution<bool> for StandardUniform

impl Distribution<char> for StandardUniform

impl Distribution<f32> for Open01

impl Distribution<f32> for OpenClosed01

impl Distribution<f32> for StandardUniform

impl Distribution<f64> for Open01

impl Distribution<f64> for OpenClosed01

impl Distribution<f64> for StandardUniform

impl Distribution<i8> for StandardUniform

impl Distribution<i16> for StandardUniform

impl Distribution<i32> for StandardUniform

impl Distribution<i64> for StandardUniform

impl Distribution<i128> for StandardUniform

impl Distribution<u8> for Alphabetic

impl Distribution<u8> for Alphanumeric

impl Distribution<u8> for StandardUniform

impl Distribution<u16> for StandardUniform

impl Distribution<u32> for StandardUniform

impl Distribution<u64> for StandardUniform

impl Distribution<u128> for StandardUniform

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

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 StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K> + Distribution<L>,

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 StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J> + Distribution<K>,

impl<A, B, C, D, E, F, G, H, I, J> Distribution<(A, B, C, D, E, F, G, H, I, J)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I> + Distribution<J>,

impl<A, B, C, D, E, F, G, H, I> Distribution<(A, B, C, D, E, F, G, H, I)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution<I>,

impl<A, B, C, D, E, F, G, H> Distribution<(A, B, C, D, E, F, G, H)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H>,

impl<A, B, C, D, E, F, G> Distribution<(A, B, C, D, E, F, G)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G>,

impl<A, B, C, D, E, F> Distribution<(A, B, C, D, E, F)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F>,

impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E>,

impl<A, B, C, D> Distribution<(A, B, C, D)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

impl<A, B, C> Distribution<(A, B, C)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B> + Distribution<C>,

impl<A, B> Distribution<(A, B)> for StandardUniform

where StandardUniform: Distribution<A> + Distribution<B>,

impl<A> Distribution<(A,)> for StandardUniform

where StandardUniform: Distribution<A>,

impl<D, F, T, S> Distribution<S> for Map<D, F, T, S>

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

impl<T, const LANES: usize> Distribution<Mask<T, LANES>> for StandardUniform

where T: MaskElement + Default, StandardUniform: Distribution<Simd<T, LANES>>, Simd<T, LANES>: SimdPartialOrd<Mask = Mask<T, LANES>>,

Available on crate feature simd_support only.

Note that on some hardware like x86/64 mask operations like _mm_blendv_epi8 only care about a single bit. This means that you could use uniform random bits directly:

// this may be faster...
let x = unsafe { _mm_blendv_epi8(a.into(), b.into(), rng.random::<__m128i>()) };

// ...than this
let x = rng.random::<mask8x16>().select(b, a);

Since most bits are unused you could also generate only as many bits as you need, i.e.:

#![feature(portable_simd)]
use std::simd::prelude::*;
use rand::prelude::*;
let mut rng = rand::rng();

let x = u16x8::splat(rng.random::<u8>() as u16);
let mask = u16x8::splat(1) << u16x8::from([0, 1, 2, 3, 4, 5, 6, 7]);
let rand_mask = (x & mask).simd_eq(mask);

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

where StandardUniform: Distribution<T>,

impl<T> Distribution<Wrapping<T>> for StandardUniform

where StandardUniform: Distribution<T>,

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

impl<X> Distribution<usize> for WeightedIndex<X>

where X: SampleUniform + PartialOrd,

Available on crate feature alloc only.

impl<const LANES: usize> Distribution<Simd<i8, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i16, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i32, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<i64, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u8, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u16, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u32, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature

impl<const LANES: usize> Distribution<Simd<u64, LANES>> for StandardUniform

Available on crate feature simd_support only.

Requires nightly Rust and the simd_support feature