Function peroxide::macros::r_macro::random

source ·
pub fn random<T>() -> T
Expand description

Generates a random value using the thread-local random number generator.

This is simply a shortcut for thread_rng().gen(). See thread_rng for documentation of the entropy source and Standard for documentation of distributions and type-specific generation.

§Provided implementations

The following types have provided implementations that 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 range 0...0x10_FFFF, except for the range 0xD800...0xDFFF (the surrogate code points). This includes unassigned/reserved code points.
  • bool: Generates false or true, each with probability 0.5.
  • Floating point types (f32 and f64): 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.

Also supported is the 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 types and tends to be faster for u32 and smaller types.
  • Option<T> first generates a bool, and if true generates and returns Some(value) where value: T, otherwise returning None.

§Examples

let x = rand::random::<u8>();
println!("{}", x);

let y = rand::random::<f64>();
println!("{}", y);

if rand::random() { // generates a boolean
    println!("Better lucky than good!");
}

If you’re calling random() in a loop, caching the generator as in the following example can increase performance.

use rand::Rng;

let mut v = vec![1, 2, 3];

for x in v.iter_mut() {
    *x = rand::random()
}

// can be made faster by caching thread_rng

let mut rng = rand::thread_rng();

for x in v.iter_mut() {
    *x = rng.gen();
}