Module urandom::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 Random struct, e.g. Random::next, Random::range and of course Random::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 Random::next 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 Random::next.

The `Uniform` distribution

The Uniform distribution is similar to the Standard distribution but it 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 Random::range or by creating a distribution object from a Range or RangeInclusive. When the range limits are not known at compile time it is typically faster to reuse an existing distribution object than to call Random::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 Random::range.

Structs

Alphanumeric

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

Bernoulli

Sample from the Bernoulli distribution.

Dice

Standard uniform dice.

Float01

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

Samples

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

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.

UniformFloat

Uniform distribution over the floating point types.

UniformInt

Uniform distribution over integral types.