29 Numerics library [numerics]

29.5 Random number generation [rand]

29.5.3 Requirements [rand.req]

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

1
#
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 .
A distribution's specification identifies its associated probability function p(z) or .
2
#
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) or , to name specific parameters, or by writing, for example, p(z |{p}) or , to denote a distribution's parameters p taken as a whole.
3
#
A class D meets the requirements of a random number distribution if the expressions shown in Table 126 are valid and have the indicated semantics, and if D and its associated types also meet all other requirements of [rand.req.dist].
In Table 126 and throughout this subclause,
  • (3.1)
    T is the type named by D's associated result_type;
  • (3.2)
    P is the type named by D's associated param_type;
  • (3.3)
    d is a value of D, and x and y are (possibly const) values of D;
  • (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)
    p is a (possibly const) value of P;
  • (3.6)
    g, g1, and g2 are lvalues of a type meeting the requirements of a uniform random bit generator;
  • (3.7)
    os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and
  • (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] and [input.output].
Table 126 — Random number distribution requirements [tab:rand.req.dist]
🔗
Expression
Return type
Pre/post-condition
Complexity
🔗
D​::​result_type
T
🔗
D​::​param_type
P
🔗
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 , the sequence of numbers returned by successive invocations with the same object g is randomly distributed according to the associated p(z |{p}) or 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 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 , where and 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.
4
#
D shall meet the Cpp17CopyConstructible (Table 32) and Cpp17CopyAssignable (Table 34) requirements.
5
#
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 of d(g).
6
#
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).
7
#
It is unspecified whether D​::​param_type is declared as a (nested) class or via a typedef.
In [rand], declarations of D​::​param_type are in the form of typedefs for convenience of exposition only.
8
#
P shall meet the Cpp17CopyConstructible (Table 32), Cpp17CopyAssignable (Table 34), and Cpp17EqualityComparable (Table 28) requirements.
9
#
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.
10
#
P shall have a declaration of the form using distribution_type = D;
11
#
On hosted implementations, the following expressions are well-formed and have the specified semantics.
🔗
os << x
12
#
Effects: Writes to os a textual representation for the parameters and the additional internal data of x.
13
#
Postconditions: The os.fmtflags and fill character are unchanged.
14
#
Result: reference to the type of os.
15
#
Returns: os.
🔗
is >> d
16
#
Preconditions: 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.
17
#
Effects: 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_base​::​failbit) (which may throw ios_base​::​failure ([iostate.flags])).
18
#
Postconditions: The is.fmtflags are unchanged.
19
#
Result: reference to the type of is.
20
#
Returns: is.