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

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

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

weighted | Deprecated Weighted index sampling |

## Structs

Alphanumeric | Sample a |

Bernoulli | The Bernoulli distribution. |

DistIter | An iterator that generates random values of |

Open01 | A distribution to sample floating point numbers uniformly in the open
interval |

OpenClosed01 | A distribution to sample floating point numbers uniformly in the half-open
interval |

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

Uniform | Sample values uniformly between two bounds. |

WeightedIndex | A distribution using weighted sampling of discrete items |

## Enums

BernoulliError | Error type returned from |

WeightedError | Error type returned from |

## Traits

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