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.
std::mt19937 gen{42}; std::uniform_int_distribution<int> die{1, 6}; int roll = die(gen); // 1..6, both ends inclusive
Try it
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.
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
// 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 mostnand has a poor sequence.std::uniform_int_distributionremoves 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::shufflewith an engine, not a distribution. - Threads: an engine and a distribution are not thread-safe. Give each thread its own pair.
Related
<random>, random engines,std::shuffle- Lessons: Random numbers