nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-25 16:24:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: use //! instead of /*! ... */ in std::rand

Browse Source
This commit is contained in:
Jonas Hietala 2014-07-28 17:52:48 +02:00
parent 42ca8a70d6
commit 23b84e55e4
1 changed files with 163 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

330
src/libstd/rand/mod.rs
View File

@ -8,173 +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)
```
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);
}
```
*/
//! 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]