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 | /// and float 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 |