[rand.req.eng] (original) (raw)
29 Numerics library [numerics]
29.5 Random number generation [rand]
29.5.3 Requirements [rand.req]
29.5.3.4 Random number engine requirements [rand.req.eng]
A random number engine(commonly shortened to engine)e of type Eis a uniform random bit generator that additionally meets the requirements (e.g., for seeding and for input/output) specified in this subclause.
At any given time,e has a state efor some integer i ≥ 0.
Upon construction,ehas an initial state e.
An engine's state may be established via a constructor, a seed function, assignment, or a suitable operator>>.
E's specification shall define:
- the size of E's state in multiples of the size of result_type, given as an integral constant expression;
- the transition algorithm TA by which e's state e is advanced to its successor state e; and
- the generation algorithm GA by which an engine's state is mapped to a value of type result_type.
A class Ethat meets the requirements of a uniform random bit generatoralso meets the requirements of a random number engineif the expressions shown in Table 125are valid and have the indicated semantics, and if E also meets all other requirements of [rand.req.eng].
In Table 125 and throughout this subclause:
- T is the type named byE's associated result_type;
- e is a value of E,v is an lvalue of E,x and y are (possibly const) values of E;
- s is a value of T;
- q is an lvalue meeting the requirements of a seed sequence;
- z is a value of type unsigned long long;
- 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 125 — Random number engine requirements [tab:rand.req.eng]
| 🔗Expression | Return type | Pre/post-condition | Complexity |
|---|---|---|---|
| 🔗E() | Creates an engine with the same initial state as all other default-constructed engines of type E. | ||
| 🔗E(x) | Creates an engine that compares equal to x. | ||
| 🔗E(s) | Creates an engine with initial state determined by s. | ||
| 🔗E(q)241 | Creates an engine with an initial state that depends on a sequence produced by one call to q.generate. | same as complexity of q.generate called on a sequence whose length is size of state | |
| 🔗e.seed() | void | Postconditions: e == E(). | same as E() |
| 🔗e.seed(s) | void | Postconditions: e == E(s). | same as E(s) |
| 🔗e.seed(q) | void | Postconditions: e == E(q). | same as E(q) |
| 🔗e() | T | Advances e's state e toe e) and returnsGA(e). | per [rand.req.urng] |
| 🔗e.discard(z)242 | void | Advances e's state e to by any means equivalent to z consecutive calls e(). | no worse than the complexity of z consecutive calls e() |
| 🔗x == y | bool | This operator is an equivalence relation. With and as the infinite sequences of values that would be generated by repeated future calls to x() and y(), respectively, returns true if ; else returns false. | |
| 🔗x != y | bool | !(x == y). |
These operations shall each be of complexity no worse than .
On hosted implementations, the following expressions are well-formed and have the specified semantics.
Effects: With os.fmtflags set toios_base::dec|ios_base::leftand the fill character set to the space character, writes to osthe textual representation of x's current state.
In the output, adjacent numbers are separated by one or more space characters.
Postconditions: The os.fmtflags and fill character are unchanged.
Result: reference to the type of os.
Preconditions: is provides a textual representation that was previously written using an output stream whose imbued locale was the same as that of is, and whose type's template specialization argumentscharT and traitswere respectively the same as those of is.
Effects: With is._fmtflags_set to ios_base::dec, sets v's state as determined by reading its textual representation from is.
If bad input is encountered, ensures that v's state is unchanged by the operation and calls is.setstate(ios_base::failbit)(which may throw ios_base::failure ([iostate.flags])).
If a textual representation written via os << xwas subsequently read via is >> v, then x == vprovided that there have been no intervening invocations of x or of v.
Postconditions: The is.fmtflags are unchanged.
Result: reference to the type of is.