# Struct rand::distributions::Standard

source · `pub struct Standard;`

## Expand description

A generic random value distribution, implemented for many primitive types. Usually generates values with a numerically uniform distribution, and with a range appropriate to the type.

### Provided implementations

Assuming the provided `Rng`

is well-behaved, these implementations
generate values with the following ranges and distributions:

- Integers (
`i32`

,`u32`

,`isize`

,`usize`

, etc.): Uniformly distributed over all values of the type. `char`

: Uniformly distributed over all Unicode scalar values, i.e. all code points in the range`0...0x10_FFFF`

, except for the range`0xD800...0xDFFF`

(the surrogate code points). This includes unassigned/reserved code points.`bool`

: Generates`false`

or`true`

, each with probability 0.5.- Floating point types (
`f32`

and`f64`

): Uniformly distributed in the half-open range`[0, 1)`

. See notes below. - Wrapping integers (
`Wrapping<T>`

), besides the type identical to their normal integer variants. - Non-zero integers (
`NonZeroU8`

), which are like their normal integer variants but cannot produce zero. - SIMD types like x86’s
`__m128i`

,`std::simd`

’s`u32x4`

/`f32x4`

/`mask32x4`

(requires`simd_support`

), where each lane is distributed like their scalar`Standard`

variants. See the list of`Standard`

implementations for more.

The `Standard`

distribution also supports generation of the following
compound types where all component types are supported:

- Tuples (up to 12 elements): each element is generated sequentially.
- Arrays: each element is generated sequentially;
see also
`Rng::fill`

which supports arbitrary array length for integer and float types and tends to be faster for`u32`

and smaller types. Note that`Rng::fill`

and`Standard`

’s array support are*not*equivalent: the former is optimised for integer types (using fewer RNG calls for element types smaller than the RNG word size), while the latter supports any element type supported by`Standard`

. `Option<T>`

first generates a`bool`

, and if true generates and returns`Some(value)`

where`value: T`

, otherwise returning`None`

.

### Custom implementations

The `Standard`

distribution may be implemented for user types as follows:

```
use rand::Rng;
use rand::distributions::{Distribution, Standard};
struct MyF32 {
x: f32,
}
impl Distribution<MyF32> for Standard {
fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
MyF32 { x: rng.gen() }
}
}
```

### Example usage

```
use rand::prelude::*;
use rand::distributions::Standard;
let val: f32 = StdRng::from_entropy().sample(Standard);
println!("f32 from [0, 1): {}", val);
```

## Floating point implementation

The floating point implementations for `Standard`

generate a random value in
the half-open interval `[0, 1)`

, i.e. including 0 but not 1.

All values that can be generated are of the form `n * ε/2`

. For `f32`

the 24 most significant random bits of a `u32`

are used and for `f64`

the
53 most significant bits of a `u64`

are used. The conversion uses the
multiplicative method: `(rng.gen::<$uty>() >> N) as $ty * (ε/2)`

.

See also: `Open01`

which samples from `(0, 1)`

, `OpenClosed01`

which
samples from `(0, 1]`

and `Rng::gen_range(0..1)`

which also samples from
`[0, 1)`

. Note that `Open01`

uses transmute-based methods which yield 1 bit
less precision but may perform faster on some architectures (on modern Intel
CPUs all methods have approximately equal performance).

## Trait Implementations§

source§### impl<'de> Deserialize<'de> for Standard

### impl<'de> Deserialize<'de> for Standard

source§#### fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,

#### fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

source§### impl DistString for Standard

### impl DistString for Standard

Note: the `String`

is potentially left with excess capacity; optionally the
user may call `string.shrink_to_fit()`

afterwards.

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

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

source§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> [T; N]

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> [T; N]

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<()> for Standard

### impl Distribution<()> for Standard

source§#### fn sample<R: Rng + ?Sized>(&self, _: &mut R)

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

`T`

, using `rng`

as the source of randomness.source§### impl<A> Distribution<(A,)> for Standardwhere
Standard: Distribution<A>,

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

source§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A,)

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

`T`

, using `rng`

as the source of randomness.source§### impl<A, B> Distribution<(A, B)> for Standardwhere
Standard: Distribution<A> + Distribution<B>,

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

source§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B)

`T`

, using `rng`

as the source of randomness.source§### impl<A, B, C> Distribution<(A, B, C)> for Standardwhere
Standard: Distribution<A> + Distribution<B> + Distribution<C>,

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

source§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C)

`T`

, using `rng`

as the source of randomness.source§### impl<A, B, C, D> Distribution<(A, B, C, D)> for Standardwhere
Standard: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D>,

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

source§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G, H)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G, H)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G, H, I)

#### fn sample<R: Rng + ?Sized>(&self, _rng: &mut R) -> (A, B, C, D, E, F, G, H, I)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(
&self,
_rng: &mut R
) -> (A, B, C, D, E, F, G, H, I, J)

#### fn sample<R: Rng + ?Sized>( &self, _rng: &mut R ) -> (A, B, C, D, E, F, G, H, I, J)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(
&self,
_rng: &mut R
) -> (A, B, C, D, E, F, G, H, I, J, K)

#### fn sample<R: Rng + ?Sized>( &self, _rng: &mut R ) -> (A, B, C, D, E, F, G, H, I, J, K)

`T`

, using `rng`

as the source of randomness.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>,

### 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§#### fn sample<R: Rng + ?Sized>(
&self,
_rng: &mut R
) -> (A, B, C, D, E, F, G, H, I, J, K, L)

#### fn sample<R: Rng + ?Sized>( &self, _rng: &mut R ) -> (A, B, C, D, E, F, G, H, I, J, K, L)

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroU128> for Standard

### impl Distribution<NonZeroU128> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroU16> for Standard

### impl Distribution<NonZeroU16> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroU32> for Standard

### impl Distribution<NonZeroU32> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroU64> for Standard

### impl Distribution<NonZeroU64> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroU8> for Standard

### impl Distribution<NonZeroU8> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<NonZeroUsize> for Standard

### impl Distribution<NonZeroUsize> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl<T> Distribution<Option<T>> for Standardwhere
Standard: Distribution<T>,

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

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

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

`T`

, using `rng`

as the source of randomness.source§### impl<T> Distribution<Wrapping<T>> for Standardwhere
Standard: Distribution<T>,

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

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<__m128i> for Standard

### impl Distribution<__m128i> for Standard

Available only on x86/64 platforms

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<__m256i> for Standard

### impl Distribution<__m256i> for Standard

Available only on x86/64 platforms

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<bool> for Standard

### impl Distribution<bool> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<char> for Standard

### impl Distribution<char> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<f32> for Standard

### impl Distribution<f32> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<f64> for Standard

### impl Distribution<f64> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<i128> for Standard

### impl Distribution<i128> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<i16> for Standard

### impl Distribution<i16> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<i32> for Standard

### impl Distribution<i32> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<i64> for Standard

### impl Distribution<i64> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<i8> for Standard

### impl Distribution<i8> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<isize> for Standard

### impl Distribution<isize> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<u128> for Standard

### impl Distribution<u128> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<u16> for Standard

### impl Distribution<u16> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<u32> for Standard

### impl Distribution<u32> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<u64> for Standard

### impl Distribution<u64> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<u8> for Standard

### impl Distribution<u8> for Standard

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

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

`T`

, using `rng`

as the source of randomness.source§### impl Distribution<usize> for Standard

### impl Distribution<usize> for Standard

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

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

`T`

, using `rng`

as the source of randomness.