# C++ named requirements: RandomNumberEngine (since C++11)

> C++ Atlas: `cppatlas.com/w/cpp/named_req/RandomNumberEngine` | Source: https://en.cppreference.com/w/cpp/named_req/RandomNumberEngine | Domain: Named Requirements | Standards: C++11, C++26

A random number engine is a function object returning unsigned integer values such that each value in the range of possible results has (ideally) equal probability.

## Official Specification Summary (cppreference)

A random number engine is a function object returning unsigned integer values such that each value in the range of possible results has (ideally) equal probability.

Any random number engine is also a *UniformRandomBitGenerator*, and therefore may be plugged into any random number distribution in order to obtain a random number (formally, a random variate).

### Requirements

A type satisfies *RandomNumberEngine* if it satisfies *UniformRandomBitGenerator* and, given the following types and values, the semantic and complexity requirements in the table below are satisfied:

**Type — Definition**

- `E`: a *RandomNumberEngine* type
- `T`: `E::result_type`

**Value — Definition**

- `e`: a value of type `E`
- `v`: an lvalue of type `E`
- `x`, `y`: values of type (possibly const-qualified) `E`
- `s`: a value of type `T`
- `q`: a *SeedSequence* lvalue
- `z`: a value of type `unsigned long long`
- `os`: an lvalue whose type is a specialization of `std::basic_ostream`
- `is`: an lvalue whose type is a specialization of `std::basic_istream`
- `n`: the size of `E`'s state
- `TA`: the transition algorithm of `E`
- `GA`: the generation algorithm of `E`

| Expression | Return type | Semantics | Complexity |
| --- | --- | --- | --- |
| `E()` | N/A | Creates an engine with the same initial state as all other default-constructed engines of type `E`. | O(n) |
| `E(x)` | N/A | Creates an engine that compares equal to `x`. | O(n) |
| `E(s)` | N/A | Creates an engine whose initial state is determined by `s`. | O(n) |
| `E(q)` | N/A | Creates an engine whose initial state is determined by a single call to `q.generate`. | same as the complexity of `q.generate` called on a sequence whose length is `n` |
| `e.seed()` | `void` | Postcondition: `e == E()`. | same as `E()` |
| `e.seed(s)` | `void` | Postcondition: `e == E(s)`. | same as `E(s)` |
| `e.seed(q)` | `void` | Postcondition: `e == E(q)`. | same as `E(q)` |
| `e()` | `T` | Advances `e`’s state from `ei` to `ei+1` (i.e. `TA(ei)`) and returns `GA(ei)`. | amortized constant |
| `e.discard(z)` | `void` | Advances `e`’s state from `ei` to `ei+z` by any means equivalent to `z` consecutive calls of `e()`. | no worse than the complexity of `z` consecutive calls of `e()` |
| `x == y` | `bool` | For all positive integer `i`, if the `i`th consecutive calls of `x()` and `y()` return the same value, returns `true`. Otherwise returns `false`. | O(n) |
| `x != y` | `bool` | `!(x == y)` | O(n) |
| `os << x` | `decltype(os)&` | With fmtflags set to `std::ios_base::dec \| std::ios_base::left` and the fill character set to the space character, writes to `os` the textual representation of `x`'s current state. Postcondition: `os`'s fmtflags and the fill character are the same as before. | O(n) |
| `is >> v` | `decltype(is)&` | With fmtflags set to `std::ios_base::dec`, reads from `is` the textual representation of `v`'s current state. If bad input is encountered, ensures that `v`’s state is unchanged by the operation and calls `is.setstate(std::ios_base::failbit)` (which may throw `std::ios_base::failure`). Precondition: `is` provides a textual representation that was previously written using an output stream `pr` satisfying all following conditions: - `is.getloc() == pr.getloc()` is `true`. - `std::is_same<decltype(is)::char_type, decltype(pr)::char_type>::value` is `true`. - `std::is_same<decltype(is)::traits_type, decltype(pr)::traits_type>::value` is `true`. Postcondition: `is`'s fmtflags are the same as before. | O(n) |

### Standard library

The following standard library facilities satisfy *RandomNumberEngine*:

- `linear_congruential_engine` (C++11): implements linear congruential algorithm (class template)
- `mersenne_twister_engine` (C++11): implements Mersenne twister algorithm (class template)
- `subtract_with_carry_engine` (C++11): implements a subtract-with-carry (lagged Fibonacci) algorithm (class template)
- `philox_engine` (C++26): a counter-based parallelizable generator (class template)
- `discard_block_engine` (C++11): discards some output of a random number engine (class template)
- `independent_bits_engine` (C++11): packs the output of a random number engine into blocks of a specified number of bits (class template)
- `shuffle_order_engine` (C++11): delivers the output of a random number engine in a different order (class template)

The following standard library facilities satisfy *UniformRandomBitGenerator* but not *RandomNumberEngine*:

- `random_device` (C++11): non-deterministic random number generator using hardware entropy source (class)

---
Attribution: content from https://en.cppreference.com/w/cpp/named_req/RandomNumberEngine (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.