Random Number Generators

A random number generator is an object that produces a sequence of pseudo-random values. A generator that produces values uniformly distributed within a specified range is an engine. An engine can be combined with a distribution, either by passing the engine as an argument to the distribution's operator() or by using a variate_generator, to produce values that are distributed in a manner defined by the distribution.

Most of the random number generators are templates whose parameters customize the generator. The descriptions of generators that take a type as an argument use common template parameter names to describe some of the properties of the type permitted as an actual argument type:

IntType — indicates a signed or unsigned integral type
UIntType — indicates an unsigned integral type
RealType — indicates a floating-point type

An engine is a TR1 class or template class whose instances act as a source of random numbers uniformly distributed between a minimum and maximum value. An engine can be a simple engine or a compound engine. Every engine has the following members:

typedef numeric-type result_type — the type returned by the generator's operator().
result_type min() — returns the minimum value returned by the generator's operator().
result_type max() — returns the maximum value returned by the generator's operator(). When result_type is an integral type this is the maximum value that can actually be returned; when result_type is a floating-point type this is the smallest value greater than all values that can be returned.
void seed() — the seed function seeds the engine with default seed values.
template <class InIt> void seed(InIt& first, InIt last) — the seed function seeds the engine with values of type unsigned long from the half-open sequence pointed to by [first, last). If the sequence is not long enough to fully initialize the engine the function stores the value last in first and throws an object of type std::invalid_argument.
result_type operator()() — returns values uniformly distributed between min() and max().

In addition, every engine has a state that determines the sequence of values that will be generated by subsequent calls to operator(). The states of two objects of the same type can be compared with operator== and operator!=; if the two states compare equal the objects will generate the same sequence of values. The state of an object can be saved to a stream as a sequence of 32-bit unsigned values with the object's operator<<; the state is not changed by saving it. A saved state can be read into an object of the same type with operator>>.

A distribution is a TR1 class or template class whose instances transform a stream of uniformly distributed random numbers obtained from an engine into a stream of random numbers with a particular distribution. Every distribution has the following members:

typedef numeric-type input_type — the type that the engine passed to operator() should return.
typedef numeric-type result_type — the type returned by the distribution's operator().
void reset() — discards any cached values, so that the result of the next call to operator() will not depend on any values obtained from the engine prior to the call.
template <class Engine> result_type operator()(Engine& eng) — returns values distributed in accordance with the distribution's definition, using eng as a source of uniformly distributed random values.

A simple engine is an engine that produces random numbers directly. This library provides one class whose objects are simple engines. It also provides four class templates which can be instantiated with values that provide parameters for the algorithm they implement, and nine predefined instances of those class templates. Objects of these types are also simple engines.

A compound engine is an engine that obtains random numbers from one or more simple engines and generates a stream of uniformly distributed random numbers from those values. The library provides class templates for two compound engines.

The library can be built as a checked version and as an unchecked version. The checked version uses a macro similar to C's assert macro to test the conditions marked as Preconditions in the functional descriptions. When a failure is detected the macro writes an error message to standard out and calls the function std::tr1::_Rng_abort. For runtime debugging, set a breakpoint on that function.

To use the checked version, define either the macro _RNG_CHECK or the macro _DEBUG to a non-zero numeric value in all code that uses the library.

Copyright note

Certain materials included or referred to in this document are copyright P.J. Plauger and/or Dinkumware, Ltd. or are based on materials that are copyright P.J. Plauger and/or Dinkumware, Ltd.

Notwithstanding the meta-data for this document, copyright information for this document is as follows: