Debian Codegraph @

.cargo/vendor/rand/src/distr/mod.rs

raw
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::random`] 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 Uniform distribution
32 //!
33 //! The [`StandardUniform`] distribution is important to mention. This is the
34 //! distribution used by [`Rng::random`] 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 //! [`StandardUniform`] for more details.
38 //!
39 //! Implementing [`Distribution<T>`] for [`StandardUniform`] for user types `T` makes it
40 //! possible to generate type `T` with [`Rng::random`], and by extension also
41 //! with the [`random`] function.
42 //!
43 //! ## Other standard uniform distributions
44 //!
45 //! [`Alphanumeric`] is a simple distribution to sample random letters and
46 //! numbers of the `char` type; in contrast [`StandardUniform`] may sample any valid
47 //! `char`.
48 //!
49 //! There's also an [`Alphabetic`] distribution which acts similarly to [`Alphanumeric`] but
50 //! doesn't include digits.
51 //!
52 //! For floats (`f32`, `f64`), [`StandardUniform`] samples from `[0, 1)`. Also
53 //! provided are [`Open01`] (samples from `(0, 1)`) and [`OpenClosed01`]
54 //! (samples from `(0, 1]`). No option is provided to sample from `[0, 1]`; it
55 //! is suggested to use one of the above half-open ranges since the failure to
56 //! sample a value which would have a low chance of being sampled anyway is
57 //! rarely an issue in practice.
58 //!
59 //! # Parameterized Uniform distributions
60 //!
61 //! The [`Uniform`] distribution provides uniform sampling over a specified
62 //! range on a subset of the types supported by the above distributions.
63 //!
64 //! Implementations support single-value-sampling via
65 //! [`Rng::random_range(Range)`](Rng::random_range).
66 //! Where a fixed (non-`const`) range will be sampled many times, it is likely
67 //! faster to pre-construct a [`Distribution`] object using
68 //! [`Uniform::new`], [`Uniform::new_inclusive`] or `From<Range>`.
69 //!
70 //! # Non-uniform sampling
71 //!
72 //! Sampling a simple true/false outcome with a given probability has a name:
73 //! the [`Bernoulli`] distribution (this is used by [`Rng::random_bool`]).
74 //!
75 //! For weighted sampling of discrete values see the [`weighted`] module.
76 //!
77 //! This crate no longer includes other non-uniform distributions; instead
78 //! it is recommended that you use either [`rand_distr`] or [`statrs`].
79 //!
80 //!
81 //! [probability distribution]: https://en.wikipedia.org/wiki/Probability_distribution
82 //! [`rand_distr`]: https://crates.io/crates/rand_distr
83 //! [`statrs`]: https://crates.io/crates/statrs
84
85 //! [`random`]: crate::random
86 //! [`rand_distr`]: https://crates.io/crates/rand_distr
87 //! [`statrs`]: https://crates.io/crates/statrs
88
89 mod bernoulli;
90 mod distribution;
91 mod float;
92 mod integer;
93 mod other;
94 mod utils;
95
96 #[doc(hidden)]
97 pub mod hidden_export {
98 pub use super::float::IntoFloat; // used by rand_distr
99 }
100 pub mod slice;
101 pub mod uniform;
102 #[cfg(feature = "alloc")]
103 pub mod weighted;
104
105 pub use self::bernoulli::{Bernoulli, BernoulliError};
106 #[cfg(feature = "alloc")]
107 pub use self::distribution::SampleString;
108 pub use self::distribution::{Distribution, Iter, Map};
109 pub use self::float::{Open01, OpenClosed01};
110 pub use self::other::{Alphabetic, Alphanumeric};
111 #[doc(inline)]
112 pub use self::uniform::Uniform;
113
114 #[allow(unused)]
115 use crate::Rng;
116
117 /// The Standard Uniform distribution
118 ///
119 /// This [`Distribution`] is the *standard* parameterization of [`Uniform`]. Bounds
120 /// are selected according to the output type.
121 ///
122 /// Assuming the provided `Rng` is well-behaved, these implementations
123 /// generate values with the following ranges and distributions:
124 ///
125 /// * Integers (`i8`, `i32`, `u64`, etc.) are uniformly distributed
126 /// over the whole range of the type (thus each possible value may be sampled
127 /// with equal probability).
128 /// * `char` is uniformly distributed over all Unicode scalar values, i.e. all
129 /// code points in the range `0...0x10_FFFF`, except for the range
130 /// `0xD800...0xDFFF` (the surrogate code points). This includes
131 /// unassigned/reserved code points.
132 /// For some uses, the [`Alphanumeric`] or [`Alphabetic`] distribution will be more
133 /// appropriate.
134 /// * `bool` samples `false` or `true`, each with probability 0.5.
135 /// * Floating point types (`f32` and `f64`) are uniformly distributed in the
136 /// half-open range `[0, 1)`. See also the [notes below](#floating-point-implementation).
137 /// * Wrapping integers ([`Wrapping<T>`]), besides the type identical to their
138 /// normal integer variants.
139 /// * Non-zero integers ([`NonZeroU8`]), which are like their normal integer
140 /// variants but cannot sample zero.
141 ///
142 /// The `StandardUniform` distribution also supports generation of the following
143 /// compound types where all component types are supported:
144 ///
145 /// * Tuples (up to 12 elements): each element is sampled sequentially and
146 /// independently (thus, assuming a well-behaved RNG, there is no correlation
147 /// between elements).
148 /// * Arrays `[T; n]` where `T` is supported. Each element is sampled
149 /// sequentially and independently. Note that for small `T` this usually
150 /// results in the RNG discarding random bits; see also [`Rng::fill`] which
151 /// offers a more efficient approach to filling an array of integer types
152 /// with random data.
153 /// * SIMD types (requires [`simd_support`] feature) like x86's [`__m128i`]
154 /// and `std::simd`'s [`u32x4`], [`f32x4`] and [`mask32x4`] types are
155 /// effectively arrays of integer or floating-point types. Each lane is
156 /// sampled independently, potentially with more efficient random-bit-usage
157 /// (and a different resulting value) than would be achieved with sequential
158 /// sampling (as with the array types above).
159 ///
160 /// ## Custom implementations
161 ///
162 /// The [`StandardUniform`] distribution may be implemented for user types as follows:
163 ///
164 /// ```
165 /// # #![allow(dead_code)]
166 /// use rand::Rng;
167 /// use rand::distr::{Distribution, StandardUniform};
168 ///
169 /// struct MyF32 {
170 /// x: f32,
171 /// }
172 ///
173 /// impl Distribution<MyF32> for StandardUniform {
174 /// fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
175 /// MyF32 { x: rng.random() }
176 /// }
177 /// }
178 /// ```
179 ///
180 /// ## Example usage
181 /// ```
182 /// use rand::prelude::*;
183 /// use rand::distr::StandardUniform;
184 ///
185 /// let val: f32 = rand::rng().sample(StandardUniform);
186 /// println!("f32 from [0, 1): {}", val);
187 /// ```
188 ///
189 /// # Floating point implementation
190 /// The floating point implementations for `StandardUniform` generate a random value in
191 /// the half-open interval `[0, 1)`, i.e. including 0 but not 1.
192 ///
193 /// All values that can be generated are of the form `n * ε/2`. For `f32`
194 /// the 24 most significant random bits of a `u32` are used and for `f64` the
195 /// 53 most significant bits of a `u64` are used. The conversion uses the
196 /// multiplicative method: `(rng.gen::<$uty>() >> N) as $ty * (ε/2)`.
197 ///
198 /// See also: [`Open01`] which samples from `(0, 1)`, [`OpenClosed01`] which
199 /// samples from `(0, 1]` and `Rng::random_range(0..1)` which also samples from
200 /// `[0, 1)`. Note that `Open01` uses transmute-based methods which yield 1 bit
201 /// less precision but may perform faster on some architectures (on modern Intel
202 /// CPUs all methods have approximately equal performance).
203 ///
204 /// [`Uniform`]: uniform::Uniform
205 /// [`Wrapping<T>`]: std::num::Wrapping
206 /// [`NonZeroU8`]: std::num::NonZeroU8
207 /// [`__m128i`]: https://doc.rust-lang.org/core/arch/x86/struct.__m128i.html
208 /// [`u32x4`]: std::simd::u32x4
209 /// [`f32x4`]: std::simd::f32x4
210 /// [`mask32x4`]: std::simd::mask32x4
211 /// [`simd_support`]: https://github.com/rust-random/rand#crate-features
212 #[derive(Clone, Copy, Debug, Default)]
213 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
214 pub struct StandardUniform;