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