Struct `StandardUniform`

pub struct StandardUniform;

The Standard Uniform distribution

This Distribution is the standard parameterization of Uniform. Bounds are selected according to the output type.

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

Integers (i8, i32, u64, etc.) are uniformly distributed over the whole range of the type (thus each possible value may be sampled with equal probability).
char is 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. For some uses, the Alphanumeric or Alphabetic distribution will be more appropriate.
bool samples false or true, each with probability 0.5.
Floating point types (f32 and f64) are uniformly distributed in the half-open range [0, 1). See also the 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 sample zero.

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

Tuples (up to 12 elements): each element is sampled sequentially and independently (thus, assuming a well-behaved RNG, there is no correlation between elements).
Arrays [T; n] where T is supported. Each element is sampled sequentially and independently. Note that for small T this usually results in the RNG discarding random bits; see also RngExt::fill which offers a more efficient approach to filling an array of integer types with random data.
SIMD types (requires simd_support feature) like x86's __m128i and std::simd's u32x4, f32x4 and mask32x4 types are effectively arrays of integer or floating-point types. Each lane is sampled independently, potentially with more efficient random-bit-usage (and a different resulting value) than would be achieved with sequential sampling (as with the array types above).

Custom implementations

The StandardUniform distribution may be implemented for user types as follows:

# #![allow(dead_code)]
use rand::{Rng, RngExt};
use rand::distr::{Distribution, StandardUniform};

struct MyF32 {
    x: f32,
}

impl Distribution<MyF32> for StandardUniform {
    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
        MyF32 { x: rng.random() }
    }
}

Example usage

use rand::prelude::*;
use rand::distr::StandardUniform;

let val: f32 = rand::rng().sample(StandardUniform);
println!("f32 from [0, 1): {}", val);

Floating point implementation

The floating point implementations for StandardUniform 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::random_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

`impl Clone for StandardUniform`

fn clone(&self) -> StandardUniform

`impl Copy for StandardUniform`

`impl Debug for StandardUniform`

