Add example of estimating pi using Monte Carlo simulation to std::rand

src/libstd/rand/mod.rs

@@ -70,6 +70,51 @@
 //! println!("{}", tuple)
 //! ```
 //!
+//! ## Monte Carlo estimation of pi
+//!
+//! 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 pi,
+//! the ratio
+//!
+//!     (area of unit circle) / (area of square)
+//!
+//! is equal to pi / 4. So if we sample many points randomly from the square,
+//! roughly pi / 4 of them should be inside the circle.
+//!
+//! We can use the above fact to estimate the value of pi: pick many points in the
+//! square at random, calculate the fraction that fall within the circle, and
+//! multiply this fraction by 4.
+//!
+//! ```
+//! use std::rand;
+//! use std::rand::distributions::{IndependentSample, Range};
+//!
+//! fn dist(x: f64, y: f64) -> f64 {
+//!    (x*x + y*y).sqrt()
+//! }
+//!
+//! fn main() {
+//!    let between = Range::new(-1f64, 1.);
+//!    let mut rng = rand::task_rng();
+//!
+//!    let total = 1_000_000u;
+//!    let mut in_circle = 0u;
+//!
+//!    for _ in range(0u, total) {
+//!        let a = between.ind_sample(&mut rng);
+//!        let b = between.ind_sample(&mut rng);
+//!        if dist(a, 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: