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) or 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 [tab:RandomDistribution] 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,
T is the type named by D's associated result_type;
P is the type named by D's associated param_type;
d is a value of D, and x 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 satisfying the requirements of a uniform random number generator [[rand.req.urng]];
os is an lvalue of the type of some class template specialization basic_ostream<charT, traits>; and
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].
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 | post: 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. post: 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]]). pre: 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. post: The is.fmtflags are unchanged. |
D shall satisfy the requirements of CopyConstructible (Table [copyconstructible]) and CopyAssignable (Table [copyassignable]) 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 [copyconstructible]), CopyAssignable (Table [copyassignable]), and EqualityComparable (Table [equalitycomparable]) 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.