251 lines
11 KiB
Markdown
251 lines
11 KiB
Markdown
[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)
|