Skip to content

Commit

Permalink
auto merge of #16041 : treeman/rust/doc-rand, r=brson
Browse files Browse the repository at this point in the history 
A larger example for `std::rand`.
  • Loading branch information
@bors
bors committed Jul 31, 2014
2 parents 8c00357 + 23b84e5 commit 2eb3ab1
Showing 1 changed file with 163 additions and 64 deletions.
227 changes: 163 additions & 64 deletions src/libstd/rand/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,70 +8,169 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.

/*!
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.
# Task-local RNG
There is built-in support for a RNG associated with each task stored
in task-local storage. This RNG can be accessed via `task_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.
If an application likely to be run soon after first booting, or on a system with very
few entropy sources, one should consider using `/dev/random` via `ReaderRng`.
- 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
```rust
use std::rand;
use std::rand::Rng;
let mut rng = rand::task_rng();
if rng.gen() { // random bool
println!("int: {}, uint: {}", rng.gen::<int>(), rng.gen::<uint>())
}
```
```rust
use std::rand;
let tuple = rand::random::<(f64, char)>();
println!("{}", tuple)
```
*/
//! 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.
//!
//! # Task-local RNG
//!
//! There is built-in support for a RNG associated with each task stored
//! in task-local storage. This RNG can be accessed via `task_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.
//! If an application likely to be run soon after first booting, or on a system with very
//! few entropy sources, one should consider using `/dev/random` via `ReaderRng`.
//! - 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
//!
//! ```rust
//! use std::rand;
//! use std::rand::Rng;
//!
//! let mut rng = rand::task_rng();
//! if rng.gen() { // random bool
//! println!("int: {}, uint: {}", rng.gen::<int>(), rng.gen::<uint>())
//! }
//! ```
//!
//! ```rust
//! use std::rand;
//!
//! let tuple = rand::random::<(f64, char)>();
//! println!("{}", tuple)
//! ```
//!
//! 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 of 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.
//!
//! [Monty Hall Problem]: http://en.wikipedia.org/wiki/Monty_Hall_problem
//!
//! ```
//! use std::rand;
//! use std::rand::Rng;
//! use std::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<uint>, 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: uint, choice: uint, rng: &mut R) -> uint {
//! let choices = free_doors(&[car, choice]);
//! rand::sample(rng, choices.move_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: uint, open: uint) -> uint {
//! free_doors(&[choice, open])[0]
//! }
//!
//! fn free_doors(blocked: &[uint]) -> Vec<uint> {
//! range(0u, 3).filter(|x| !blocked.contains(x)).collect()
//! }
//!
//! fn main() {
//! // The estimation will be more accurate with more simulations
//! let num_simulations = 10000u;
//!
//! let mut rng = rand::task_rng();
//! let random_door = Range::new(0u, 3);
//!
//! let (mut switch_wins, mut switch_losses) = (0u, 0u);
//! let (mut keep_wins, mut keep_losses) = (0u, 0u);
//!
//! println!("Running {} simulations...", num_simulations);
//! for _ in range(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);
//! }
//! ```

#![experimental]

Expand Down

0 comments on commit 2eb3ab1

Please sign in to comment.