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 range0...0x10_FFFF
, except for the range0xD800...0xDFFF
(the surrogate code points). This includes unassigned/reserved code points.bool
: Generatesfalse
ortrue
, each with probability 0.5.- Floating point types (
f32
andf64
): 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.
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 (up to 32 elements): each element is generated sequentially;
see also
Rng::fill
which supports arbitrary array length for integer and float types and tends to be faster foru32
and smaller types. When usingrustc
≥ 1.51, enable themin_const_gen
feature to support arrays larger than 32 elements. Note thatRng::fill
andStandard
’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 byStandard
. Option<T>
first generates abool
, and if true generates and returnsSome(value)
wherevalue: T
, otherwise returningNone
.
§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 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> Distribution<[T; 32]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 32]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 31]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 31]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 30]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 30]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 29]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 29]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 28]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 28]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 27]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 27]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 26]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 26]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 25]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 25]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 24]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 24]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 23]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 23]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 22]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 22]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 21]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 21]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 20]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 20]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 19]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 19]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 18]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 18]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 17]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 17]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 16]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 16]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 15]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 15]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 14]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 14]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 13]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 13]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 12]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 12]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 11]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 11]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 10]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 10]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 9]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 9]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 8]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 8]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 7]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 7]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 6]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 6]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 5]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 5]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 4]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 4]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 3]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 3]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 2]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 2]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 1]> for Standardwhere
Standard: Distribution<T>,
impl<T> Distribution<[T; 1]> for Standardwhere
Standard: Distribution<T>,
source§impl<T> Distribution<[T; 0]> for Standard
impl<T> Distribution<[T; 0]> for Standard
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.