fn fmt(&self, f: &mut Formatter<'_>) -> Result

`impl Default for StandardUniform`

fn default() -> StandardUniform

`impl Distribution<()> for StandardUniform`

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

`impl Distribution<NonZero<i128>> for StandardUniform`

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

`impl Distribution<NonZero<i16>> for StandardUniform`

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

`impl Distribution<NonZero<i32>> for StandardUniform`

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

`impl Distribution<NonZero<i64>> for StandardUniform`

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

`impl Distribution<NonZero<i8>> for StandardUniform`

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

`impl Distribution<NonZero<u128>> for StandardUniform`

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

`impl Distribution<NonZero<u16>> for StandardUniform`

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

`impl Distribution<NonZero<u32>> for StandardUniform`

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

`impl Distribution<NonZero<u64>> for StandardUniform`

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

`impl Distribution<NonZero<u8>> for StandardUniform`

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

`impl Distribution<__m128i> for StandardUniform`

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

`impl Distribution<__m256i> for StandardUniform`

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

`impl Distribution<bool> for StandardUniform`

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

`impl Distribution<char> for StandardUniform`

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

`impl Distribution<f32> for StandardUniform`

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

`impl Distribution<f64> for StandardUniform`

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

`impl Distribution<i128> for StandardUniform`

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

`impl Distribution<i16> for StandardUniform`

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

`impl Distribution<i32> for StandardUniform`

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

`impl Distribution<i64> for StandardUniform`

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

`impl Distribution<i8> for StandardUniform`

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

`impl Distribution<u128> for StandardUniform`

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

`impl Distribution<u16> for StandardUniform`

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

`impl Distribution<u32> for StandardUniform`

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

`impl Distribution<u64> for StandardUniform`

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

`impl Distribution<u8> for StandardUniform`

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

`impl SampleString for StandardUniform`

fn append_string<R: Rng + ?Sized>(&self, rng: &mut R, s: &mut String, len: usize)

`impl Serialize for StandardUniform`

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where __S: Serializer,

`impl<'de> Deserialize<'de> for StandardUniform`

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

`impl<A> Distribution<(A,)> for StandardUniform where StandardUniform: Distribution<A>,`

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

`impl<A, B> Distribution<(A, B)> for StandardUniform where StandardUniform: Distribution<A> + Distribution,`

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

`impl<A, B, C> Distribution<(A, B, C)> for StandardUniform where StandardUniform: Distribution<A> + Distribution + Distribution<C>,`

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

`impl<A, B, C, D> Distribution<(A, B, C, D)> for StandardUniform where StandardUniform: Distribution<A> + Distribution + Distribution<C> + Distribution<D>,`

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

`impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for StandardUniform where StandardUniform: Distribution<A> + Distribution + Distribution<C> + Distribution<D> + Distribution<E>,`

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

`impl<A, B, C, D, E, F> Distribution<(A, B, C, D, E, F)> for StandardUniform where StandardUniform: Distribution<A> + Distribution + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F>,`

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

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

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

`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 + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H>,`

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

`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 + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution,`

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

`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 + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution + Distribution<J>,`

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

`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 + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution + Distribution<J> + Distribution<K>,`

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

`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 + Distribution<C> + Distribution<D> + Distribution<E> + Distribution<F> + Distribution<G> + Distribution<H> + Distribution + Distribution<J> + Distribution<K> + Distribution<L>,`

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

`impl<T> Distribution<Wrapping<T>> for StandardUniform where StandardUniform: Distribution<T>,`

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

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

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

Auto Trait Implementations

`impl Freeze for StandardUniform`

`impl RefUnwindSafe for StandardUniform`

`impl Send for StandardUniform`

`impl Sync for StandardUniform`

`impl Unpin for StandardUniform`

`impl UnsafeUnpin for StandardUniform`

`impl UnwindSafe for StandardUniform`

Blanket Implementations

`impl<T> Any for StandardUniform where T: 'static + ?Sized,`

fn type_id(&self) -> TypeId

`impl<T> Borrow<T> for StandardUniform where T: ?Sized,`

fn borrow(&self) -> &T

`impl<T> BorrowMut<T> for StandardUniform where T: ?Sized,`

fn borrow_mut(&mut self) -> &mut T

`impl<T> CloneToUninit for StandardUniform where T: Clone,`

unsafe fn clone_to_uninit(&self, dest: *mut u8)

`impl<T> DeserializeOwned for StandardUniform where T: for<'de> Deserialize<'de>,`

`impl<T> From<T> for StandardUniform`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for StandardUniform where T: Clone,`

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

`impl<T, U> Into for StandardUniform where U: From<T>,`

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for StandardUniform where U: Into<T>,`

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

`impl<T, U> TryInto for StandardUniform where U: TryFrom<T>,`

type Error = >::Error;
fn try_into(self) -> Result<U, >::Error>

Custom implementations

Example usage

Floating point implementation

Trait Implementations

impl Clone for StandardUniform

impl Copy for StandardUniform

impl Debug for StandardUniform

impl Default for StandardUniform

impl Distribution<()> for StandardUniform

impl Distribution<NonZero<i128>> for StandardUniform

impl Distribution<NonZero<i16>> for StandardUniform

impl Distribution<NonZero<i32>> for StandardUniform

impl Distribution<NonZero<i64>> for StandardUniform

impl Distribution<NonZero<i8>> for StandardUniform

impl Distribution<NonZero<u128>> for StandardUniform

impl Distribution<NonZero<u16>> for StandardUniform

impl Distribution<NonZero<u32>> for StandardUniform

impl Distribution<NonZero<u64>> for StandardUniform

impl Distribution<NonZero<u8>> for StandardUniform

impl Distribution<__m128i> for StandardUniform

impl Distribution<__m256i> for StandardUniform

impl Distribution<bool> for StandardUniform

impl Distribution<char> for StandardUniform

impl Distribution<f32> for StandardUniform

impl Distribution<f64> for StandardUniform

impl Distribution<i128> for StandardUniform

impl Distribution<i16> for StandardUniform

impl Distribution<i32> for StandardUniform

impl Distribution<i64> for StandardUniform

impl Distribution<i8> for StandardUniform

impl Distribution<u128> for StandardUniform

impl Distribution<u16> for StandardUniform

impl Distribution<u32> for StandardUniform

impl Distribution<u64> for StandardUniform

impl Distribution<u8> for StandardUniform

impl SampleString for StandardUniform

impl Serialize for StandardUniform

impl<'de> Deserialize<'de> for StandardUniform

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

impl<A, B> Distribution<(A, B)> for StandardUniform where StandardUniform: Distribution<A> + Distribution<B>,

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

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, 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, 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, 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, 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, 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<T> Distribution<Wrapping<T>> for StandardUniform where StandardUniform: Distribution<T>,

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

Auto Trait Implementations

impl Freeze for StandardUniform

impl RefUnwindSafe for StandardUniform

impl Send for StandardUniform

impl Sync for StandardUniform

impl Unpin for StandardUniform

impl UnsafeUnpin for StandardUniform

impl UnwindSafe for StandardUniform