[rand.req.eng]

# 29 Numerics library [[numerics]](./#numerics)

## 29.5 Random number generation [[rand]](rand#req.eng)

### 29.5.3 Requirements [[rand.req]](rand.req#eng)

#### 29.5.3.4 Random number engine requirements [rand.req.eng]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L1824)

A [*random number engine*](#def:random_number_engine) (commonly shortened to [*engine*](#def:engine))e of type E is a uniform random bit generator
that additionally meets the requirements
(e.g., for seeding and for input/output)
specified in this subclause[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L1833)

At any given time,e has a state ei for some integer i ≥ 0[.](#2.sentence-1)

Upon construction,e has an initial state e0[.](#2.sentence-2)

An engine's state may be established via
 a constructor,
 a seed function,
 assignment,
 or a suitable operator>>[.](#2.sentence-3)

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L1846)

E's specification shall define:

- [(3.1)](#3.1)

the size of E's state
 in multiples of the size of result_type,
 given as an integral constant expression;

- [(3.2)](#3.2)

the [*transition algorithm*](#def:transition_algorithm)TA by which e's state ei is advanced to its [*successor state*](#def:successor_state)ei+1;
 and

- [(3.3)](#3.3)

the [*generation algorithm*](#def:generation_algorithm)GA by which an engine's state is mapped
 to a value of type result_type[.](#3.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L1867)

A class E that meets the requirements
of a [uniform random bit generator](rand.req.urng "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]") also meets the requirements
of a [*random number engine*](#def:random_number_engine) if the expressions shown
in Table [127](#tab:rand.req.eng "Table 127: Random number engine requirements") are valid and have the indicated semantics,
and if E also meets all other requirements
of [rand.req.eng][.](#4.sentence-1)

In Table [127](#tab:rand.req.eng "Table 127: Random number engine requirements") and throughout this subclause:

- [(4.1)](#4.1)

T is the type named by E's associated result_type;

- [(4.2)](#4.2)

e is a value of E, v is an lvalue of E, x and y are (possibly const) values of E;

- [(4.3)](#4.3)

s is a value of T;

- [(4.4)](#4.4)

q is an lvalue
 meeting the requirements of a [seed sequence](rand.req.seedseq "29.5.3.2 Seed sequence requirements [rand.req.seedseq]");

- [(4.5)](#4.5)

z is a value
 of type unsigned long long;

- [(4.6)](#4.6)

os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>;
 and

- [(4.7)](#4.7)

is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained
according to [[strings]](strings "27 Strings library") and [[input.output]](input.output "31 Input/output library")[.](#4.sentence-2)

Table [127](#tab:rand.req.eng) — Random number engine requirements [[tab:rand.req.eng]](./tab:rand.req.eng)  

| [🔗](#tab:rand.req.eng-row-1)<br>**Expression** | **Return type** | **Pre/post-condition** | **Complexity** |
| --- | --- | --- | --- |
| [🔗](#tab:rand.req.eng-row-2)<br>E() |  | Creates an engine  with the same initial state  as all other default-constructed engines  of type E[.](#tab:rand.req.eng-row-2-column-3-sentence-1) | O(size of state) |
| [🔗](#tab:rand.req.eng-row-3)<br>E(x) |  | Creates an engine  that compares equal to x[.](#tab:rand.req.eng-row-3-column-3-sentence-1) | O(size of state) |
| [🔗](#tab:rand.req.eng-row-4)<br>E(s) |  | Creates an engine  with initial state determined by s[.](#tab:rand.req.eng-row-4-column-3-sentence-1) | O(size of state) |
| [🔗](#tab:rand.req.eng-row-5)<br>E(q)[240](#footnote-240 "This constructor (as well as the subsequent corresponding seed() function) can be particularly useful to applications requiring a large number of independent random sequences.") |  | Creates an engine  with an initial state  that depends on a sequence  produced by one call  to q.generate[.](#tab:rand.req.eng-row-5-column-3-sentence-1) | same as complexity of q.generate  called on a sequence  whose length is size of state |
| [🔗](#tab:rand.req.eng-row-6)<br>e.seed() | void | *Postconditions*: e == E()[.](#tab:rand.req.eng-row-6-column-3-sentence-1) | same as E() |
| [🔗](#tab:rand.req.eng-row-7)<br>e.seed(s) | void | *Postconditions*: e == E(s)[.](#tab:rand.req.eng-row-7-column-3-sentence-1) | same as E(s) |
| [🔗](#tab:rand.req.eng-row-8)<br>e.seed(q) | void | *Postconditions*: e == E(q)[.](#tab:rand.req.eng-row-8-column-3-sentence-1) | same as E(q) |
| [🔗](#tab:rand.req.eng-row-9)<br>e() | T | Advances e's state ei to  ei+1 =TA(ei)  and returns  GA(ei)[.](#tab:rand.req.eng-row-9-column-3-sentence-1) | per [[rand.req.urng]](rand.req.urng "29.5.3.3 Uniform random bit generator requirements") |
| [🔗](#tab:rand.req.eng-row-10)<br>e.discard(z)[241](#footnote-241 "This operation is common in user code, and can often be implemented in an engine-specific manner so as to provide significant performance improvements over an equivalent naive loop that makes z consecutive calls e().") | void | Advances e's state ei  to ei+z  by any means equivalent to z consecutive calls e()[.](#tab:rand.req.eng-row-10-column-3-sentence-1) | no worse than the complexity  of z consecutive calls e() |
| [🔗](#tab:rand.req.eng-row-11)<br>x == y | bool | This operator is an equivalence relation[.](#tab:rand.req.eng-row-11-column-3-sentence-1)<br>With Sx and Sy  as the infinite sequences of values  that would be generated  by repeated future calls  to x() and y(),  respectively,  returns true  if Sx=Sy;  else returns false[.](#tab:rand.req.eng-row-11-column-3-sentence-2) | O(size of state) |
| [🔗](#tab:rand.req.eng-row-12)<br>x != y | bool | !(x == y)[.](#tab:rand.req.eng-row-12-column-3-sentence-1) | O(size of state) |

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2026)

E shall meet the[*Cpp17CopyConstructible*](utility.arg.requirements#:Cpp17CopyConstructible "16.4.4.2 Template argument requirements [utility.arg.requirements]") (Table [32](utility.arg.requirements#tab:cpp17.copyconstructible "Table 32: Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible)"))
and [*Cpp17CopyAssignable*](utility.arg.requirements#:Cpp17CopyAssignable "16.4.4.2 Template argument requirements [utility.arg.requirements]") (Table [34](utility.arg.requirements#tab:cpp17.copyassignable "Table 34: Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable)")) requirements[.](#5.sentence-1)

These operations shall each be of complexity
no worse than O(size of state)[.](#5.sentence-2)

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2033)

On hosted implementations,
the following expressions are well-formed and have the specified semantics[.](#6.sentence-1)

[🔗](#itemdecl:1)

`os << x
`

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2042)

*Effects*: With os.*fmtflags* set toios_base​::​dec|ios_base​::​left and the fill character set to the space character,
writes to os the textual representation
of x's current state[.](#7.sentence-1)

In the output,
adjacent numbers are separated
by one or more space characters[.](#7.sentence-2)

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2054)

*Postconditions*: The os.*fmtflags* and fill character are unchanged[.](#8.sentence-1)

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2058)

*Result*: reference to the type of os[.](#9.sentence-1)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2062)

*Returns*: os[.](#10.sentence-1)

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2066)

*Complexity*: O(size of state)

[🔗](#itemdecl:2)

`is >> v
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2076)

*Preconditions*: is provides a textual representation
that was previously written
using an output stream
whose imbued locale
was the same as that of is,
and whose type's template specialization argumentscharT and traits were respectively the same as those of is[.](#12.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2087)

*Effects*: With is.*fmtflags* set to ios_base​::​dec,
sets v's state
as determined by reading its textual representation from is[.](#13.sentence-1)

If bad input is encountered,
ensures that v's state is unchanged by the operation
and
calls is.setstate(ios_base​::​failbit) (which may throw ios_base​::​failure ([[iostate.flags]](iostate.flags "31.5.4.4 Flags functions")))[.](#13.sentence-2)

If a textual representation written via os << x was subsequently read via is >> v,
then x == v provided that there have been no intervening invocations
of x or of v[.](#13.sentence-3)

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2104)

*Postconditions*: The is.*fmtflags* are unchanged[.](#14.sentence-1)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2108)

*Result*: reference to the type of is[.](#15.sentence-1)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2112)

*Returns*: is[.](#16.sentence-1)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/numerics.tex#L2116)

*Complexity*: O(size of state)

[240)](#footnote-240)[240)](#footnoteref-240)

This constructor
 (as well as the subsequent corresponding seed() function)
 can be particularly useful
 to applications requiring
 a large number of independent random sequences[.](#footnote-240.sentence-1)

[241)](#footnote-241)[241)](#footnoteref-241)

This operation is common
 in user code,
 and can often be implemented
 in an engine-specific manner
 so as to provide significant performance improvements
 over an equivalent naive loop
 that makes z consecutive calls e()[.](#footnote-241.sentence-1)