# [−][src]Crate rand

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.4"
```

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::seq::sample_slice(rng, &choices, 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); }

## Re-exports

`pub use jitter::JitterRng;` |

`pub use os::OsRng;` |

## Modules

chacha | The ChaCha random number generator. |

distributions | Sampling from random distributions. |

isaac | The ISAAC random number generator. |

jitter | Non-physical true random number generator based on timing jitter. |

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. |

seq | Functions for randomly accessing and sampling sequences. |

## Structs

AsciiGenerator | Iterator which will continuously generate random ascii characters. |

ChaChaRng | A random number generator that uses the ChaCha20 algorithm [1]. |

Closed01 | A wrapper for generating floating point numbers uniformly in the
closed interval |

Generator | Iterator which will generate a stream of random items. |

Isaac64Rng | A random number generator that uses ISAAC-64[1], the 64-bit variant of the ISAAC algorithm. |

IsaacRng | A random number generator that uses the ISAAC algorithm[1]. |

Open01 | A wrapper for generating floating point numbers uniformly in the
open interval |

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 | 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 | [ Deprecated ] DEPRECATED: use |

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. |

weak_rng | Create a weak random number generator with a default algorithm and seed. |