# Module rand::distributions

Expand description

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` and of course `Rng::sample`.

Abstractly, a probability distribution describes the probability of occurrence 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::sample(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 `Uniform` object than to call [`Rng::sample(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::sample(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 `WeightedIndex` distribution.

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

## Modules

A distribution uniformly sampling numbers within a given range.

weightedDeprecated

Weighted index sampling

## Structs

Sample a `u8`, uniformly distributed over ASCII letters and numbers: a-z, A-Z and 0-9.

The Bernoulli distribution.

An iterator that generates random values of `T` with distribution `D`, using `R` as the source of randomness.

A distribution of values of type `S` derived from the distribution `D` by mapping its output of type `T` through the closure `F`.

A distribution to sample floating point numbers uniformly in the open interval `(0, 1)`, i.e. not including either endpoint.

A distribution to sample floating point numbers uniformly in the half-open interval `(0, 1]`, i.e. including 1 but not 0.

A distribution to sample items uniformly from a slice.

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.

Sample values uniformly between two bounds.

A distribution using weighted sampling of discrete items

## Enums

Error type returned from `Bernoulli::new`.

Error type returned from `WeightedIndex::new`.

## Traits

`String` sampler

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