| // Copyright 2013-2017 The Rust Project Developers. See the COPYRIGHT |
| // file at the top-level directory of this distribution and at |
| // https://rust-lang.org/COPYRIGHT. |
| // |
| // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or |
| // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license |
| // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your |
| // option. This file may not be copied, modified, or distributed |
| // except according to those terms. |
| |
| //! Utilities for random number generation |
| //! |
| //! The key function is `Rng::gen()`. It is polymorphic and so can be used to |
| //! generate any type supporting the [`Uniform`] distribution (i.e. `T` where |
| //! `Uniform`: `Distribution<T>`). Type inference means that often a simple call |
| //! to `rng.gen()` will suffice, but sometimes an annotation is required, e.g. |
| //! `rng.gen::<f64>()`. |
| //! |
| //! See the `distributions` submodule for sampling random numbers from |
| //! distributions like normal and exponential. |
| //! |
| //! # Usage |
| //! |
| //! This crate is [on crates.io](https://crates.io/crates/rand) and can be |
| //! used by adding `rand` to the dependencies in your project's `Cargo.toml`. |
| //! |
| //! ```toml |
| //! [dependencies] |
| //! rand = "0.4" |
| //! ``` |
| //! |
| //! and this to your crate root: |
| //! |
| //! ```rust |
| //! extern crate rand; |
| //! ``` |
| //! |
| //! # Thread-local RNG |
| //! |
| //! There is built-in support for a RNG associated with each thread stored |
| //! in thread-local storage. This RNG can be accessed via `thread_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. Linux 3.17 added the `getrandom(2)` system call which solves |
| //! the issue: it blocks if entropy pool is not initialized yet, but it does |
| //! not block once initialized. `OsRng` tries to use `getrandom(2)` if |
| //! available, and use `/dev/urandom` fallback if not. If an application |
| //! does not have `getrandom` and likely to be run soon after first booting, |
| //! or on a system with very few entropy sources, one should consider using |
| //! `/dev/random` via `ReadRng`. |
| //! - 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 rand::Rng; |
| //! |
| //! let mut rng = rand::thread_rng(); |
| //! if rng.gen() { // random bool |
| //! println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>()) |
| //! } |
| //! ``` |
| //! |
| //! ## Monte Carlo estimation of π |
| //! |
| //! 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 π, |
| //! we have: |
| //! |
| //! ```text |
| //! (area of unit circle) / (area of square) = π / 4 |
| //! ``` |
| //! |
| //! So if we sample many points randomly from the square, roughly π / 4 of them |
| //! should be inside the circle. |
| //! |
| //! We can use the above fact to estimate the value of π: pick many points in |
| //! the square at random, calculate the fraction that fall within the circle, |
| //! and multiply this fraction by 4. |
| //! |
| //! ``` |
| //! use rand::distributions::{Distribution, Range}; |
| //! |
| //! fn main() { |
| //! let between = Range::new(-1f64, 1.); |
| //! let mut rng = rand::thread_rng(); |
| //! |
| //! let total = 1_000_000; |
| //! let mut in_circle = 0; |
| //! |
| //! for _ in 0..total { |
| //! let a = between.sample(&mut rng); |
| //! let b = between.sample(&mut rng); |
| //! if a*a + b*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: |
| //! > 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 if 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]: https://en.wikipedia.org/wiki/Monty_Hall_problem |
| //! |
| //! ``` |
| //! use rand::Rng; |
| //! use rand::distributions::{Distribution, Range}; |
| //! use rand::distributions::range::RangeInt; |
| //! |
| //! struct SimulationResult { |
| //! win: bool, |
| //! switch: bool, |
| //! } |
| //! |
| //! // Run a single simulation of the Monty Hall problem. |
| //! fn simulate<R: Rng>(random_door: &Range<RangeInt<u32>>, rng: &mut R) |
| //! -> SimulationResult { |
| //! let car = random_door.sample(rng); |
| //! |
| //! // This is our initial choice |
| //! let mut choice = random_door.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: u32, choice: u32, rng: &mut R) -> u32 { |
| //! let choices = free_doors(&[car, choice]); |
| //! rand::seq::sample_slice(rng, &choices, 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: u32, open: u32) -> u32 { |
| //! free_doors(&[choice, open])[0] |
| //! } |
| //! |
| //! fn free_doors(blocked: &[u32]) -> Vec<u32> { |
| //! (0..3).filter(|x| !blocked.contains(x)).collect() |
| //! } |
| //! |
| //! fn main() { |
| //! // The estimation will be more accurate with more simulations |
| //! let num_simulations = 10000; |
| //! |
| //! let mut rng = rand::thread_rng(); |
| //! let random_door = Range::new(0u32, 3); |
| //! |
| //! let (mut switch_wins, mut switch_losses) = (0, 0); |
| //! let (mut keep_wins, mut keep_losses) = (0, 0); |
| //! |
| //! println!("Running {} simulations...", num_simulations); |
| //! for _ in 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); |
| //! } |
| //! ``` |
| //! |
| //! [`Uniform`]: distributions/struct.Uniform.html |
| |
| #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", |
| html_favicon_url = "https://www.rust-lang.org/favicon.ico", |
| html_root_url = "https://docs.rs/rand/0.5")] |
| |
| #![deny(missing_debug_implementations)] |
| |
| #![cfg_attr(not(feature="std"), no_std)] |
| #![cfg_attr(all(feature="alloc", not(feature="std")), feature(alloc))] |
| #![cfg_attr(feature = "i128_support", feature(i128_type, i128))] |
| #![cfg_attr(all(target_arch = "wasm32", not(target_os = "emscripten")), recursion_limit="128")] |
| |
| #[cfg(feature="std")] extern crate std as core; |
| #[cfg(all(feature = "alloc", not(feature="std")))] extern crate alloc; |
| |
| #[cfg(test)] #[cfg(feature="serde-1")] extern crate bincode; |
| #[cfg(feature="serde-1")] extern crate serde; |
| #[cfg(feature="serde-1")] #[macro_use] extern crate serde_derive; |
| |
| #[cfg(all(target_arch = "wasm32", not(target_os = "emscripten")))] |
| #[macro_use] |
| extern crate stdweb; |
| |
| extern crate rand_core; |
| |
| #[cfg(feature = "log")] #[macro_use] extern crate log; |
| #[cfg(not(feature = "log"))] macro_rules! trace { ($($x:tt)*) => () } |
| #[cfg(not(feature = "log"))] macro_rules! debug { ($($x:tt)*) => () } |
| #[cfg(all(feature="std", not(feature = "log")))] macro_rules! info { ($($x:tt)*) => () } |
| #[cfg(not(feature = "log"))] macro_rules! warn { ($($x:tt)*) => () } |
| #[cfg(all(feature="std", not(feature = "log")))] macro_rules! error { ($($x:tt)*) => () } |
| |
| |
| use core::{marker, mem, slice}; |
| |
| // re-exports from rand-core |
| pub use rand_core::{RngCore, BlockRngCore, CryptoRng, SeedableRng}; |
| pub use rand_core::{ErrorKind, Error}; |
| |
| // external rngs |
| pub use jitter::JitterRng; |
| #[cfg(feature="std")] pub use os::OsRng; |
| |
| // pseudo rngs |
| pub mod prng; |
| pub use isaac::{IsaacRng, Isaac64Rng}; |
| pub use chacha::ChaChaRng; |
| pub use prng::XorShiftRng; |
| pub use prng::Hc128Rng; |
| |
| // convenience and derived rngs |
| #[cfg(feature="std")] pub use entropy_rng::EntropyRng; |
| #[cfg(feature="std")] pub use thread_rng::{ThreadRng, thread_rng}; |
| #[cfg(feature="std")] #[allow(deprecated)] pub use thread_rng::random; |
| |
| use distributions::{Distribution, Uniform, Range}; |
| use distributions::range::SampleRange; |
| |
| // public modules |
| pub mod distributions; |
| pub mod jitter; |
| pub mod mock; |
| #[cfg(feature="std")] pub mod os; |
| #[cfg(feature="std")] pub mod read; |
| pub mod reseeding; |
| #[cfg(any(feature="std", feature = "alloc"))] pub mod seq; |
| |
| // These tiny modules are here to avoid API breakage, probably only temporarily |
| pub mod chacha { |
| //! The ChaCha random number generator. |
| pub use prng::ChaChaRng; |
| } |
| pub mod isaac { |
| //! The ISAAC random number generator. |
| pub use prng::{IsaacRng, Isaac64Rng}; |
| } |
| |
| // private modules |
| #[cfg(feature="std")] mod entropy_rng; |
| #[cfg(feature="std")] mod thread_rng; |
| |
| |
| /// A type that can be randomly generated using an `Rng`. |
| /// |
| /// This is merely an adaptor around the [`Uniform`] distribution for |
| /// convenience and backwards-compatibility. |
| /// |
| /// [`Uniform`]: distributions/struct.Uniform.html |
| #[deprecated(since="0.5.0", note="replaced by distributions::Uniform")] |
| pub trait Rand : Sized { |
| /// Generates a random instance of this type using the specified source of |
| /// randomness. |
| fn rand<R: Rng>(rng: &mut R) -> Self; |
| } |
| |
| /// An automatically-implemented extension trait on [`RngCore`] providing high-level |
| /// generic methods for sampling values and other convenience methods. |
| /// |
| /// This is the primary trait to use when generating random values. |
| /// |
| /// # Generic usage |
| /// |
| /// The basic pattern is `fn foo<R: Rng + ?Sized>(rng: &mut R)`. Some |
| /// things are worth noting here: |
| /// |
| /// - Since `Rng: RngCore` and every `RngCore` implements `Rng`, it makes no |
| /// difference whether we use `R: Rng` or `R: RngCore`. |
| /// - The `+ ?Sized` un-bounding allows functions to be called directly on |
| /// type-erased references; i.e. `foo(r)` where `r: &mut RngCore`. Without |
| /// this it would be necessary to write `foo(&mut r)`. |
| /// |
| /// An alternative pattern is possible: `fn foo<R: Rng>(rng: R)`. This has some |
| /// trade-offs. It allows the argument to be consumed directly without a `&mut` |
| /// (which is how `from_rng(thread_rng())` works); also it still works directly |
| /// on references (including type-erased references). Unfortunately within the |
| /// function `foo` it is not known whether `rng` is a reference type or not, |
| /// hence many uses of `rng` require an extra reference, either explicitly |
| /// (`distr.sample(&mut rng)`) or implicitly (`rng.gen()`); one may hope the |
| /// optimiser can remove redundant references later. |
| /// |
| /// Example: |
| /// |
| /// ```rust |
| /// use rand::Rng; |
| /// |
| /// fn foo<R: Rng + ?Sized>(rng: &mut R) -> f32 { |
| /// rng.gen() |
| /// } |
| /// ``` |
| /// |
| /// # Iteration |
| /// |
| /// Iteration over an `Rng` can be achieved using `iter::repeat` as follows: |
| /// |
| /// ```rust |
| /// use std::iter; |
| /// use rand::{Rng, thread_rng}; |
| /// use rand::distributions::{Alphanumeric, Range}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// |
| /// // Vec of 16 x f32: |
| /// let v: Vec<f32> = iter::repeat(()).map(|()| rng.gen()).take(16).collect(); |
| /// |
| /// // String: |
| /// let s: String = iter::repeat(()) |
| /// .map(|()| rng.sample(Alphanumeric)) |
| /// .take(7).collect(); |
| /// |
| /// // Dice-rolling: |
| /// let die_range = Range::new_inclusive(1, 6); |
| /// let mut roll_die = iter::repeat(()).map(|()| rng.sample(die_range)); |
| /// while roll_die.next().unwrap() != 6 { |
| /// println!("Not a 6; rolling again!"); |
| /// } |
| /// ``` |
| /// |
| /// [`RngCore`]: https://docs.rs/rand-core/0.1/rand-core/trait.RngCore.html |
| pub trait Rng: RngCore { |
| /// Fill `dest` entirely with random bytes (uniform value distribution), |
| /// where `dest` is any type supporting [`AsByteSliceMut`], namely slices |
| /// and arrays over primitive integer types (`i8`, `i16`, `u32`, etc.). |
| /// |
| /// On big-endian platforms this performs byte-swapping to ensure |
| /// portability of results from reproducible generators. |
| /// |
| /// This uses [`fill_bytes`] internally which may handle some RNG errors |
| /// implicitly (e.g. waiting if the OS generator is not ready), but panics |
| /// on other errors. See also [`try_fill`] which returns errors. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut arr = [0i8; 20]; |
| /// thread_rng().try_fill(&mut arr[..]); |
| /// ``` |
| /// |
| /// [`fill_bytes`]: https://docs.rs/rand-core/0.1/rand-core/trait.RngCore.html#method.fill_bytes |
| /// [`try_fill`]: trait.Rng.html#method.try_fill |
| /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html |
| fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) { |
| self.fill_bytes(dest.as_byte_slice_mut()); |
| dest.to_le(); |
| } |
| |
| /// Fill `dest` entirely with random bytes (uniform value distribution), |
| /// where `dest` is any type supporting [`AsByteSliceMut`], namely slices |
| /// and arrays over primitive integer types (`i8`, `i16`, `u32`, etc.). |
| /// |
| /// On big-endian platforms this performs byte-swapping to ensure |
| /// portability of results from reproducible generators. |
| /// |
| /// This uses [`try_fill_bytes`] internally and forwards all RNG errors. In |
| /// some cases errors may be resolvable; see [`ErrorKind`] and |
| /// documentation for the RNG in use. If you do not plan to handle these |
| /// errors you may prefer to use [`fill`]. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// # use rand::Error; |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// # fn try_inner() -> Result<(), Error> { |
| /// let mut arr = [0u64; 4]; |
| /// thread_rng().try_fill(&mut arr[..])?; |
| /// # Ok(()) |
| /// # } |
| /// |
| /// # try_inner().unwrap() |
| /// ``` |
| /// |
| /// [`ErrorKind`]: https://docs.rs/rand-core/0.1/rand-core/enum.ErrorKind.html |
| /// [`try_fill_bytes`]: https://docs.rs/rand-core/0.1/rand-core/trait.RngCore.html#method.try_fill_bytes |
| /// [`fill`]: trait.Rng.html#method.fill |
| /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html |
| fn try_fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error> { |
| self.try_fill_bytes(dest.as_byte_slice_mut())?; |
| dest.to_le(); |
| Ok(()) |
| } |
| |
| /// Sample a new value, using the given distribution. |
| /// |
| /// ### Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// use rand::distributions::Range; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let x: i32 = rng.sample(Range::new(10, 15)); |
| /// ``` |
| fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T { |
| distr.sample(self) |
| } |
| |
| /// Return a random value supporting the [`Uniform`] distribution. |
| /// |
| /// [`Uniform`]: struct.Uniform.html |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let x: u32 = rng.gen(); |
| /// println!("{}", x); |
| /// println!("{:?}", rng.gen::<(f64, bool)>()); |
| /// ``` |
| #[inline(always)] |
| fn gen<T>(&mut self) -> T where Uniform: Distribution<T> { |
| Uniform.sample(self) |
| } |
| |
| /// Return an iterator that will yield an infinite number of randomly |
| /// generated items. |
| /// |
| /// # Example |
| /// |
| /// ``` |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let x = rng.gen_iter::<u32>().take(10).collect::<Vec<u32>>(); |
| /// println!("{:?}", x); |
| /// println!("{:?}", rng.gen_iter::<(f64, bool)>().take(5) |
| /// .collect::<Vec<(f64, bool)>>()); |
| /// ``` |
| #[allow(deprecated)] |
| #[deprecated(since="0.5.0", note="use iter::repeat instead")] |
| fn gen_iter<T>(&mut self) -> Generator<T, &mut Self> where Uniform: Distribution<T> { |
| Generator { rng: self, _marker: marker::PhantomData } |
| } |
| |
| /// Generate a random value in the range [`low`, `high`), i.e. inclusive of |
| /// `low` and exclusive of `high`. |
| /// |
| /// This is a convenience wrapper around |
| /// `distributions::Range`. If this function will be called |
| /// repeatedly with the same arguments, one should use `Range`, as |
| /// that will amortize the computations that allow for perfect |
| /// uniformity, as they only happen when constructing the `Range`. |
| /// |
| /// # Panics |
| /// |
| /// Panics if `low >= high`. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let n: u32 = rng.gen_range(0, 10); |
| /// println!("{}", n); |
| /// let m: f64 = rng.gen_range(-40.0f64, 1.3e5f64); |
| /// println!("{}", m); |
| /// ``` |
| fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T { |
| Range::sample_single(low, high, self) |
| } |
| |
| /// Return a bool with a 1 in n chance of true |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// #[allow(deprecated)] |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// assert_eq!(rng.gen_weighted_bool(0), true); |
| /// assert_eq!(rng.gen_weighted_bool(1), true); |
| /// // Just like `rng.gen::<bool>()` a 50-50% chance, but using a slower |
| /// // method with different results. |
| /// println!("{}", rng.gen_weighted_bool(2)); |
| /// // First meaningful use of `gen_weighted_bool`. |
| /// println!("{}", rng.gen_weighted_bool(3)); |
| /// ``` |
| #[deprecated(since="0.5.0", note="use gen_bool instead")] |
| fn gen_weighted_bool(&mut self, n: u32) -> bool { |
| // Short-circuit after `n <= 1` to avoid panic in `gen_range` |
| n <= 1 || self.gen_range(0, n) == 0 |
| } |
| |
| /// Return a bool with a probability `p` of being true. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// println!("{}", rng.gen_bool(1.0 / 3.0)); |
| /// ``` |
| fn gen_bool(&mut self, p: f64) -> bool { |
| assert!(p >= 0.0 && p <= 1.0); |
| // If `p` is constant, this will be evaluated at compile-time. |
| let p_int = (p * core::u32::MAX as f64) as u32; |
| self.gen::<u32>() <= p_int |
| } |
| |
| /// Return an iterator of random characters from the set A-Z,a-z,0-9. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// #[allow(deprecated)] |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let s: String = thread_rng().gen_ascii_chars().take(10).collect(); |
| /// println!("{}", s); |
| /// ``` |
| #[allow(deprecated)] |
| #[deprecated(since="0.5.0", note="use distributions::Alphanumeric instead")] |
| fn gen_ascii_chars(&mut self) -> AsciiGenerator<&mut Self> { |
| AsciiGenerator { rng: self } |
| } |
| |
| /// Return a random element from `values`. |
| /// |
| /// Return `None` if `values` is empty. |
| /// |
| /// # Example |
| /// |
| /// ``` |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let choices = [1, 2, 4, 8, 16, 32]; |
| /// let mut rng = thread_rng(); |
| /// println!("{:?}", rng.choose(&choices)); |
| /// assert_eq!(rng.choose(&choices[..0]), None); |
| /// ``` |
| fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> { |
| if values.is_empty() { |
| None |
| } else { |
| Some(&values[self.gen_range(0, values.len())]) |
| } |
| } |
| |
| /// Return a mutable pointer to a random element from `values`. |
| /// |
| /// Return `None` if `values` is empty. |
| fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> { |
| if values.is_empty() { |
| None |
| } else { |
| let len = values.len(); |
| Some(&mut values[self.gen_range(0, len)]) |
| } |
| } |
| |
| /// Shuffle a mutable slice in place. |
| /// |
| /// This applies Durstenfeld's algorithm for the [Fisher–Yates shuffle](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm) |
| /// which produces an unbiased permutation. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, Rng}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let mut y = [1, 2, 3]; |
| /// rng.shuffle(&mut y); |
| /// println!("{:?}", y); |
| /// rng.shuffle(&mut y); |
| /// println!("{:?}", y); |
| /// ``` |
| fn shuffle<T>(&mut self, values: &mut [T]) { |
| let mut i = values.len(); |
| while i >= 2 { |
| // invariant: elements with index >= i have been locked in place. |
| i -= 1; |
| // lock element i in place. |
| values.swap(i, self.gen_range(0, i + 1)); |
| } |
| } |
| } |
| |
| impl<R: RngCore + ?Sized> Rng for R {} |
| |
| /// Trait for casting types to byte slices |
| /// |
| /// This is used by the [`fill`] and [`try_fill`] methods. |
| /// |
| /// [`fill`]: trait.Rng.html#method.fill |
| /// [`try_fill`]: trait.Rng.html#method.try_fill |
| pub trait AsByteSliceMut { |
| /// Return a mutable reference to self as a byte slice |
| fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8]; |
| |
| /// Call `to_le` on each element (i.e. byte-swap on Big Endian platforms). |
| fn to_le(&mut self); |
| } |
| |
| impl AsByteSliceMut for [u8] { |
| fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8] { |
| self |
| } |
| |
| fn to_le(&mut self) {} |
| } |
| |
| macro_rules! impl_as_byte_slice { |
| ($t:ty) => { |
| impl AsByteSliceMut for [$t] { |
| fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8] { |
| unsafe { |
| slice::from_raw_parts_mut(&mut self[0] |
| as *mut $t |
| as *mut u8, |
| self.len() * mem::size_of::<$t>() |
| ) |
| } |
| } |
| |
| fn to_le(&mut self) { |
| for x in self { |
| *x = x.to_le(); |
| } |
| } |
| } |
| } |
| } |
| |
| impl_as_byte_slice!(u16); |
| impl_as_byte_slice!(u32); |
| impl_as_byte_slice!(u64); |
| #[cfg(feature="i128_support")] impl_as_byte_slice!(u128); |
| impl_as_byte_slice!(usize); |
| impl_as_byte_slice!(i8); |
| impl_as_byte_slice!(i16); |
| impl_as_byte_slice!(i32); |
| impl_as_byte_slice!(i64); |
| #[cfg(feature="i128_support")] impl_as_byte_slice!(i128); |
| impl_as_byte_slice!(isize); |
| |
| macro_rules! impl_as_byte_slice_arrays { |
| ($n:expr,) => {}; |
| ($n:expr, $N:ident, $($NN:ident,)*) => { |
| impl_as_byte_slice_arrays!($n - 1, $($NN,)*); |
| |
| impl<T> AsByteSliceMut for [T; $n] where [T]: AsByteSliceMut { |
| fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8] { |
| self[..].as_byte_slice_mut() |
| } |
| |
| fn to_le(&mut self) { |
| self[..].to_le() |
| } |
| } |
| }; |
| } |
| impl_as_byte_slice_arrays!(32, N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,N,); |
| |
| /// Iterator which will generate a stream of random items. |
| /// |
| /// This iterator is created via the [`gen_iter`] method on [`Rng`]. |
| /// |
| /// [`gen_iter`]: trait.Rng.html#method.gen_iter |
| /// [`Rng`]: trait.Rng.html |
| #[derive(Debug)] |
| #[allow(deprecated)] |
| #[deprecated(since="0.5.0", note="use iter::repeat instead")] |
| pub struct Generator<T, R: RngCore> { |
| rng: R, |
| _marker: marker::PhantomData<fn() -> T>, |
| } |
| |
| #[allow(deprecated)] |
| impl<T, R: RngCore> Iterator for Generator<T, R> where Uniform: Distribution<T> { |
| type Item = T; |
| |
| fn next(&mut self) -> Option<T> { |
| Some(self.rng.gen()) |
| } |
| } |
| |
| /// Iterator which will continuously generate random ascii characters. |
| /// |
| /// This iterator is created via the [`gen_ascii_chars`] method on [`Rng`]. |
| /// |
| /// [`gen_ascii_chars`]: trait.Rng.html#method.gen_ascii_chars |
| /// [`Rng`]: trait.Rng.html |
| #[derive(Debug)] |
| #[allow(deprecated)] |
| #[deprecated(since="0.5.0", note="use distributions::Alphanumeric instead")] |
| pub struct AsciiGenerator<R: RngCore> { |
| rng: R, |
| } |
| |
| #[allow(deprecated)] |
| impl<R: RngCore> Iterator for AsciiGenerator<R> { |
| type Item = char; |
| |
| fn next(&mut self) -> Option<char> { |
| const GEN_ASCII_STR_CHARSET: &'static [u8] = |
| b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\ |
| abcdefghijklmnopqrstuvwxyz\ |
| 0123456789"; |
| Some(*self.rng.choose(GEN_ASCII_STR_CHARSET).unwrap() as char) |
| } |
| } |
| |
| |
| /// A convenient way to seed new algorithmic generators, otherwise known as |
| /// pseudo-random number generators (PRNGs). |
| /// |
| /// This is the recommended way to create PRNGs, unless a deterministic seed is |
| /// desired (in which case [`SeedableRng::from_seed`] should be used). |
| /// |
| /// Note: this trait is automatically implemented for any PRNG implementing |
| /// [`SeedableRng`] and is not intended to be implemented by users. |
| /// |
| /// ## Example |
| /// |
| /// ``` |
| /// use rand::{StdRng, Rng, NewRng}; |
| /// |
| /// let mut rng = StdRng::new(); |
| /// println!("Random die roll: {}", rng.gen_range(1, 7)); |
| /// ``` |
| /// |
| /// [`SeedableRng`]: https://docs.rs/rand-core/0.1/rand-core/trait.SeedableRng.html |
| /// [`SeedableRng::from_seed`]: https://docs.rs/rand-core/0.1/rand-core/trait.SeedableRng.html#tymethod.from_seed |
| #[cfg(feature="std")] |
| pub trait NewRng: SeedableRng { |
| /// Creates a new instance, automatically seeded with fresh entropy. |
| /// |
| /// Normally this will use `OsRng`, but if that fails `JitterRng` will be |
| /// used instead. Both should be suitable for cryptography. It is possible |
| /// that both entropy sources will fail though unlikely; failures would |
| /// almost certainly be platform limitations or build issues, i.e. most |
| /// applications targetting PC/mobile platforms should not need to worry |
| /// about this failing. |
| /// |
| /// If all entropy sources fail this will panic. If you need to handle |
| /// errors, use the following code, equivalent aside from error handling: |
| /// |
| /// ```rust |
| /// use rand::{Rng, StdRng, EntropyRng, SeedableRng, Error}; |
| /// |
| /// fn foo() -> Result<(), Error> { |
| /// // This uses StdRng, but is valid for any R: SeedableRng |
| /// let mut rng = StdRng::from_rng(EntropyRng::new())?; |
| /// |
| /// println!("random number: {}", rng.gen_range(1, 10)); |
| /// Ok(()) |
| /// } |
| /// ``` |
| fn new() -> Self; |
| } |
| |
| #[cfg(feature="std")] |
| impl<R: SeedableRng> NewRng for R { |
| fn new() -> R { |
| R::from_rng(EntropyRng::new()).unwrap_or_else(|err| |
| panic!("NewRng::new() failed: {}", err)) |
| } |
| } |
| |
| /// The standard RNG. The PRNG algorithm in `StdRng` is chosen to be efficient |
| /// on the current platform, to be statistically strong and unpredictable |
| /// (meaning a cryptographically secure PRNG). |
| /// |
| /// The current algorithm used on all platforms is [HC-128]. |
| /// |
| /// Reproducibility of output from this generator is however not required, thus |
| /// future library versions may use a different internal generator with |
| /// different output. Further, this generator may not be portable and can |
| /// produce different output depending on the architecture. If you require |
| /// reproducible output, use a named RNG, for example `ChaChaRng`. |
| /// |
| /// [HC-128]: struct.Hc128Rng.html |
| #[derive(Clone, Debug)] |
| pub struct StdRng(Hc128Rng); |
| |
| impl RngCore for StdRng { |
| #[inline(always)] |
| fn next_u32(&mut self) -> u32 { |
| self.0.next_u32() |
| } |
| |
| #[inline(always)] |
| fn next_u64(&mut self) -> u64 { |
| self.0.next_u64() |
| } |
| |
| fn fill_bytes(&mut self, dest: &mut [u8]) { |
| self.0.fill_bytes(dest); |
| } |
| |
| fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> { |
| self.0.try_fill_bytes(dest) |
| } |
| } |
| |
| impl SeedableRng for StdRng { |
| type Seed = <Hc128Rng as SeedableRng>::Seed; |
| |
| fn from_seed(seed: Self::Seed) -> Self { |
| StdRng(Hc128Rng::from_seed(seed)) |
| } |
| |
| fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error> { |
| Hc128Rng::from_rng(rng).map(|result| StdRng(result)) |
| } |
| } |
| |
| impl CryptoRng for StdRng {} |
| |
| /// An RNG recommended when small state, cheap initialization and good |
| /// performance are required. The PRNG algorithm in `SmallRng` is chosen to be |
| /// efficient on the current platform, **without consideration for cryptography |
| /// or security**. The size of its state is much smaller than for `StdRng`. |
| /// |
| /// Reproducibility of output from this generator is however not required, thus |
| /// future library versions may use a different internal generator with |
| /// different output. Further, this generator may not be portable and can |
| /// produce different output depending on the architecture. If you require |
| /// reproducible output, use a named RNG, for example `XorShiftRng`. |
| /// |
| /// The current algorithm used on all platforms is [Xorshift]. |
| /// |
| /// # Examples |
| /// |
| /// Initializing `StdRng` with a random seed can be done using `NewRng`: |
| /// |
| /// ``` |
| /// use rand::{NewRng, SmallRng}; |
| /// |
| /// // Create small, cheap to initialize and fast RNG with a random seed. |
| /// // The randomness is supplied by the operating system. |
| /// let mut small_rng = SmallRng::new(); |
| /// ``` |
| /// |
| /// When initializing a lot of `SmallRng`, using `thread_rng` can be more |
| /// efficient: |
| /// |
| /// ``` |
| /// use std::iter; |
| /// use rand::{SeedableRng, SmallRng, thread_rng}; |
| /// |
| /// // Create a big, expensive to initialize and slower, but unpredictable RNG. |
| /// // This is cached and done only once per thread. |
| /// let mut thread_rng = thread_rng(); |
| /// // Create small, cheap to initialize and fast RNGs with random seeds. |
| /// // One can generally assume this won't fail. |
| /// let rngs: Vec<SmallRng> = iter::repeat(()) |
| /// .map(|()| SmallRng::from_rng(&mut thread_rng).unwrap()) |
| /// .take(10) |
| /// .collect(); |
| /// ``` |
| /// |
| /// [Xorshift]: struct.XorShiftRng.html |
| #[derive(Clone, Debug)] |
| pub struct SmallRng(XorShiftRng); |
| |
| impl RngCore for SmallRng { |
| #[inline(always)] |
| fn next_u32(&mut self) -> u32 { |
| self.0.next_u32() |
| } |
| |
| #[inline(always)] |
| fn next_u64(&mut self) -> u64 { |
| self.0.next_u64() |
| } |
| |
| fn fill_bytes(&mut self, dest: &mut [u8]) { |
| self.0.fill_bytes(dest); |
| } |
| |
| fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> { |
| self.0.try_fill_bytes(dest) |
| } |
| } |
| |
| impl SeedableRng for SmallRng { |
| type Seed = <XorShiftRng as SeedableRng>::Seed; |
| |
| fn from_seed(seed: Self::Seed) -> Self { |
| SmallRng(XorShiftRng::from_seed(seed)) |
| } |
| |
| fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error> { |
| XorShiftRng::from_rng(rng).map(|result| SmallRng(result)) |
| } |
| } |
| |
| /// DEPRECATED: use `SmallRng` instead. |
| /// |
| /// Create a weak random number generator with a default algorithm and seed. |
| /// |
| /// It returns the fastest `Rng` algorithm currently available in Rust without |
| /// consideration for cryptography or security. If you require a specifically |
| /// seeded `Rng` for consistency over time you should pick one algorithm and |
| /// create the `Rng` yourself. |
| /// |
| /// This will seed the generator with randomness from thread_rng. |
| #[deprecated(since="0.5.0", note="removed in favor of SmallRng")] |
| #[cfg(feature="std")] |
| pub fn weak_rng() -> XorShiftRng { |
| XorShiftRng::from_rng(thread_rng()).unwrap_or_else(|err| |
| panic!("weak_rng failed: {:?}", err)) |
| } |
| |
| /// DEPRECATED: use `seq::sample_iter` instead. |
| /// |
| /// Randomly sample up to `amount` elements from a finite iterator. |
| /// The order of elements in the sample is not random. |
| /// |
| /// # Example |
| /// |
| /// ```rust |
| /// use rand::{thread_rng, sample}; |
| /// |
| /// let mut rng = thread_rng(); |
| /// let sample = sample(&mut rng, 1..100, 5); |
| /// println!("{:?}", sample); |
| /// ``` |
| #[cfg(feature="std")] |
| #[inline(always)] |
| #[deprecated(since="0.4.0", note="renamed to seq::sample_iter")] |
| pub fn sample<T, I, R>(rng: &mut R, iterable: I, amount: usize) -> Vec<T> |
| where I: IntoIterator<Item=T>, |
| R: Rng, |
| { |
| // the legacy sample didn't care whether amount was met |
| seq::sample_iter(rng, iterable, amount) |
| .unwrap_or_else(|e| e) |
| } |
| |
| #[cfg(test)] |
| mod test { |
| use mock::StepRng; |
| use super::*; |
| #[cfg(all(not(feature="std"), feature="alloc"))] use alloc::boxed::Box; |
| |
| pub struct TestRng<R> { inner: R } |
| |
| impl<R: RngCore> RngCore for TestRng<R> { |
| fn next_u32(&mut self) -> u32 { |
| self.inner.next_u32() |
| } |
| fn next_u64(&mut self) -> u64 { |
| self.inner.next_u64() |
| } |
| fn fill_bytes(&mut self, dest: &mut [u8]) { |
| self.inner.fill_bytes(dest) |
| } |
| fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> { |
| self.inner.try_fill_bytes(dest) |
| } |
| } |
| |
| pub fn rng(seed: u64) -> TestRng<StdRng> { |
| // TODO: use from_hashable |
| let mut state = seed; |
| let mut seed = <StdRng as SeedableRng>::Seed::default(); |
| for x in seed.iter_mut() { |
| // PCG algorithm |
| const MUL: u64 = 6364136223846793005; |
| const INC: u64 = 11634580027462260723; |
| let oldstate = state; |
| state = oldstate.wrapping_mul(MUL).wrapping_add(INC); |
| |
| let xorshifted = (((oldstate >> 18) ^ oldstate) >> 27) as u32; |
| let rot = (oldstate >> 59) as u32; |
| *x = xorshifted.rotate_right(rot) as u8; |
| } |
| TestRng { inner: StdRng::from_seed(seed) } |
| } |
| |
| #[test] |
| fn test_fill_bytes_default() { |
| let mut r = StepRng::new(0x11_22_33_44_55_66_77_88, 0); |
| |
| // check every remainder mod 8, both in small and big vectors. |
| let lengths = [0, 1, 2, 3, 4, 5, 6, 7, |
| 80, 81, 82, 83, 84, 85, 86, 87]; |
| for &n in lengths.iter() { |
| let mut buffer = [0u8; 87]; |
| let v = &mut buffer[0..n]; |
| r.fill_bytes(v); |
| |
| // use this to get nicer error messages. |
| for (i, &byte) in v.iter().enumerate() { |
| if byte == 0 { |
| panic!("byte {} of {} is zero", i, n) |
| } |
| } |
| } |
| } |
| |
| #[test] |
| fn test_fill() { |
| let x = 9041086907909331047; // a random u64 |
| let mut rng = StepRng::new(x, 0); |
| |
| // Convert to byte sequence and back to u64; byte-swap twice if BE. |
| let mut array = [0u64; 2]; |
| rng.fill(&mut array[..]); |
| assert_eq!(array, [x, x]); |
| assert_eq!(rng.next_u64(), x); |
| |
| // Convert to bytes then u32 in LE order |
| let mut array = [0u32; 2]; |
| rng.fill(&mut array[..]); |
| assert_eq!(array, [x as u32, (x >> 32) as u32]); |
| assert_eq!(rng.next_u32(), x as u32); |
| } |
| |
| #[test] |
| fn test_gen_range() { |
| let mut r = rng(101); |
| for _ in 0..1000 { |
| let a = r.gen_range(-3, 42); |
| assert!(a >= -3 && a < 42); |
| assert_eq!(r.gen_range(0, 1), 0); |
| assert_eq!(r.gen_range(-12, -11), -12); |
| } |
| |
| for _ in 0..1000 { |
| let a = r.gen_range(10, 42); |
| assert!(a >= 10 && a < 42); |
| assert_eq!(r.gen_range(0, 1), 0); |
| assert_eq!(r.gen_range(3_000_000, 3_000_001), 3_000_000); |
| } |
| |
| } |
| |
| #[test] |
| #[should_panic] |
| fn test_gen_range_panic_int() { |
| let mut r = rng(102); |
| r.gen_range(5, -2); |
| } |
| |
| #[test] |
| #[should_panic] |
| fn test_gen_range_panic_usize() { |
| let mut r = rng(103); |
| r.gen_range(5, 2); |
| } |
| |
| #[test] |
| #[allow(deprecated)] |
| fn test_gen_weighted_bool() { |
| let mut r = rng(104); |
| assert_eq!(r.gen_weighted_bool(0), true); |
| assert_eq!(r.gen_weighted_bool(1), true); |
| } |
| |
| #[test] |
| fn test_gen_bool() { |
| let mut r = rng(105); |
| for _ in 0..5 { |
| assert_eq!(r.gen_bool(0.0), false); |
| assert_eq!(r.gen_bool(1.0), true); |
| } |
| } |
| |
| #[test] |
| fn test_choose() { |
| let mut r = rng(107); |
| assert_eq!(r.choose(&[1, 1, 1]).map(|&x|x), Some(1)); |
| |
| let v: &[isize] = &[]; |
| assert_eq!(r.choose(v), None); |
| } |
| |
| #[test] |
| fn test_shuffle() { |
| let mut r = rng(108); |
| let empty: &mut [isize] = &mut []; |
| r.shuffle(empty); |
| let mut one = [1]; |
| r.shuffle(&mut one); |
| let b: &[_] = &[1]; |
| assert_eq!(one, b); |
| |
| let mut two = [1, 2]; |
| r.shuffle(&mut two); |
| assert!(two == [1, 2] || two == [2, 1]); |
| |
| let mut x = [1, 1, 1]; |
| r.shuffle(&mut x); |
| let b: &[_] = &[1, 1, 1]; |
| assert_eq!(x, b); |
| } |
| |
| #[test] |
| fn test_rng_trait_object() { |
| use distributions::{Distribution, Uniform}; |
| let mut rng = rng(109); |
| let mut r = &mut rng as &mut RngCore; |
| r.next_u32(); |
| r.gen::<i32>(); |
| let mut v = [1, 1, 1]; |
| r.shuffle(&mut v); |
| let b: &[_] = &[1, 1, 1]; |
| assert_eq!(v, b); |
| assert_eq!(r.gen_range(0, 1), 0); |
| let _c: u8 = Uniform.sample(&mut r); |
| } |
| |
| #[test] |
| #[cfg(any(feature="std", feature="alloc"))] |
| fn test_rng_boxed_trait() { |
| use distributions::{Distribution, Uniform}; |
| let rng = rng(110); |
| let mut r = Box::new(rng) as Box<RngCore>; |
| r.next_u32(); |
| r.gen::<i32>(); |
| let mut v = [1, 1, 1]; |
| r.shuffle(&mut v); |
| let b: &[_] = &[1, 1, 1]; |
| assert_eq!(v, b); |
| assert_eq!(r.gen_range(0, 1), 0); |
| let _c: u8 = Uniform.sample(&mut r); |
| } |
| |
| #[test] |
| fn test_stdrng_construction() { |
| let seed = [1,0,0,0, 23,0,0,0, 200,1,0,0, 210,30,0,0, |
| 0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0]; |
| let mut rng1 = StdRng::from_seed(seed); |
| assert_eq!(rng1.next_u64(), 15759097995037006553); |
| |
| let mut rng2 = StdRng::from_rng(rng1).unwrap(); |
| assert_eq!(rng2.next_u64(), 6766915756997287454); |
| } |
| } |