Share via


<random>

Defines many random number generators.

#include <random>

Remarks

A random number generator is an object that produces a sequence of pseudo-random values. A generator that produces values uniformly distributed in 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 Class, to produce values that are distributed in a manner that is 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 the properties of the type that are permitted as an actual argument type, as follows:

  • IntType indicates a signed or unsigned integral type.

  • UIntType indicates an unsigned integral type.

  • RealType indicates a floating-point type.

An engine is a 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 is the type that is returned by the generator's operator().

  • result_type min() returns the minimum value that is returned by the generator's operator().

  • result_type max() returns the maximum value that is 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 initializes the engine with default seed values.

  • template <class InIt> void seed(InIt& first, InIt last) The seed function seeds the engine by using values of type unsigned long from the half-open sequence that is 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.

    Note

    Only engines retained for TR1 compatibility include this member.

  • result_type operator()() returns values that are uniformly distributed between min() and max().

min, max, and result_type are not described in detail for the engines that follow.

Beginning with Visual Studio 2010, every engine except those retained for TR1 compatibility also includes the following members:

  • An explicit constructor with argument result_type x0 that creates an engine seeded as if by calling seed(x0).

  • An explicit constructor with argument seed_seq& seq that creates an engine seeded as if by calling seed(seq).

  • void seed(result_type x0) The seed function seeds the engine with seed value x0.

  • void seed(seed_seq& seq) The seed function seeds the engine with seed values from seq.

  • void discard(unsigned long long count) effectively calls operator() count times and discards each value.

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 by using operator== and operator!=. If the two states compare as 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 by using the operator<< of the object. The state is not changed by saving it. A saved state can be read into an object of the same type by using operator>>.

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 that can be instantiated by using 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 by using those values. This library provides class templates for two compound engines.

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 that have a particular distribution. Every distribution has the following members:

  • typedef numeric-type input_type is the type that should be returned by the engine passed to operator().

  • typedef numeric-type result_type is the type that is returned by the distribution's operator().

  • void reset() discards any cached values, so that the result of the next call to operator() does not depend on any values obtained from the engine before the call.

  • template <class Engine> result_type operator()(Engine& eng) returns values that are distributed according to the distribution's definition, by using eng as a source of uniformly distributed random values and the stored parameter package.

input_type, result_type, and reset are not described in detail for the distributions that follow.

Beginning with Visual Studio 2010, every distribution also has:

  • typedef unspecified-type param_type is the package of parameters passed to operator() to generate its return value.

  • A const param& constructor initializes the stored parameter package from its argument.

  • param_type param() const gets the stored parameter package.

  • void param(const param_type&) sets the stored parameter package from its argument.

  • template <class Engine> result_type operator()(Engine& eng, param_type par0) returns values distributed in accordance with the distribution's definition, using eng as a source of uniformly distributed random values and the parameter package par0.

A parameter package is an object that stores all the parameters needed for a distribution. It contains:

  • typedef distribution-type distribution_type is the type of its distribution.

  • One or more constructors that take the same parameter lists as the distribution constructors take.

  • The same parameter-access functions as the distribution.

  • Equality and inequality comparison operators.

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 Precondition in the functional descriptions. 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.

Classes

bernoulli_distribution Class

Generates a Bernoulli distribution.

binomial_distribution Class

Generates a binomial distribution.

cauchy_distribution Class

Generates a Cauchy distribution.

chi_squared_distribution Class

Generates a chi-squared distribution.

discard_block Class

Generates a random sequence by discarding values returned by its base engine. Retained for TR1 compatibility.

discard_block_engine Class

Generates a random sequence by discarding values returned by its base engine.

discrete_distribution Class

Generates a discrete integer distribution.

exponential_distribution Class

Generates an exponential distribution.

extreme_value_distribution Class

Generates an extreme value distribution.

fisher_f_distribution Class

Generates a Fisher F distribution.

gamma_distribution Class

Generates a gamma distribution.

geometric_distribution Class

Generates a geometric distribution.

independent_bits_engine Class

Generates a random sequence with a specified number of bits by repacking bits from the values returned by its base engine.

linear_congruential Class

Generates a random sequence by using the linear congruential algorithm. Retained for TR1 compatibility.

linear_congruential_engine Class

Generates a random sequence by using the linear congruential algorithm.

lognormal_distribution Class

Generates a log-normal distribution.

mersenne_twister Class

Generates a random sequence by using the Mersenne twister algorithm. Retained for TR1 compatibility.

mersenne_twister_engine Class

Generates a random sequence by using the Mersenne twister algorithm.

negative_binomial_distribution Class

Generates a negative binomial distribution.

normal_distribution Class

Generates a normal distribution.

piecewise_constant_distribution Class

Generates a piecewise constant distribution.

piecewise_linear_distribution Class

Generates a piecewise linear distribution.

poisson_distribution Class

Generates a Poisson distribution.

random_device Class

Generates a random sequence by using an external device.

seed_seq Class

Stores a vector of unsigned integer values that can supply a randomized seed for a random-number engine.

shuffle_order_engine Class

Generates a random sequence by reordering the values returned from its base engine.

student_t_distribution Class

Generates a Student T distribution.

subtract_with_carry Class

Generates a random sequence by using the subtract with carry algorithm. Retained for TR1 compatibility.

subtract_with_carry_01 Class

Generates a random sequence by using the floating-point subtract with carry algorithm. Retained for TR1 compatibility.

subtract_with_carry_engine Class

Generates a random sequence by using the subtract with carry algorithm.

uniform_int Class

Generates a uniform integer distribution. Retained for TR1 compatibility.

uniform_int_distribution Class

Generates a uniform integer distribution.

uniform_real Class

Generates a uniform floating-point distribution. Retained for TR1 compatibility.

uniform_real_distribution Class

Generates a uniform floating-point distribution.

variate_generator Class

Wraps an engine and a distribution.

weibull_distribution Class

Generates a Weibull distribution.

xor_combine Class

Generates a combined distribution.

Typedefs

default_random_engine TypeDef

Type definition for the default engine.

knuth_b TypeDef

Type definition for a shuffle order engine.

minstd_rand0 TypeDef

Type definition for a linear congruential engine.

minstd_rand TypeDef

Type definition for a linear congruential engine.

mt19937 TypeDef

Type definition for a Mersenne twister engine.

mt19937_64 TypeDef

Type definition for a Mersenne twister engine.

ranlux_base_01 TypeDef

Type definition for a floating-point subtract with carry engine.

ranlux3 TypeDef

Type definition for a subtract with carry engine.

ranlux3_01 TypeDef

Type definition for a floating-point subtract with carry engine.

ranlux4 TypeDef

Type definition for a subtract with carry engine.

ranlux4_01 TypeDef

Type definition for a floating-point subtract with carry engine.

ranlux24 TypeDef

Type definition for a discard block engine.

ranlux24_base TypeDef

Type definition for a subtract with carry engine.

ranlux48 TypeDef

Type definition for a discard block engine.

ranlux48_base TypeDef

Type definition for a subtract with carry engine.

ranlux64_base_01 TypeDef

Type definition for a floating-point subtract with carry engine.

Operators

operator== <random>

Tests if the engine on the left side of the operator is equal to engine on the right side.

operator!= <random>

Tests if the engine on the left side of the operator is not equal to engine on the right side.

operator<< <random>

Writes state information to the stream.

operator>> <random>

Extracts state information from a stream.

Functions

generate_canonical

Returns a floating-point value from a random sequence.