mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-25 16:24:46 +00:00
doc: use //! instead of /*! ... */ in std::rand
This commit is contained in:
Jonas Hietala
parent
42ca8a70d6
commit
23b84e55e4
@ -8,173 +8,169 @@
|
|||||||
// option. This file may not be copied, modified, or distributed
|
// option. This file may not be copied, modified, or distributed
|
||||||
// except according to those terms.
|
// except according to those terms.
|
||||||
|
|
||||||
/*!
|
//! Utilities for random number generation
|
||||||
|
//!
|
||||||
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
|
||||||
The key functions are `random()` and `Rng::gen()`. These are polymorphic
|
//! means that often a simple call to `rand::random()` or `rng.gen()` will
|
||||||
and so can be used to generate any type that implements `Rand`. Type inference
|
//! suffice, but sometimes an annotation is required, e.g. `rand::random::<f64>()`.
|
||||||
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.
|
||||||
See the `distributions` submodule for sampling random numbers from
|
//!
|
||||||
distributions like normal and exponential.
|
//! # Task-local RNG
|
||||||
|
//!
|
||||||
# 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
|
||||||
There is built-in support for a RNG associated with each task stored
|
//! used implicitly via `random`. This RNG is normally randomly seeded
|
||||||
in task-local storage. This RNG can be accessed via `task_rng`, or
|
//! from an operating-system source of randomness, e.g. `/dev/urandom` on
|
||||||
used implicitly via `random`. This RNG is normally randomly seeded
|
//! Unix systems, and will automatically reseed itself from this source
|
||||||
from an operating-system source of randomness, e.g. `/dev/urandom` on
|
//! after generating 32 KiB of random data.
|
||||||
Unix systems, and will automatically reseed itself from this source
|
//!
|
||||||
after generating 32 KiB of random data.
|
//! # Cryptographic security
|
||||||
|
//!
|
||||||
# Cryptographic security
|
//! An application that requires an entropy source for cryptographic purposes
|
||||||
|
//! must use `OsRng`, which reads randomness from the source that the operating
|
||||||
An application that requires an entropy source for cryptographic purposes
|
//! system provides (e.g. `/dev/urandom` on Unixes or `CryptGenRandom()` on Windows).
|
||||||
must use `OsRng`, which reads randomness from the source that the operating
|
//! The other random number generators provided by this module are not suitable
|
||||||
system provides (e.g. `/dev/urandom` on Unixes or `CryptGenRandom()` on Windows).
|
//! for such purposes.
|
||||||
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:
|
||||||
*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
|
||||||
- On Linux, `/dev/random` may block if entropy pool is empty; `/dev/urandom` will not block.
|
//! `/dev/urandom`; the kernel internally runs a cryptographically secure pseudorandom
|
||||||
This does not mean that `/dev/random` provides better output than
|
//! number generator (CSPRNG) based on entropy pool for random number generation,
|
||||||
`/dev/urandom`; the kernel internally runs a cryptographically secure pseudorandom
|
//! so the "quality" of `/dev/random` is not better than `/dev/urandom` in most cases.
|
||||||
number generator (CSPRNG) based on entropy pool for random number generation,
|
//! However, this means that `/dev/urandom` can yield somewhat predictable randomness
|
||||||
so the "quality" of `/dev/random` is not better than `/dev/urandom` in most cases.
|
//! if the entropy pool is very small, such as immediately after first booting.
|
||||||
However, this means that `/dev/urandom` can yield somewhat predictable randomness
|
//! If an application likely to be run soon after first booting, or on a system with very
|
||||||
if the entropy pool is very small, such as immediately after first booting.
|
//! few entropy sources, one should consider using `/dev/random` via `ReaderRng`.
|
||||||
If an application likely to be run soon after first booting, or on a system with very
|
//! - On some systems (e.g. FreeBSD, OpenBSD and Mac OS X) there is no difference
|
||||||
few entropy sources, one should consider using `/dev/random` via `ReaderRng`.
|
//! between the two sources. (Also note that, on some systems e.g. FreeBSD, both `/dev/random`
|
||||||
- On some systems (e.g. FreeBSD, OpenBSD and Mac OS X) there is no difference
|
//! and `/dev/urandom` may block once if the CSPRNG has not seeded yet.)
|
||||||
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
|
||||||
|
//!
|
||||||
# Examples
|
//! ```rust
|
||||||
|
//! use std::rand;
|
||||||
```rust
|
//! use std::rand::Rng;
|
||||||
use std::rand;
|
//!
|
||||||
use std::rand::Rng;
|
//! let mut rng = rand::task_rng();
|
||||||
|
//! if rng.gen() { // random bool
|
||||||
let mut rng = rand::task_rng();
|
//! println!("int: {}, uint: {}", rng.gen::<int>(), rng.gen::<uint>())
|
||||||
if rng.gen() { // random bool
|
//! }
|
||||||
println!("int: {}, uint: {}", rng.gen::<int>(), rng.gen::<uint>())
|
//! ```
|
||||||
}
|
//!
|
||||||
```
|
//! ```rust
|
||||||
|
//! use std::rand;
|
||||||
```rust
|
//!
|
||||||
use std::rand;
|
//! let tuple = rand::random::<(f64, char)>();
|
||||||
|
//! println!("{}", tuple)
|
||||||
let tuple = rand::random::<(f64, char)>();
|
//! ```
|
||||||
println!("{}", tuple)
|
//!
|
||||||
```
|
//! This is a simulation of the [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,
|
||||||
> Suppose you're on a game show, and you're given the choice of three doors:
|
//! > and the host, who knows what's behind the doors, opens another door, say No. 3,
|
||||||
> Behind one door is a car; behind the others, goats. You pick a door, say No. 1,
|
//! > which has a goat. He then says to you, "Do you want to pick door No. 2?"
|
||||||
> and the host, who knows what's behind the doors, opens another door, say No. 3,
|
//! > Is it to your advantage to switch your choice?
|
||||||
> 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.
|
||||||
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.
|
||||||
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
|
||||||
|
//!
|
||||||
[Monty Hall Problem]: http://en.wikipedia.org/wiki/Monty_Hall_problem
|
//! ```
|
||||||
|
//! use std::rand;
|
||||||
```
|
//! use std::rand::Rng;
|
||||||
use std::rand;
|
//! use std::rand::distributions::{IndependentSample, Range};
|
||||||
use std::rand::Rng;
|
//!
|
||||||
use std::rand::distributions::{IndependentSample, Range};
|
//! struct SimulationResult {
|
||||||
|
//! win: bool,
|
||||||
struct SimulationResult {
|
//! switch: bool,
|
||||||
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 {
|
||||||
// Run a single simulation of the Monty Hall problem.
|
//! let car = random_door.ind_sample(rng);
|
||||||
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);
|
||||||
// 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);
|
||||||
// The game host opens a door
|
//!
|
||||||
let open = game_host_open(car, choice, rng);
|
//! // Shall we switch?
|
||||||
|
//! let switch = rng.gen();
|
||||||
// Shall we switch?
|
//! if switch {
|
||||||
let switch = rng.gen();
|
//! choice = switch_door(choice, open);
|
||||||
if switch {
|
//! }
|
||||||
choice = switch_door(choice, open);
|
//!
|
||||||
}
|
//! SimulationResult { win: choice == car, switch: switch }
|
||||||
|
//! }
|
||||||
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.
|
||||||
// Returns the door the game host opens given our choice and knowledge of
|
//! fn game_host_open<R: Rng>(car: uint, choice: uint, rng: &mut R) -> uint {
|
||||||
// where the car is. The game host will never open the door with the car.
|
//! let choices = free_doors(&[car, choice]);
|
||||||
fn game_host_open<R: Rng>(car: uint, choice: uint, rng: &mut R) -> uint {
|
//! rand::sample(rng, choices.move_iter(), 1)[0]
|
||||||
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.
|
||||||
// Returns the door we switch to, given our current choice and
|
//! fn switch_door(choice: uint, open: uint) -> uint {
|
||||||
// the open door. There will only be one valid door.
|
//! free_doors(&[choice, open])[0]
|
||||||
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 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
|
||||||
fn main() {
|
//! let num_simulations = 10000u;
|
||||||
// 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 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);
|
||||||
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) {
|
||||||
println!("Running {} simulations...", num_simulations);
|
//! let result = simulate(&random_door, &mut rng);
|
||||||
for _ in range(0, num_simulations) {
|
//!
|
||||||
let result = simulate(&random_door, &mut rng);
|
//! match (result.win, result.switch) {
|
||||||
|
//! (true, true) => switch_wins += 1,
|
||||||
match (result.win, result.switch) {
|
//! (true, false) => keep_wins += 1,
|
||||||
(true, true) => switch_wins += 1,
|
//! (false, true) => switch_losses += 1,
|
||||||
(true, false) => keep_wins += 1,
|
//! (false, false) => keep_losses += 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;
|
||||||
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!("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);
|
||||||
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.
|
||||||
// With a large number of simulations, the values should converge to
|
//! println!("Estimated chance to win if we switch: {}",
|
||||||
// 0.667 and 0.333 respectively.
|
//! switch_wins as f32 / total_switches as f32);
|
||||||
println!("Estimated chance to win if we switch: {}",
|
//! println!("Estimated chance to win if we don't: {}",
|
||||||
switch_wins as f32 / total_switches as f32);
|
//! keep_wins as f32 / total_keeps as f32);
|
||||||
println!("Estimated chance to win if we don't: {}",
|
//! }
|
||||||
keep_wins as f32 / total_keeps as f32);
|
//! ```
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
*/
|
|
||||||
|
|
||||||
#![experimental]
|
#![experimental]
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user