[rand.req.dist] (original) (raw)
26 Numerics library [numerics]
26.6 Random number generation [rand]
26.6.2 Requirements [rand.req]
26.6.2.6 Random number distribution requirements [rand.req.dist]
A random number distribution(commonly shortened to distribution)d of type Dis 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 functionp(z) or .
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, 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.
A class Dmeets the requirements of a random number distributionif the expressions shown in Table 95are valid and have the indicated semantics, and if D and its associated types also meet all other requirements of this subclause [rand.req.dist].
In that Table and throughout this subclause,
- T is the type named byD's associated result_type;
- P is the type named byD's associated param_type;
- d is a value of D, andx and y are (possibly const) values of 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;
- p is a (possibly const) value of P;
- g, g1, and g2 are lvalues of a type meeting the requirements of a uniform random bit generator;
- os is an lvalue of the type of some class template specializationbasic_ostream<charT, traits>; and
- is is an lvalue of the type of some class template specializationbasic_istream<charT, traits>;
where charT and traits are constrained according to [strings] and [input.output].
Table 95: Random number distribution requirements [tab:rand.req.dist]
| Expression | Return type | Pre/post-condition | Complexity |
|---|---|---|---|
| D::result_type | T | T is an arithmetic type. | 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 valuep 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 associatedp(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 associatedp(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. |
| 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_base::failbit) (which may throw ios_base::failure ([iostate.flags])).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.Postconditions: The is.fmtflags are unchanged. |
D shall meet theCpp17CopyConstructible (Table 29) and Cpp17CopyAssignable (Table 31) requirements.
The sequence of numbers produced by repeated invocations of d(g)shall be independent of any invocation ofos << dor of any const member function of Dbetween any of the invocations d(g).
If a textual representation is written using os << xand that representation is restored into the same or a different object yof 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_typeis declared as a (nested) classor via a typedef.
In this subclause [rand], declarations of D::param_typeare in the form of typedefs for convenience of exposition only.
P shall meet theCpp17CopyConstructible (Table 29),Cpp17CopyAssignable (Table 31), andCpp17EqualityComparable (Table 25) requirements.
For each of the constructors of Dtaking 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 Dthat 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;