[rand.req]

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

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

### 29.5.3 Requirements [rand.req]

#### [29.5.3.1](#genl) General requirements [[rand.req.genl]](rand.req.genl)

[1](#genl-1)

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

Throughout [[rand]](rand "29.5 Random number generation"),
the effect of instantiating a template:

- [(1.1)](#genl-1.1)

  that has a template type parameter
 named Sseq is undefined unless the corresponding template argument
 is cv-unqualified and
 meets the requirements
 of [seed sequence](#seedseq "29.5.3.2 Seed sequence requirements [rand.req.seedseq]")[.](#genl-1.1.sentence-1)

- [(1.2)](#genl-1.2)

  that has a template type parameter
 named URBG is undefined unless the corresponding template argument
 is cv-unqualified and
 meets the requirements
 of [uniform random bit generator](#urng "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]")[.](#genl-1.2.sentence-1)

- [(1.3)](#genl-1.3)

  that has a template type parameter
 named Engine is undefined unless the corresponding template argument
 is cv-unqualified and
 meets the requirements
 of [random number engine](#eng "29.5.3.4 Random number engine requirements [rand.req.eng]")[.](#genl-1.3.sentence-1)

- [(1.4)](#genl-1.4)

  that has a template type parameter
 named RealType is undefined unless the corresponding template argument
 is cv-unqualified and
 is one of float, double, or long double[.](#genl-1.4.sentence-1)

- [(1.5)](#genl-1.5)

  that has a template type parameter
 named IntType is undefined unless the corresponding template argument
 is cv-unqualified and
 is one of short, int, long, long long, unsigned short, unsigned int, unsigned long,
 or unsigned long long[.](#genl-1.5.sentence-1)

- [(1.6)](#genl-1.6)

  that has a template type parameter
 named UIntType is undefined unless the corresponding template argument
 is cv-unqualified and
 is one of unsigned short, unsigned int, unsigned long,
 or unsigned long long[.](#genl-1.6.sentence-1)

[2](#genl-2)

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

Throughout [[rand]](rand "29.5 Random number generation"),
phrases of the form âx is an iterator of a specific kindâ
shall be interpreted as equivalent to the more formal requirement that
âx is a value
of a type meeting the requirements
of the specified iterator typeâ[.](#genl-2.sentence-1)

[3](#genl-3)

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

Throughout [[rand]](rand "29.5 Random number generation"),
any constructor that can be called with a single argument
and that meets a requirement specified in this subclause
shall be declared explicit[.](#genl-3.sentence-1)

#### [29.5.3.2](#seedseq) Seed sequence requirements [[rand.req.seedseq]](rand.req.seedseq)

[1](#seedseq-1)

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

A [*seed sequence*](#def:seed_sequence "29.5.3.2 Seed sequence requirements [rand.req.seedseq]") is an object
 that consumes a sequence
 of integer-valued data
 and produces a requested number
 of unsigned integer values i, 0â¤i<232,
 based on the consumed data[.](#seedseq-1.sentence-1)

[*Note [1](#seedseq-note-1)*:

Such an object provides a mechanism
 to avoid replication of streams of random variates[.](#seedseq-1.sentence-2)

This can be useful, for example, in applications
 requiring large numbers of random number engines[.](#seedseq-1.sentence-3)

â *end note*]

[2](#seedseq-2)

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

A class S meets the requirements
of a seed sequence
if the expressions shown
in Table [126](#tab:rand.req.seedseq "Table 126: Seed sequence requirements") are valid and have the indicated semantics,
and if S also meets all other requirements
of [[rand.req.seedseq]](#seedseq "29.5.3.2 Seed sequence requirements")[.](#seedseq-2.sentence-1)

In Table [126](#tab:rand.req.seedseq "Table 126: Seed sequence requirements") and throughout this subclause:

- [(2.1)](#seedseq-2.1)

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

- [(2.2)](#seedseq-2.2)

q is a value of type S and r is a value of type S or const S;

- [(2.3)](#seedseq-2.3)

ib and ie are input iterators
 with an unsigned integer value_type of at least 32 bits;

- [(2.4)](#seedseq-2.4)

rb and re are mutable random access iterators
 with an unsigned integer value_type of at least 32 bits;

- [(2.5)](#seedseq-2.5)

ob is an output iterator;
 and

- [(2.6)](#seedseq-2.6)

il is a value of type initializer_list<T>[.](#seedseq-2.sentence-2)

Table [126](#tab:rand.req.seedseq) — Seed sequence requirements [[tab:rand.req.seedseq]](./tab:rand.req.seedseq)  

| [ð](#tab:rand.req.seedseq-row-1)<br>**Expression** | **Return type** | **Pre/post-condition** | **Complexity** |
| --- | --- | --- | --- |
| [ð](#tab:rand.req.seedseq-row-2)<br>S​::​result_type | T | T is an [unsigned integer type](basic.fundamental#def:type,unsigned_integer "6.9.2 Fundamental types [basic.fundamental]")  of at least 32 bits[.](#tab:rand.req.seedseq-row-2-column-3-sentence-1) |  |
| [ð](#tab:rand.req.seedseq-row-3)<br>S() |  | Creates a seed sequence  with the same initial state as all other default-constructed seed sequences  of type S[.](#tab:rand.req.seedseq-row-3-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.seedseq-row-4)<br>S(ib,ie) |  | Creates a seed sequence  having internal state  that depends on some or all of the bits  of the supplied sequence [ib,ie)[.](#tab:rand.req.seedseq-row-4-column-3-sentence-1) | O(ieâib) |
| [ð](#tab:rand.req.seedseq-row-5)<br>S(il) |  | Same as S(il.begin(), il.end())[.](#tab:rand.req.seedseq-row-5-column-3-sentence-1) | same as S(il.begin(), il.end()) |
| [ð](#tab:rand.req.seedseq-row-6)<br>q.generate(rb,re) | void | Does nothing if rb == re[.](#tab:rand.req.seedseq-row-6-column-3-sentence-1)<br>Otherwise,  fills the supplied sequence [rb,re)  with 32-bit quantities  that depend on the sequence supplied to the constructor  and possibly also depend on the history  of generate's previous invocations[.](#tab:rand.req.seedseq-row-6-column-3-sentence-2) | O(reârb) |
| [ð](#tab:rand.req.seedseq-row-7)<br>r.size() | size_t | The number of 32-bit units  that would be copied  by a call to r.param[.](#tab:rand.req.seedseq-row-7-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.seedseq-row-8)<br>r.param(ob) | void | Copies to the given destination  a sequence of 32-bit units  that can be provided  to the constructor of a second object of type S,  and that would reproduce in that second object  a state indistinguishable  from the state of the first object[.](#tab:rand.req.seedseq-row-8-column-3-sentence-1) | O(r.size()) |

#### [29.5.3.3](#urng) Uniform random bit generator requirements [[rand.req.urng]](rand.req.urng)

[1](#urng-1)

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

A [*uniform random bit generator*](#def:uniform_random_bit_generator)g of type G is a function object
returning unsigned integer values
such that each value
in the range of possible results
has (ideally) equal probability
of being returned[.](#urng-1.sentence-1)

[*Note [1](#urng-note-1)*:

The degree to which g's results
 approximate the ideal
 is often determined statistically[.](#urng-1.sentence-2)

â *end note*]

template<class G>concept [uniform_random_bit_generator](#concept:uniform_random_bit_generator "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]") =[invocable](concept.invocable#concept:invocable "18.7.2 Concept invocable [concept.invocable]")<G&> && [unsigned_integral](concepts.arithmetic#concept:unsigned_integral "18.4.7 Arithmetic concepts [concepts.arithmetic]")<invoke_result_t<G&>> &&requires {{ G::min() } -> [same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<invoke_result_t<G&>>; { G::max() } -> [same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<invoke_result_t<G&>>; requires bool_constant<(G::min() < G::max())>::value; };

[2](#urng-2)

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

Let g be an object of type G[.](#urng-2.sentence-1)

G models[uniform_random_bit_generator](#concept:uniform_random_bit_generator "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]") only if

- [(2.1)](#urng-2.1)

G​::​min() <= g(),

- [(2.2)](#urng-2.2)

g() <= G​::​max(), and

- [(2.3)](#urng-2.3)

g() has amortized constant complexity[.](#urng-2.sentence-2)

[3](#urng-3)

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

A class G meets the [*uniform random bit generator*](#def:uniform_random_bit_generator) requirements ifG models [uniform_random_bit_generator](#concept:uniform_random_bit_generator "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]"),invoke_result_t<G&> is an unsigned integer type ([[basic.fundamental]](basic.fundamental "6.9.2 Fundamental types")),
andG provides a nested [*typedef-name*](dcl.typedef#nt:typedef-name "9.2.4 The typedef specifier [dcl.typedef]") result_type that denotes the same type as invoke_result_t<G&>[.](#urng-3.sentence-1)

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

[1](#eng-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[.](#eng-1.sentence-1)

[2](#eng-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[.](#eng-2.sentence-1)

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

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

[3](#eng-3)

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

E's specification shall define:

- [(3.1)](#eng-3.1)

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

- [(3.2)](#eng-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)](#eng-3.3)

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

[4](#eng-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](#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]](#eng "29.5.3.4 Random number engine requirements")[.](#eng-4.sentence-1)

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

- [(4.1)](#eng-4.1)

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

- [(4.2)](#eng-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)](#eng-4.3)

s is a value of T;

- [(4.4)](#eng-4.4)

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

- [(4.5)](#eng-4.5)

z is a value
 of type unsigned long long;

- [(4.6)](#eng-4.6)

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

- [(4.7)](#eng-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")[.](#eng-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]](#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](#eng-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[.](#eng-5.sentence-1)

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

[6](#eng-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[.](#eng-6.sentence-1)

[ð](#eng-itemdecl:1)

`os << x
`

[7](#eng-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[.](#eng-7.sentence-1)

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

[8](#eng-8)

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

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

[9](#eng-9)

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

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

[10](#eng-10)

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

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

[11](#eng-11)

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

*Complexity*: O(size of state)

[ð](#eng-itemdecl:2)

`is >> v
`

[12](#eng-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[.](#eng-12.sentence-1)

[13](#eng-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[.](#eng-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")))[.](#eng-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[.](#eng-13.sentence-3)

[14](#eng-14)

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

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

[15](#eng-15)

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

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

[16](#eng-16)

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

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

[17](#eng-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)

#### [29.5.3.5](#adapt) Random number engine adaptor requirements [[rand.req.adapt]](rand.req.adapt)

[1](#adapt-1)

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

A [*random number engine adaptor*](#def:random_number_engine_adaptor) (commonly shortened to [*adaptor*](#def:adaptor))a of type A is a random number engine
that takes values
produced by some other random number engine,
and applies an algorithm to those values
in order to deliver a sequence of values
with different randomness properties[.](#adapt-1.sentence-1)

An engine b of type B adapted in this way
is termed a [*base engine*](#def:base_engine) in this context[.](#adapt-1.sentence-2)

The expression a.base() shall be valid and shall return a
const reference to a's base engine[.](#adapt-1.sentence-3)

[2](#adapt-2)

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

The requirements of a random number engine type
shall be interpreted as follows
with respect to a random number engine adaptor type[.](#adapt-2.sentence-1)

[ð](#adapt-itemdecl:1)

`A::A();
`

[3](#adapt-3)

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

*Effects*: The base engine is initialized
 as if by its default constructor[.](#adapt-3.sentence-1)

[ð](#adapt-itemdecl:2)

`bool operator==(const A& a1, const A& a2);
`

[4](#adapt-4)

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

*Returns*: true if a1's base engine is equal to a2's base engine[.](#adapt-4.sentence-1)

Otherwise returns false[.](#adapt-4.sentence-2)

[ð](#adapt-itemdecl:3)

`A::A(result_type s);
`

[5](#adapt-5)

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

*Effects*: The base engine is initialized
 with s[.](#adapt-5.sentence-1)

[ð](#adapt-itemdecl:4)

`template<class Sseq> A::A(Sseq& q);
`

[6](#adapt-6)

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

*Effects*: The base engine is initialized
 with q[.](#adapt-6.sentence-1)

[ð](#adapt-itemdecl:5)

`void seed();
`

[7](#adapt-7)

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

*Effects*: With b as the base engine, invokes b.seed()[.](#adapt-7.sentence-1)

[ð](#adapt-itemdecl:6)

`void seed(result_type s);
`

[8](#adapt-8)

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

*Effects*: With b as the base engine, invokes b.seed(s)[.](#adapt-8.sentence-1)

[ð](#adapt-itemdecl:7)

`template<class Sseq> void seed(Sseq& q);
`

[9](#adapt-9)

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

*Effects*: With b as the base engine, invokes b.seed(q)[.](#adapt-9.sentence-1)

[10](#adapt-10)

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

A shall also meet
the following additional requirements:

- [(10.1)](#adapt-10.1)

  The complexity
 of each function
 shall not exceed the complexity
 of the corresponding function
 applied to the base engine[.](#adapt-10.1.sentence-1)

- [(10.2)](#adapt-10.2)

  The state
 of A shall include the state
 of its base engine[.](#adapt-10.2.sentence-1)
  The size of A's state
 shall be no less than the size of the base engine[.](#adapt-10.2.sentence-2)

- [(10.3)](#adapt-10.3)

  Copying A's state
 (e.g., during copy construction or copy assignment)
 shall include copying
 the state of the base engine of A[.](#adapt-10.3.sentence-1)

- [(10.4)](#adapt-10.4)

  The textual representation
 of A shall include
 the textual representation of its base engine[.](#adapt-10.4.sentence-1)

#### [29.5.3.6](#dist) Random number distribution requirements [[rand.req.dist]](rand.req.dist)

[1](#dist-1)

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

A [*random number distribution*](#def:random_number_distribution) (commonly shortened to [*distribution*](#def:distribution))d of type D is a function object
returning values
that are distributed according to
an associated mathematical [*probability density function*](#def:probability_density_function)p(z) or according to
an associated [*discrete probability function*](#def:discrete_probability_function)P(zi)[.](#dist-1.sentence-1)

A distribution's specification
identifies its associated probability functionp(z) or P(zi)[.](#dist-1.sentence-2)

[2](#dist-2)

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

An associated probability function is typically expressed
using certain externally-supplied quantities
known as the [*parameters of the distribution*](#def:parameters_of_the_distribution)[.](#dist-2.sentence-1)

Such distribution parameters are identified
in this context by writing, for example, p(z | a,b) or P(zi|a,b),
 to name specific parameters,
or by writing, for example, p(z |{p}) or P(zi|{p}),
 to denote a distribution's parameters p taken as a whole[.](#dist-2.sentence-2)

[3](#dist-3)

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

A class D meets the requirements
of a [*random number distribution*](#def:random_number_distribution) if the expressions shown
in Table [128](#tab:rand.req.dist "Table 128: Random number distribution requirements") are valid and have the indicated semantics,
and if D and its associated types
also meet all other requirements
of [[rand.req.dist]](#dist "29.5.3.6 Random number distribution requirements")[.](#dist-3.sentence-1)

In Table [128](#tab:rand.req.dist "Table 128: Random number distribution requirements") and throughout this subclause,

- [(3.1)](#dist-3.1)

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

- [(3.2)](#dist-3.2)

P is the type named by D's associated param_type;

- [(3.3)](#dist-3.3)

d is a
 value of D,
 and x and y are (possibly const) values of D;

- [(3.4)](#dist-3.4)

glb and lub are values of T respectively corresponding to
 the greatest lower bound and the least upper bound
 on the values potentially returned by d's operator(),
 as determined by the current values of d's parameters;

- [(3.5)](#dist-3.5)

p is a (possibly const) value of P;

- [(3.6)](#dist-3.6)

g, g1, and g2 are lvalues of a type
 meeting the requirements
 of a [uniform random bit generator](#urng "29.5.3.3 Uniform random bit generator requirements [rand.req.urng]");

- [(3.7)](#dist-3.7)

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

- [(3.8)](#dist-3.8)

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")[.](#dist-3.sentence-2)

Table [128](#tab:rand.req.dist) — Random number distribution requirements [[tab:rand.req.dist]](./tab:rand.req.dist)  

| [ð](#tab:rand.req.dist-row-1)<br>**Expression** | **Return type** | **Pre/post-condition** | **Complexity** |
| --- | --- | --- | --- |
| [ð](#tab:rand.req.dist-row-2)<br>D​::​result_type | T | T is an [arithmetic type](basic.fundamental#def:type,arithmetic "6.9.2 Fundamental types [basic.fundamental]")[.](#tab:rand.req.dist-row-2-column-3-sentence-1) |  |
| [ð](#tab:rand.req.dist-row-3)<br>D​::​param_type | P |  |  |
| [ð](#tab:rand.req.dist-row-4)<br>D() |  | Creates a distribution whose behavior is indistinguishable  from that of any other newly default-constructed distribution  of type D[.](#tab:rand.req.dist-row-4-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.dist-row-5)<br>D(p) |  | Creates a distribution whose behavior is indistinguishable  from that of a distribution  newly constructed directly from the values used to construct p[.](#tab:rand.req.dist-row-5-column-3-sentence-1) | same as p's construction |
| [ð](#tab:rand.req.dist-row-6)<br>d.reset() | void | Subsequent uses of d do not depend  on values produced by any engine  prior to invoking reset[.](#tab:rand.req.dist-row-6-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.dist-row-7)<br>x.param() | P | Returns a value  p such that D(p).param() == p[.](#tab:rand.req.dist-row-7-column-3-sentence-1) | no worse than the complexity of D(p) |
| [ð](#tab:rand.req.dist-row-8)<br>d.param(p) | void | *Postconditions*: d.param() == p[.](#tab:rand.req.dist-row-8-column-3-sentence-1) | no worse than the complexity of D(p) |
| [ð](#tab:rand.req.dist-row-9)<br>d(g) | T | With p=d.param(),  the sequence of numbers  returned by successive invocations  with the same object g  is randomly distributed  according to the associated  p(z |{p})  or  P(zi|{p})  function[.](#tab:rand.req.dist-row-9-column-3-sentence-1) | amortized constant number of invocations of g |
| [ð](#tab:rand.req.dist-row-10)<br>d(g,p) | T | The sequence of numbers  returned by successive invocations  with the same objects g and p  is randomly distributed  according to the associated  p(z |{p})  or  P(zi|{p})  function[.](#tab:rand.req.dist-row-10-column-3-sentence-1) | amortized constant number of invocations of g |
| [ð](#tab:rand.req.dist-row-11)<br>x.min() | T | Returns glb[.](#tab:rand.req.dist-row-11-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.dist-row-12)<br>x.max() | T | Returns lub[.](#tab:rand.req.dist-row-12-column-3-sentence-1) | constant |
| [ð](#tab:rand.req.dist-row-13)<br>x == y | bool | This operator is an equivalence relation[.](#tab:rand.req.dist-row-13-column-3-sentence-1)<br>Returns true  if x.param() == y.param() and S1=S2,  where S1 and S2 are  the infinite sequences of values  that would be generated, respectively,  by repeated future calls  to x(g1) and y(g2)  whenever g1 == g2[.](#tab:rand.req.dist-row-13-column-3-sentence-2)<br>Otherwise returns false[.](#tab:rand.req.dist-row-13-column-3-sentence-3) | constant |
| [ð](#tab:rand.req.dist-row-14)<br>x != y | bool | !(x == y)[.](#tab:rand.req.dist-row-14-column-3-sentence-1) | same as x == y[.](#tab:rand.req.dist-row-14-column-4-sentence-1) |

[4](#dist-4)

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

D 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[.](#dist-4.sentence-1)

[5](#dist-5)

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

The sequence of numbers
produced by repeated invocations of d(g) shall be independent of any invocation ofos << d or of
any const member function of D between any of the invocations of d(g)[.](#dist-5.sentence-1)

[6](#dist-6)

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

If a textual representation is written using os << x and that representation is restored
into the same or a different object y of the same type using is >> y,
repeated invocations of y(g) shall produce the same sequence of numbers
as would repeated invocations of x(g)[.](#dist-6.sentence-1)

[7](#dist-7)

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

It is unspecified whether D​::​param_type is declared as a (nested) class or via a typedef[.](#dist-7.sentence-1)

In [[rand]](rand "29.5 Random number generation"),
declarations of D​::​param_type are in the form of typedefs
for convenience of exposition only[.](#dist-7.sentence-2)

[8](#dist-8)

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

P 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)")),[*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)")),
and[*Cpp17EqualityComparable*](utility.arg.requirements#:Cpp17EqualityComparable "16.4.4.2 Template argument requirements [utility.arg.requirements]") (Table [28](utility.arg.requirements#tab:cpp17.equalitycomparable "Table 28: Cpp17EqualityComparable requirements")) requirements[.](#dist-8.sentence-1)

[9](#dist-9)

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

For each of the constructors of D taking arguments corresponding to parameters of the distribution,P shall have a corresponding constructor
subject to the same requirements
and taking arguments identical in number, type, and default values[.](#dist-9.sentence-1)

Moreover,
for each of the member functions of D that return values corresponding to parameters of the distribution,P shall have a corresponding member function
with the identical name, type, and semantics[.](#dist-9.sentence-2)

[10](#dist-10)

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

P shall have a declaration of the formusing distribution_type = D;

[11](#dist-11)

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

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

[ð](#dist-itemdecl:1)

`os << x
`

[12](#dist-12)

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

*Effects*: Writes to os a textual representation
for the parameters and the additional internal data of x[.](#dist-12.sentence-1)

[13](#dist-13)

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

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

[14](#dist-14)

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

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

[15](#dist-15)

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

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

[ð](#dist-itemdecl:2)

`is >> d
`

[16](#dist-16)

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

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

[17](#dist-17)

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

*Effects*: Restores from is the parameters and additional internal data of the lvalue d[.](#dist-17.sentence-1)

If bad input is encountered,
ensures that d 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")))[.](#dist-17.sentence-2)

[18](#dist-18)

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

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

[19](#dist-19)

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

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

[20](#dist-20)

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

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