mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-25 16:24:46 +00:00
auto merge of #16041 : treeman/rust/doc-rand, r=brson
A larger example for `std::rand`.
This commit is contained in:
bors
commit
2eb3ab19ac
@ -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]
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user