1 // Copyright 2018 Developers of the Rand project. 2 // Copyright 2013-2017 The Rust Project Developers. 3 // 4 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or 5 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license 6 // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your 7 // option. This file may not be copied, modified, or distributed 8 // except according to those terms. 9 10 //! Generating random samples from probability distributions 11 //! 12 //! This module is the home of the [`Distribution`] trait and several of its 13 //! implementations. It is the workhorse behind some of the convenient 14 //! functionality of the [`Rng`] trait, e.g. [`Rng::gen`] and of course 15 //! [`Rng::sample`]. 16 //! 17 //! Abstractly, a [probability distribution] describes the probability of 18 //! occurrence of each value in its sample space. 19 //! 20 //! More concretely, an implementation of `Distribution<T>` for type `X` is an 21 //! algorithm for choosing values from the sample space (a subset of `T`) 22 //! according to the distribution `X` represents, using an external source of 23 //! randomness (an RNG supplied to the `sample` function). 24 //! 25 //! A type `X` may implement `Distribution<T>` for multiple types `T`. 26 //! Any type implementing [`Distribution`] is stateless (i.e. immutable), 27 //! but it may have internal parameters set at construction time (for example, 28 //! [`Uniform`] allows specification of its sample space as a range within `T`). 29 //! 30 //! 31 //! # The `Standard` distribution 32 //! 33 //! The [`Standard`] distribution is important to mention. This is the 34 //! distribution used by [`Rng::gen`] and represents the "default" way to 35 //! produce a random value for many different types, including most primitive 36 //! types, tuples, arrays, and a few derived types. See the documentation of 37 //! [`Standard`] for more details. 38 //! 39 //! Implementing `Distribution<T>` for [`Standard`] for user types `T` makes it 40 //! possible to generate type `T` with [`Rng::gen`], and by extension also 41 //! with the [`random`] function. 42 //! 43 //! ## Random characters 44 //! 45 //! [`Alphanumeric`] is a simple distribution to sample random letters and 46 //! numbers of the `char` type; in contrast [`Standard`] may sample any valid 47 //! `char`. 48 //! 49 //! 50 //! # Uniform numeric ranges 51 //! 52 //! The [`Uniform`] distribution is more flexible than [`Standard`], but also 53 //! more specialised: it supports fewer target types, but allows the sample 54 //! space to be specified as an arbitrary range within its target type `T`. 55 //! Both [`Standard`] and [`Uniform`] are in some sense uniform distributions. 56 //! 57 //! Values may be sampled from this distribution using [`Rng::sample(Range)`] or 58 //! by creating a distribution object with [`Uniform::new`], 59 //! [`Uniform::new_inclusive`] or `From<Range>`. When the range limits are not 60 //! known at compile time it is typically faster to reuse an existing 61 //! `Uniform` object than to call [`Rng::sample(Range)`]. 62 //! 63 //! User types `T` may also implement `Distribution<T>` for [`Uniform`], 64 //! although this is less straightforward than for [`Standard`] (see the 65 //! documentation in the [`uniform`] module). Doing so enables generation of 66 //! values of type `T` with [`Rng::sample(Range)`]. 67 //! 68 //! ## Open and half-open ranges 69 //! 70 //! There are surprisingly many ways to uniformly generate random floats. A 71 //! range between 0 and 1 is standard, but the exact bounds (open vs closed) 72 //! and accuracy differ. In addition to the [`Standard`] distribution Rand offers 73 //! [`Open01`] and [`OpenClosed01`]. See "Floating point implementation" section of 74 //! [`Standard`] documentation for more details. 75 //! 76 //! # Non-uniform sampling 77 //! 78 //! Sampling a simple true/false outcome with a given probability has a name: 79 //! the [`Bernoulli`] distribution (this is used by [`Rng::gen_bool`]). 80 //! 81 //! For weighted sampling from a sequence of discrete values, use the 82 //! [`WeightedIndex`] distribution. 83 //! 84 //! This crate no longer includes other non-uniform distributions; instead 85 //! it is recommended that you use either [`rand_distr`] or [`statrs`]. 86 //! 87 //! 88 //! [probability distribution]: https://en.wikipedia.org/wiki/Probability_distribution 89 //! [`rand_distr`]: https://crates.io/crates/rand_distr 90 //! [`statrs`]: https://crates.io/crates/statrs 91 92 //! [`random`]: crate::random 93 //! [`rand_distr`]: https://crates.io/crates/rand_distr 94 //! [`statrs`]: https://crates.io/crates/statrs 95 96 mod bernoulli; 97 mod distribution; 98 mod float; 99 mod integer; 100 mod other; 101 mod slice; 102 mod utils; 103 #[cfg(feature = "alloc")] 104 mod weighted_index; 105 106 #[doc(hidden)] 107 pub mod hidden_export { 108 pub use super::float::IntoFloat; // used by rand_distr 109 } 110 pub mod uniform; 111 #[deprecated( 112 since = "0.8.0", 113 note = "use rand::distributions::{WeightedIndex, WeightedError} instead" 114 )] 115 #[cfg(feature = "alloc")] 116 #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] 117 pub mod weighted; 118 119 pub use self::bernoulli::{Bernoulli, BernoulliError}; 120 pub use self::distribution::{Distribution, DistIter, DistMap}; 121 #[cfg(feature = "alloc")] 122 pub use self::distribution::DistString; 123 pub use self::float::{Open01, OpenClosed01}; 124 pub use self::other::Alphanumeric; 125 pub use self::slice::Slice; 126 #[doc(inline)] 127 pub use self::uniform::Uniform; 128 #[cfg(feature = "alloc")] 129 pub use self::weighted_index::{WeightedError, WeightedIndex}; 130 131 #[allow(unused)] 132 use crate::Rng; 133 134 /// A generic random value distribution, implemented for many primitive types. 135 /// Usually generates values with a numerically uniform distribution, and with a 136 /// range appropriate to the type. 137 /// 138 /// ## Provided implementations 139 /// 140 /// Assuming the provided `Rng` is well-behaved, these implementations 141 /// generate values with the following ranges and distributions: 142 /// 143 /// * Integers (`i32`, `u32`, `isize`, `usize`, etc.): Uniformly distributed 144 /// over all values of the type. 145 /// * `char`: Uniformly distributed over all Unicode scalar values, i.e. all 146 /// code points in the range `0...0x10_FFFF`, except for the range 147 /// `0xD800...0xDFFF` (the surrogate code points). This includes 148 /// unassigned/reserved code points. 149 /// * `bool`: Generates `false` or `true`, each with probability 0.5. 150 /// * Floating point types (`f32` and `f64`): Uniformly distributed in the 151 /// half-open range `[0, 1)`. See notes below. 152 /// * Wrapping integers (`Wrapping<T>`), besides the type identical to their 153 /// normal integer variants. 154 /// 155 /// The `Standard` distribution also supports generation of the following 156 /// compound types where all component types are supported: 157 /// 158 /// * Tuples (up to 12 elements): each element is generated sequentially. 159 /// * Arrays (up to 32 elements): each element is generated sequentially; 160 /// see also [`Rng::fill`] which supports arbitrary array length for integer 161 /// types and tends to be faster for `u32` and smaller types. 162 /// When using `rustc` ≥ 1.51, enable the `min_const_gen` feature to support 163 /// arrays larger than 32 elements. 164 /// Note that [`Rng::fill`] and `Standard`'s array support are *not* equivalent: 165 /// the former is optimised for integer types (using fewer RNG calls for 166 /// element types smaller than the RNG word size), while the latter supports 167 /// any element type supported by `Standard`. 168 /// * `Option<T>` first generates a `bool`, and if true generates and returns 169 /// `Some(value)` where `value: T`, otherwise returning `None`. 170 /// 171 /// ## Custom implementations 172 /// 173 /// The [`Standard`] distribution may be implemented for user types as follows: 174 /// 175 /// ``` 176 /// # #![allow(dead_code)] 177 /// use rand::Rng; 178 /// use rand::distributions::{Distribution, Standard}; 179 /// 180 /// struct MyF32 { 181 /// x: f32, 182 /// } 183 /// 184 /// impl Distribution<MyF32> for Standard { 185 /// fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 { 186 /// MyF32 { x: rng.gen() } 187 /// } 188 /// } 189 /// ``` 190 /// 191 /// ## Example usage 192 /// ``` 193 /// use rand::prelude::*; 194 /// use rand::distributions::Standard; 195 /// 196 /// let val: f32 = StdRng::from_entropy().sample(Standard); 197 /// println!("f32 from [0, 1): {}", val); 198 /// ``` 199 /// 200 /// # Floating point implementation 201 /// The floating point implementations for `Standard` generate a random value in 202 /// the half-open interval `[0, 1)`, i.e. including 0 but not 1. 203 /// 204 /// All values that can be generated are of the form `n * ε/2`. For `f32` 205 /// the 24 most significant random bits of a `u32` are used and for `f64` the 206 /// 53 most significant bits of a `u64` are used. The conversion uses the 207 /// multiplicative method: `(rng.gen::<$uty>() >> N) as $ty * (ε/2)`. 208 /// 209 /// See also: [`Open01`] which samples from `(0, 1)`, [`OpenClosed01`] which 210 /// samples from `(0, 1]` and `Rng::gen_range(0..1)` which also samples from 211 /// `[0, 1)`. Note that `Open01` uses transmute-based methods which yield 1 bit 212 /// less precision but may perform faster on some architectures (on modern Intel 213 /// CPUs all methods have approximately equal performance). 214 /// 215 /// [`Uniform`]: uniform::Uniform 216 #[derive(Clone, Copy, Debug)] 217 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))] 218 pub struct Standard; 219