# [−] [src] Module rand::distributions

Generating random samples from probability distributions

This module is the home of the [`Distribution`] trait and several of its implementations. It is the workhorse behind some of the convenient functionality of the [`Rng`] trait, e.g. [`Rng::gen`], [`Rng::gen_range`] and of course [`Rng::sample`].

Abstractly, a probability distribution describes the probability of occurance of each value in its sample space.

More concretely, an implementation of `Distribution<T>` for type `X` is an algorithm for choosing values from the sample space (a subset of `T`) according to the distribution `X` represents, using an external source of randomness (an RNG supplied to the `sample` function).

A type `X` may implement `Distribution<T>` for multiple types `T`. Any type implementing [`Distribution`] is stateless (i.e. immutable), but it may have internal parameters set at construction time (for example, `Uniform` allows specification of its sample space as a range within `T`).

# The `Standard` distribution

The `Standard` distribution is important to mention. This is the distribution used by [`Rng::gen()`] and represents the "default" way to produce a random value for many different types, including most primitive types, tuples, arrays, and a few derived types. See the documentation of `Standard` for more details.

Implementing `Distribution<T>` for `Standard` for user types `T` makes it possible to generate type `T` with [`Rng::gen()`], and by extension also with the [`random()`] function.

## Random characters

`Alphanumeric` is a simple distribution to sample random letters and numbers of the `char` type; in contrast `Standard` may sample any valid `char`.

# Uniform numeric ranges

The `Uniform` distribution is more flexible than `Standard`, but also more specialised: it supports fewer target types, but allows the sample space to be specified as an arbitrary range within its target type `T`. Both `Standard` and `Uniform` are in some sense uniform distributions.

Values may be sampled from this distribution using [`Rng::gen_range`] or by creating a distribution object with `Uniform::new`, `Uniform::new_inclusive` or `From<Range>`. When the range limits are not known at compile time it is typically faster to reuse an existing distribution object than to call [`Rng::gen_range`].

User types `T` may also implement `Distribution<T>` for `Uniform`, although this is less straightforward than for `Standard` (see the documentation in the `uniform` module. Doing so enables generation of values of type `T` with [`Rng::gen_range`].

## Open and half-open ranges

There are surprisingly many ways to uniformly generate random floats. A range between 0 and 1 is standard, but the exact bounds (open vs closed) and accuracy differ. In addition to the `Standard` distribution Rand offers `Open01` and `OpenClosed01`. See "Floating point implementation" section of `Standard` documentation for more details.

# Non-uniform sampling

Sampling a simple true/false outcome with a given probability has a name: the `Bernoulli` distribution (this is used by [`Rng::gen_bool`]).

For weighted sampling from a sequence of discrete values, use the `weighted` module.

This crate no longer includes other non-uniform distributions; instead it is recommended that you use either `rand_distr` or `statrs`.

## Re-exports

`pub use self::weighted::WeightedIndex;`
`pub use self::weighted::WeightedError;`

## Modules

uniform | A distribution uniformly sampling numbers within a given range.
weighted | Weighted index sampling

## Structs

Alphanumeric | Sample a `char`, uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9.
Bernoulli | The Bernoulli distribution.
Beta | Deprecated The Beta distribution with shape parameters `alpha` and `beta`.
Binomial | Deprecated The binomial distribution `Binomial(n, p)`.
Cauchy | Deprecated The Cauchy distribution `Cauchy(median, scale)`.
ChiSquared | Deprecated The chi-squared distribution `χ²(k)`, where `k` is the degrees of freedom.
Dirichlet | Deprecated The dirichelet distribution `Dirichlet(alpha)`.
DistIter | An iterator that generates random values of `T` with distribution `D`, using `R` as the source of randomness.
Exp | Deprecated The exponential distribution `Exp(lambda)`.
Exp1 | Deprecated Samples floating-point numbers according to the exponential distribution, with rate parameter `λ = 1`. This is equivalent to `Exp::new(1.0)` or sampling with `-rng.gen::<f64>().ln()`, but faster.
FisherF | Deprecated The Fisher F distribution `F(m, n)`.
Gamma | Deprecated The Gamma distribution `Gamma(shape, scale)` distribution.
LogNormal | Deprecated The log-normal distribution `ln N(mean, std_dev**2)`.
Normal | Deprecated The normal distribution `N(mean, std_dev**2)`.
Open01 | A distribution to sample floating point numbers uniformly in the open interval `(0, 1)`, i.e. not including either endpoint.
OpenClosed01 | A distribution to sample floating point numbers uniformly in the half-open interval `(0, 1]`, i.e. including 1 but not 0.
Pareto | Deprecated Samples floating-point numbers according to the Pareto distribution
Poisson | Deprecated The Poisson distribution `Poisson(lambda)`.
Standard | A generic random value distribution, implemented for many primitive types. Usually generates values with a numerically uniform distribution, and with a range appropriate to the type.
StandardNormal | Deprecated Samples floating-point numbers according to the normal distribution `N(0, 1)` (a.k.a. a standard normal, or Gaussian). This is equivalent to `Normal::new(0.0, 1.0)` but faster.
StudentT | Deprecated The Student t distribution, `t(nu)`, where `nu` is the degrees of freedom.
Triangular | Deprecated The triangular distribution.
Uniform | Sample values uniformly between two bounds.
UnitCircle | Deprecated Samples uniformly from the edge of the unit circle in two dimensions.
UnitSphereSurface | Deprecated Samples uniformly from the surface of the unit sphere in three dimensions.
Weibull | Deprecated Samples floating-point numbers according to the Weibull distribution

## Enums

BernoulliError | Error type returned from `Bernoulli::new`.

## Traits

Distribution | Types (distributions) that can be used to create a random instance of `T`.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)