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

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.

`alloc`

A distribution using weighted sampling of discrete items

## Enums

Error type returned from `Bernoulli::new`

.

`alloc`

Error type returned from `WeightedIndex::new`

.

## Traits

`String`

sampler

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

.