# Struct rand_distr::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.random() }
}
}
```

### §Example usage

```
use rand::prelude::*;
use rand::distributions::Standard;
let val: f32 = StdRng::from_os_rng().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<Standard, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,

#### fn deserialize<__D>(
__deserializer: __D
) -> Result<Standard, <__D as Deserializer<'de>>::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§### impl Distribution<()> for Standard

### impl Distribution<()> for Standard

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

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

source§### impl<A, B> Distribution<(A, B)> for Standard

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

source§### impl<A, B, C> Distribution<(A, B, C)> for Standard

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

source§### impl<A, B, C, D> Distribution<(A, B, C, D)> for Standard

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

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§### 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§### 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§### 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>(&self, rng: &mut R) -> (A, B, C, D, E, F, G, H)

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

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

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

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

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

`T`

, using `rng`

as the source of randomness.