Crate rand [−] [src]

Utilities for random number generation

The key functions are random() and Rng::gen(). These are polymorphic and so can be used to generate any type that implements Rand. Type inference means that often a simple call to rand::random() or rng.gen() will suffice, but sometimes an annotation is required, e.g. rand::random::<f64>().

See the distributions submodule for sampling random numbers from distributions like normal and exponential.

Usage

This crate is on crates.io and can be used by adding rand to the dependencies in your project's Cargo.toml.

[dependencies]
rand = "0.3"

and this to your crate root:

extern crate rand;

Thread-local RNG

There is built-in support for a RNG associated with each thread stored in thread-local storage. This RNG can be accessed via thread_rng, or used implicitly via random. This RNG is normally randomly seeded from an operating-system source of randomness, e.g. /dev/urandom on Unix systems, and will automatically reseed itself from this source after generating 32 KiB of random data.

Cryptographic security

An application that requires an entropy source for cryptographic purposes must use OsRng, which reads randomness from the source that the operating system provides (e.g. /dev/urandom on Unixes or CryptGenRandom() on Windows). The other random number generators provided by this module are not suitable for such purposes.

Note: many Unix systems provide /dev/random as well as /dev/urandom. This module uses /dev/urandom for the following reasons:

On Linux, /dev/random may block if entropy pool is empty; /dev/urandom will not block. This does not mean that /dev/random provides better output than /dev/urandom; the kernel internally runs a cryptographically secure pseudorandom number generator (CSPRNG) based on entropy pool for random number generation, so the "quality" of /dev/random is not better than /dev/urandom in most cases. However, this means that /dev/urandom can yield somewhat predictable randomness if the entropy pool is very small, such as immediately after first booting. Linux 3.17 added the getrandom(2) system call which solves the issue: it blocks if entropy pool is not initialized yet, but it does not block once initialized. OsRng tries to use getrandom(2) if available, and use /dev/urandom fallback if not. If an application does not have getrandom and likely to be run soon after first booting, or on a system with very few entropy sources, one should consider using /dev/random via ReadRng.
On some systems (e.g. FreeBSD, OpenBSD and Mac OS X) there is no difference between the two sources. (Also note that, on some systems e.g. FreeBSD, both /dev/random and /dev/urandom may block once if the CSPRNG has not seeded yet.)

Examples

use rand::Rng;

let mut rng = rand::thread_rng();
if rng.gen() { // random bool
    println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>())
}

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

Monte Carlo estimation of π

For this example, imagine we have a square with sides of length 2 and a unit circle, both centered at the origin. Since the area of a unit circle is π, we have:

    (area of unit circle) / (area of square) = π / 4

So if we sample many points randomly from the square, roughly π / 4 of them should be inside the circle.

We can use the above fact to estimate the value of π: pick many points in the square at random, calculate the fraction that fall within the circle, and multiply this fraction by 4.

use rand::distributions::{IndependentSample, Range};

fn main() {
   let between = Range::new(-1f64, 1.);
   let mut rng = rand::thread_rng();

   let total = 1_000_000;
   let mut in_circle = 0;

   for _ in 0..total {
       let a = between.ind_sample(&mut rng);
       let b = between.ind_sample(&mut rng);
       if a*a + b*b <= 1. {
           in_circle += 1;
       }
   }

   // prints something close to 3.14159...
   println!("{}", 4. * (in_circle as f64) / (total as f64));
}

Monty Hall Problem

This is a simulation of the Monty Hall Problem:

Suppose you're on a game show, and you're given the choice of three doors: Behind one door is a car; behind the others, goats. You pick a door, say No. 1, and the host, who knows what's behind the doors, opens another door, say No. 3, which has a goat. He then says to you, "Do you want to pick door No. 2?" Is it to your advantage to switch your choice?

The rather unintuitive answer is that you will have a 2/3 chance of winning if you switch and a 1/3 chance of winning if you don't, so it's better to switch.

This program will simulate the game show and with large enough simulation steps it will indeed confirm that it is better to switch.

use rand::Rng;
use rand::distributions::{IndependentSample, Range};

