The random number library provides classes that generate random and pseudo-random numbers. These classes include:

• Uniform random bit generators (URBGs), which include both random number engines, which are pseudo-random number generators that generate integer sequences with a uniform distribution, and true random number generators (if available).
• Random number distributions (e.g.uniform,normal, orpoisson distributions) which convert the output of URBGs into various statistical distributions.

URBGs and distributions are designed to be used together to produce random values. All of the random number engines may be specifically seeded, serialized, and de-serialized for use with repeatable simulators.

[edit]Uniform random bit generators

Auniform random bit generator is a function object returning unsigned integer values such that each value in the range of possible results has (ideally) equal probability of being returned.

All uniform random bit generators meet theUniformRandomBitGenerator requirements.C++20 also defines auniform_random_bit_generator concept.

[edit]Random number engines

Arandom number engine (commonly shortened toengine ) is a uniform random bit generator which generates pseudo-random numbers using seed data as entropy source.

At any given time, an enginee of typeE has a statee_i for some non-negative integeri. Upon construction,e has an initial statee₀, which is determined by engine parameters and an initial seed (or seed sequence).

The following properties are always defined for any engine typeE:

• Thesize ofE’s state in multiples of the size ofE::result_type (i.e.(sizeof e_i)/ sizeof(E::result_type)).
• Thetransition algorithmTA by whiche’s statee_i is advanced to its successor statee_i+1 (i.e.TA(e_i)== e_i+1).
• Thegeneration algorithmGA by whiche’s state is mapped to a value of typeE::result_type, the result is a pseudo-random number.

A pseudo-random number sequence can be generated by callingTA andGA alternatively.

The standard library provides the implementations of three different classes of pseudo-random number generation algorithms as class templates, so that the algorithms can be customized. The choice of which engine to use involves a number of trade-offs:

• Thelinear congruential engine is moderately fast and has a very small storage requirement for state.
• TheMersenne twister engine is slower and has greater state storage requirements but with the right parameters has the longest non-repeating sequence with the most desirable spectral characteristics (for a given definition of desirable).
• Thesubtract with carry engine is very fast even on processors without advanced arithmetic instruction sets, at the expense of greater state storage and sometimes less desirable spectral characteristics.

None of these random number engines arecryptographically secure. As with any secure operation, a crypto library should be used for the purpose (e.g.OpenSSLRAND_bytes).

All types instantiated from these templates meet theRandomNumberEngine requirements.

[edit]Random number engine adaptors

Random number engine adaptors generate pseudo-random numbers using another random number engine as entropy source. They are generally used to alter the spectral characteristics of the underlying engine.

[edit]Predefined random number generators

Several specific popular algorithms are predefined.

[edit]Non-deterministic random numbers

std::random_device is a non-deterministic uniform random bit generator, although implementations are allowed to implementstd::random_device using a pseudo-random number engine if there is no support for non-deterministic random number generation.

[edit]Random number distributions

A random number distribution post-processes the output of a URBG in such a way that resulting output is distributed according to a defined statistical probability density function.

Random number distributions satisfyRandomNumberDistribution.

[edit]Utilities

[edit]Random number algorithms

[edit]C random library

In addition to the engines and distributions described above, the functions and constants from the C random library are also available though not recommended:

[edit]Example

#include <cmath>#include <iomanip>#include <iostream>#include <map>#include <random>#include <string> int main(){// Seed with a real random value, if availablestd::random_device r; // Choose a random mean between 1 and 6    std::default_random_engine e1(r());std::uniform_int_distribution<int> uniform_dist(1,6);int mean= uniform_dist(e1);std::cout<<"Randomly-chosen mean: "<< mean<<'\n'; // Generate a normal distribution around that meanstd::seed_seq seed2{r(), r(), r(), r(), r(), r(), r(), r()};std::mt19937 e2(seed2);std::normal_distribution<> normal_dist(mean,2); std::map<int,int> hist;for(int n=0; n!=10000;++n)++hist[std::round(normal_dist(e2))]; std::cout<<"Normal distribution around "<< mean<<":\n"<<std::fixed<<std::setprecision(1);for(auto[x, y]: hist)std::cout<<std::setw(2)<< x<<' '<<std::string(y/200,'*')<<'\n';}

Randomly-chosen mean: 4Normal distribution around 4:-4-3-2-1 0 * 1 *** 2 ****** 3 ******** 4 ********* 5 ******** 6 ****** 7 *** 8 * 9101112

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文