pub struct StandardUniform;
Expand description
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 range0...0x10_FFFF
, except for the range0xD800...0xDFFF
(the surrogate code points). This includes unassigned/reserved code points. For some uses, theAlphanumeric
distribution will be more appropriate.bool
samplesfalse
ortrue
, each with probability 0.5.- Floating point types (
f32
andf64
) 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]
whereT
is supported. Each element is sampled sequentially and independently. Note that for smallT
this usually results in the RNG discarding random bits; see alsoRng::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
andstd::simd
’su32x4
,f32x4
andmask32x4
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:
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 = StdRng::from_os_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§
Source§impl Clone for StandardUniform
impl Clone for StandardUniform
Source§fn clone(&self) -> StandardUniform
fn clone(&self) -> StandardUniform
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreSource§impl Debug for StandardUniform
impl Debug for StandardUniform
Source§impl Default for StandardUniform
impl Default for StandardUniform
Source§fn default() -> StandardUniform
fn default() -> StandardUniform
Source§impl<'de> Deserialize<'de> for StandardUniform
impl<'de> Deserialize<'de> for StandardUniform
Source§fn deserialize<__D>(
__deserializer: __D,
) -> Result<StandardUniform, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(
__deserializer: __D,
) -> Result<StandardUniform, <__D as Deserializer<'de>>::Error>where
__D: Deserializer<'de>,
Source§impl DistString for StandardUniform
impl DistString for StandardUniform
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 StandardUniformwhere
StandardUniform: Distribution<T>,
impl<T, const N: usize> Distribution<[T; N]> for StandardUniformwhere
StandardUniform: Distribution<T>,
Source§impl Distribution<()> for StandardUniform
impl Distribution<()> for StandardUniform
Source§impl<A> Distribution<(A,)> for StandardUniformwhere
StandardUniform: Distribution<A>,
impl<A> Distribution<(A,)> for StandardUniformwhere
StandardUniform: Distribution<A>,
Source§impl<A, B> Distribution<(A, B)> for StandardUniform
impl<A, B> Distribution<(A, B)> for StandardUniform
Source§impl<A, B, C> Distribution<(A, B, C)> for StandardUniform
impl<A, B, C> Distribution<(A, B, C)> for StandardUniform
Source§impl<A, B, C, D> Distribution<(A, B, C, D)> for StandardUniform
impl<A, B, C, D> Distribution<(A, B, C, D)> for StandardUniform
Source§impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for StandardUniformwhere
StandardUniform: Distribution<A> + Distribution<B> + Distribution<C> + Distribution<D> + Distribution<E>,
impl<A, B, C, D, E> Distribution<(A, B, C, D, E)> for StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
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> Distribution<(A, B, C, D, E, F, G, H)> for StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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 StandardUniformwhere
StandardUniform: 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.