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