struct SimulationResult {
    win: bool,
    switch: bool,
}

// Run a single simulation of the Monty Hall problem.
fn simulate<R: Rng>(random_door: &Range<u32>, rng: &mut R)
                    -> SimulationResult {
    let car = random_door.ind_sample(rng);

    // This is our initial choice
    let mut choice = random_door.ind_sample(rng);

    // The game host opens a door
    let open = game_host_open(car, choice, rng);

    // Shall we switch?
    let switch = rng.gen();
    if switch {
        choice = switch_door(choice, open);
    }

    SimulationResult { win: choice == car, switch: switch }
}

// Returns the door the game host opens given our choice and knowledge of
// where the car is. The game host will never open the door with the car.
fn game_host_open<R: Rng>(car: u32, choice: u32, rng: &mut R) -> u32 {
    let choices = free_doors(&[car, choice]);
    rand::sample(rng, choices.into_iter(), 1)[0]
}

// Returns the door we switch to, given our current choice and
// the open door. There will only be one valid door.
fn switch_door(choice: u32, open: u32) -> u32 {
    free_doors(&[choice, open])[0]
}

fn free_doors(blocked: &[u32]) -> Vec<u32> {
    (0..3).filter(|x| !blocked.contains(x)).collect()
}

fn main() {
    // The estimation will be more accurate with more simulations
    let num_simulations = 10000;

    let mut rng = rand::thread_rng();
    let random_door = Range::new(0, 3);

    let (mut switch_wins, mut switch_losses) = (0, 0);
    let (mut keep_wins, mut keep_losses) = (0, 0);

    println!("Running {} simulations...", num_simulations);
    for _ in 0..num_simulations {
        let result = simulate(&random_door, &mut rng);

        match (result.win, result.switch) {
            (true, true) => switch_wins += 1,
            (true, false) => keep_wins += 1,
            (false, true) => switch_losses += 1,
            (false, false) => keep_losses += 1,
        }
    }

    let total_switches = switch_wins + switch_losses;
    let total_keeps = keep_wins + keep_losses;

    println!("Switched door {} times with {} wins and {} losses",
             total_switches, switch_wins, switch_losses);

    println!("Kept our choice {} times with {} wins and {} losses",
             total_keeps, keep_wins, keep_losses);

    // With a large number of simulations, the values should converge to
    // 0.667 and 0.333 respectively.
    println!("Estimated chance to win if we switch: {}",
             switch_wins as f32 / total_switches as f32);
    println!("Estimated chance to win if we don't: {}",
             keep_wins as f32 / total_keeps as f32);
}

Reexports

pub use os::OsRng;

pub use isaac::{IsaacRng, Isaac64Rng};

pub use chacha::ChaChaRng;

Modules

chacha	The ChaCha random number generator.
distributions	Sampling from random distributions.
isaac	The ISAAC random number generator.
os	Interfaces to the operating system provided random number generators.
read	A wrapper around any Read to treat it as an RNG.
reseeding	A wrapper around another RNG that reseeds it after it generates a certain number of random bytes.

Structs

AsciiGenerator	Iterator which will continuously generate random ascii characters.
Closed01	A wrapper for generating floating point numbers uniformly in the closed interval `[0,1]` (including both endpoints).
Generator	Iterator which will generate a stream of random items.
Open01	A wrapper for generating floating point numbers uniformly in the open interval `(0,1)` (not including either endpoint).
StdRng	The standard RNG. This is designed to be efficient on the current platform.
ThreadRng	The thread-local RNG.
XorShiftRng	An Xorshift[1] random number generator.

Traits

Rand	A type that can be randomly generated using an `Rng`.
Rng	A random number generator.
SeedableRng	A random number generator that can be explicitly seeded to produce the same stream of randomness multiple times.

Functions

random	Generates a random value using the thread-local random number generator.
sample	Randomly sample up to `amount` elements from an iterator.
thread_rng	Retrieve the lazily-initialized thread-local random number generator, seeded by the system. Intended to be used in method chaining style, e.g. `thread_rng().gen::<i32>()`.
weak_rng	Create a weak random number generator with a default algorithm and seed.