Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Memory and Utilities

C++ random distributions

Reference for C++ random distributions: uniform_int, uniform_real, normal, bernoulli, discrete and more, and why their exact output is implementation-specific.

A distribution object turns the raw, uniformly spread integers of a random engine into values with a shape you actually want: a die roll, a coin flip, a height drawn from a bell curve. All of them live in <random>. You build the distribution once with its parameters, then call it with an engine: dist(engine).

The standard fixes the sequence of values for the engines (a default-seeded std::mt19937 always starts the same way on every platform), but it does not fix how a distribution consumes those numbers. The same seed and the same distribution can therefore print different values with libstdc++, libc++ and MSVC. The outputs below were produced by libstdc++ (GCC 15.2) and are only reproducible with that library.

C++
std::mt19937 gen{42};
std::uniform_int_distribution<int> die{1, 6};
int roll = die(gen);   // 1..6, both ends inclusive

Try it

C++ Dice, coins and real numbers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Normal and weighted choices

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
// integers
template<class IntType = int> class uniform_int_distribution;       // [a, b]
template<class IntType = int> class binomial_distribution;          // trials t, probability p
template<class IntType = int> class poisson_distribution;           // mean
template<class IntType = int> class geometric_distribution;
template<class IntType = int> class discrete_distribution;          // weights

// booleans
class bernoulli_distribution;                                       // probability p

// real numbers
template<class RealType = double> class uniform_real_distribution;  // [a, b)
template<class RealType = double> class normal_distribution;        // mean, stddev
template<class RealType = double> class exponential_distribution;   // lambda
Name Description
uniform_int_distribution(a, b) Every integer from a to b, both included, equally likely. Requires a <= b.
uniform_real_distribution(a, b) A real number in [a, b). Requires a < b.
normal_distribution(mean, stddev) Bell curve. stddev must be positive.
bernoulli_distribution(p) true with probability p, from 0 to 1. Default is 0.5.
binomial_distribution(t, p) Number of successes in t independent trials.
poisson_distribution(mean) Count of events in a fixed interval.
discrete_distribution(weights) Index i with probability proportional to weights[i].
piecewise_constant_distribution, piecewise_linear_distribution Densities defined by intervals and weights.

Returns: dist(engine) returns one value of result_type. dist.reset() discards cached state, and dist.param() reads or replaces the parameters.

Errors / undefined behavior: invalid parameters (such as b < a, a negative standard deviation or a probability outside 0 to 1) are undefined behavior. The class templates are only valid for the intended types: uniform_int_distribution<char> is not allowed (use int and convert).

Usage notes

  • Never use rand() % n. It is biased for most n and has a poor sequence. std::uniform_int_distribution removes the bias.
  • Not portable across libraries. An engine's output is standardized; a distribution's mapping is not. Do not write tests that expect specific numbers from a distribution unless you pin the standard library.
  • Create the distribution once outside a loop when you can. Some, such as normal_distribution, keep a cached second value, so a new object each time wastes work.
  • Distributions copy by value and hold state, but not randomness. Several distributions can share one engine; the engine is the part you pass by reference.
  • Integer ranges are inclusive, real ranges are half-open. uniform_real_distribution<double>{0, 1} never returns exactly 1 on a correct implementation.
  • Shuffling uses std::shuffle with an engine, not a distribution.
  • Threads: an engine and a distribution are not thread-safe. Give each thread its own pair.