29 Numerics library [numerics]

29.6 Random number generation [rand]

29.6.1 Requirements [rand.req]

29.6.1.6 Random number distribution requirements [rand.req.dist]

A random number distribution (commonly shortened to distribution) d of type D is a function object returning values that are distributed according to an associated mathematical probability density function p(z) or according to an associated discrete probability function

P (z_{i})

A distribution's specification identifies its associated probability function p(z) or

P (z_{i})

An associated probability function is typically expressed using certain externally-supplied quantities known as the parameters of the distribution.

Such distribution parameters are identified in this context by writing, for example,

p (z | a, b)

P (z_{i} | a, b)

, to name specific parameters, or by writing, for example, p(z |{p}) or

P (z_{i} | {p})

, to denote a distribution's parameters p taken as a whole.

A class D satisfies the requirements of a random number distribution if the expressions shown in Table 100 are valid and have the indicated semantics, and if D and its associated types also satisfy all other requirements of this section [rand.req.dist].

In that Table and throughout this section,

a)
T is the type named by D's associated result_type;
b)
P is the type named by D's associated param_type;
c)
d is a value of D, and x and y are (possibly const) values of D;
d)
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;
e)
p is a (possibly const) value of P;
f)
g, g1, and g2 are lvalues of a type satisfying the requirements of a uniform random bit generator ([rand.req.urng]);
g)
os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and
h)
is is an lvalue of the type of some class template specialization basic_istream<charT, traits>;

where charT and traits are constrained according to Clauses [strings] and [input.output].

Table 100 — Random number distribution requirements

Expression	Return type	Pre/post-condition	Complexity
D::result_type	T	T is an arithmetic type ([basic.fundamental]).	compile-time
D::param_type	P		compile-time
D()		Creates a distribution whose behavior is indistinguishable from that of any other newly default-constructed distribution of type D.	constant
D(p)		Creates a distribution whose behavior is indistinguishable from that of a distribution newly constructed directly from the values used to construct p.	same as p's construction
d.reset()	void	Subsequent uses of d do not depend on values produced by any engine prior to invoking reset.	constant
x.param()	P	Returns a value p such that D(p).param() == p.	no worse than the complexity of D(p)
d.param(p)	void	Postconditions: d.param() == p.	no worse than the complexity of D(p)
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 (z_{i} \| {p})$ function.	amortized constant number of invocations of g
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 (z_{i} \| {p})$ function.	amortized constant number of invocations of g
x.min()	T	Returns glb.	constant
x.max()	T	Returns lub.	constant
x == y	bool	This operator is an equivalence relation. Returns true if x.param() == y.param() and $S_{1} = S_{2}$ , where $S_{1}$ and $S_{2}$ are the infinite sequences of values that would be generated, respectively, by repeated future calls to x(g1) and y(g2) whenever g1 == g2. Otherwise returns false.	constant
x != y	bool	!(x == y).	same as x == y.
os << x	reference to the type of os	Writes to os a textual representation for the parameters and the additional internal data of x. Postconditions: The os.fmtflags and fill character are unchanged.
is >> d	reference to the type of is	Restores from is the parameters and additional internal data of the lvalue d. If bad input is encountered, ensures that d is unchanged by the operation and calls is.setstate(ios::failbit) (which may throw ios::failure ([iostate.flags])). Requires: is provides a textual representation that was previously written using an os whose imbued locale and whose type's template specialization arguments charT and traits were the same as those of is. Postconditions: The is.fmtflags are unchanged.

D shall satisfy the requirements of CopyConstructible (Table 24) and CopyAssignable (Table 26) types.

The sequence of numbers produced by repeated invocations of d(g) shall be independent of any invocation of os << d or of any const member function of D between any of the invocations d(g).

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).

It is unspecified whether D::param_type is declared as a (nested) class or via a typedef.

In this subclause [rand], declarations of D::param_type are in the form of typedefs for convenience of exposition only.

P shall satisfy the requirements of CopyConstructible (Table 24), CopyAssignable (Table 26), and EqualityComparable (Table 20) types.

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.

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.

P shall have a declaration of the form

using distribution_type =  D;