Struct rand::distributions::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 range0...0x10_FFFF, except for the range0xD800...0xDFFF(the surrogate code points). This includes unassigned/reserved code points.bool: Generatesfalseortrue, each with probability 0.5.- Floating point types (
f32andf64): 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::fillwhich supports arbitrary array length for integer types and tends to be faster foru32and smaller types. 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 and gen_range (which uses Uniform) use
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).