Struct `StandardUniform`

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 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 Rng::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;
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).

Implementations

`impl Clone for StandardUniform`

fn clone(self: &Self) -> StandardUniform

`impl Copy for StandardUniform`

`impl Debug for StandardUniform`

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

`impl Default for StandardUniform`

fn default() -> StandardUniform

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Distribution for crate::distr::StandardUniform`

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

`impl Freeze for StandardUniform`

`impl RefUnwindSafe for StandardUniform`

`impl SampleString for crate::distr::StandardUniform`

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

`impl Send for StandardUniform`

`impl Serialize for StandardUniform`

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

`impl Sync for StandardUniform`

`impl Unpin for StandardUniform`

`impl UnwindSafe for StandardUniform`

`impl<'de> Deserialize for StandardUniform`

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

`impl<A> Distribution for StandardUniform`

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

`impl<A, B> Distribution for StandardUniform`

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

`impl<A, B, C> Distribution for StandardUniform`

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

`impl<A, B, C, D> Distribution for StandardUniform`

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

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

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

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

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

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

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

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

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

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

fn sample<R: Rng + ?Sized>(self: &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 for StandardUniform`

fn sample<R: Rng + ?Sized>(self: &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 for StandardUniform`

fn sample<R: Rng + ?Sized>(self: &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 for StandardUniform`

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

`impl<T> Any for StandardUniform`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for StandardUniform`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for StandardUniform`

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

`impl<T> CloneToUninit for StandardUniform`

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

`impl<T> DeserializeOwned for StandardUniform`

`impl<T> Distribution for crate::distr::StandardUniform`

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

`impl<T> From for StandardUniform`

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

`impl<T> ToOwned for StandardUniform`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, N: usize> Distribution for crate::distr::StandardUniform`

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

`impl<T, U> Into for StandardUniform`

fn into(self: 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`

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

`impl<T, U> TryInto for StandardUniform`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

`impl<V, T> VZip for StandardUniform`

fn vzip(self: Self) -> V