# Module rand::distributions

source · ## 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.

## 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.

## Enums

- Error type returned from
`Bernoulli::new`

.

## Traits

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

.