# Distribution in rand::distributions - Rust
Types (distributions) that can be used to create a random instance of `T`.
Keywords: rust, rustlang, rust-lang, Distribution

# 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>ⓘNotable traits for DistIter<D, R, T>impl<D, R, T> Iterator for DistIter<D, R, T> where
        D: Distribution<T>,
        R: Rng,     type Item = 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: Rng + ?Sized>(&self, rng: &mut R) -> T

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>ⓘNotable traits for DistIter<D, R, T>`impl<D, R, T> Iterator for DistIter<D, R, T> where
D: Distribution<T>,
R: Rng, type Item = 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>> Distribution<T> for &'a D

source

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

## Implementors

source

### impl Distribution<bool> for Bernoulli

source

### impl Distribution<bool> for Standard

source

### impl Distribution<char> for Standard

source

### impl Distribution<f32> for Open01

source

### impl Distribution<f32> for OpenClosed01

source

### impl Distribution<f32> for Standard

source

### impl Distribution<f64> for Open01

source

### impl Distribution<f64> for OpenClosed01

source

### impl Distribution<f64> for Standard

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 Standard

source

### impl Distribution<u128> for Standard

source

### impl Distribution<()> for Standard

source

### impl Distribution<usize> for Standard

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 Standard where
Standard: Distribution<A>,

source

### impl<A, B> Distribution<(A, B)> for Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,

source

### impl<A, B, C> Distribution<(A, B, C)> for Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,

source

### impl<A, B, C, D> Distribution<(A, B, C, D)> for Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,

source

### impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,
Standard: Distribution<E>,

source

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

source

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

source

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

source

### impl<A, B, C, D, E, F, G, H, I> Distribution<(A, B, C, D, E, F, G, H, I)> for Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,
Standard: Distribution<E>,
Standard: Distribution<F>,
Standard: Distribution<G>,
Standard: Distribution<H>,
Standard: 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 Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,
Standard: Distribution<E>,
Standard: Distribution<F>,
Standard: Distribution<G>,
Standard: Distribution<H>,
Standard: Distribution<I>,
Standard: 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 Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,
Standard: Distribution<E>,
Standard: Distribution<F>,
Standard: Distribution<G>,
Standard: Distribution<H>,
Standard: Distribution<I>,
Standard: Distribution<J>,
Standard: 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 Standard where
Standard: Distribution<A>,
Standard: Distribution<B>,
Standard: Distribution<C>,
Standard: Distribution<D>,
Standard: Distribution<E>,
Standard: Distribution<F>,
Standard: Distribution<G>,
Standard: Distribution<H>,
Standard: Distribution<I>,
Standard: Distribution<J>,
Standard: Distribution<K>,
Standard: 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<T> Distribution<Option<T>> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 0]> for Standard

source

### impl<T> Distribution<[T; 1]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 2]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 3]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 4]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 5]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 6]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 7]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 8]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 9]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 10]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 11]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 12]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 13]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 14]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 15]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 16]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 17]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 18]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 19]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 20]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 21]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 22]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 23]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 24]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 25]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 26]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 27]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 28]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 29]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 30]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 31]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<[T; 32]> for Standard where
Standard: Distribution<T>,

source

### impl<T> Distribution<Wrapping<T>> for Standard where
Standard: Distribution<T>,

source

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

source

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