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
89mod bernoulli;
90mod distribution;
91mod float;
92mod integer;
93mod other;
94mod utils;
95
96#[doc(hidden)]
97pub mod hidden_export {
98 pub use super::float::IntoFloat; // used by rand_distr
99}
100pub mod slice;
101pub mod uniform;
102#[cfg(feature = "alloc")]
103pub mod weighted;
104
105pub use self::bernoulli::{Bernoulli, BernoulliError};
106#[cfg(feature = "alloc")]
107pub use self::distribution::SampleString;
108pub use self::distribution::{Distribution, Iter, Map};
109pub use self::float::{Open01, OpenClosed01};
110pub use self::other::{Alphabetic, Alphanumeric};
111#[doc(inline)]
112pub use self::uniform::Uniform;
113
114#[allow(unused)]
115use 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))]
214pub struct StandardUniform;
215