[rand.req.dist]

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

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

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

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

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

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

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

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

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

- [(3.1)](#3.1)

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

- [(3.2)](#3.2)

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

- [(3.3)](#3.3)

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

- [(3.4)](#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)](#3.5)

p is a (possibly const) value of P;

- [(3.6)](#3.6)

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

- [(3.7)](#3.7)

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

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

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

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

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

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

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

[10](#10)

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

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

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

[🔗](#itemdecl:1)

`os << x
`

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

[13](#13)

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

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

[14](#14)

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

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

[15](#15)

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

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

[🔗](#itemdecl:2)

`is >> d
`

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

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

[18](#18)

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

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

[19](#19)

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

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

[20](#20)

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

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