24 Numerics library [numerics]

24.7 Random number generation [rand]

24.7.2 Requirements [rand.req]

24.7.2.4 Random number engine requirements [rand.req.eng]

1
#
A random number engine (commonly shortened to engine) e of type E is a uniform random bit generator that additionally meets the requirements (e.g., for seeding and for input/output) specified in this subclause.
2
#
At any given time, e has a state e for some integer .
Upon construction, e has an initial state e.
An engine's state may be established via a constructor, a seed function, assignment, or a suitable operator>>.
3
#
E's specification shall define:
  1. a)
    the size of E's state in multiples of the size of result_­type, given as an integral constant expression;
  2. b)
    the transition algorithm TA by which e's state e is advanced to its successor state e; and
  3. c)
    the generation algorithm GA by which an engine's state is mapped to a value of type result_­type.
4
#
A class E that satisfies the requirements of a uniform random bit generator also satisfies the requirements of a random number engine if the expressions shown in Table 84 are valid and have the indicated semantics, and if E also satisfies all other requirements of this subclause [rand.req.eng].
In that Table and throughout this subclause:
  1. a)
    T is the type named by E's associated result_­type;
  2. b)
    e is a value of E, v is an lvalue of E, x and y are (possibly const) values of E;
  3. c)
    s is a value of T;
  4. d)
    q is an lvalue satisfying the requirements of a seed sequence;
  5. e)
    z is a value of type unsigned long long;
  6. f)
    os is an lvalue of the type of some class template specialization basic_­ostream<charT, traits>; and
  7. g)
    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 84 — Random number engine requirements
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)247
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
Ensures: e == E().
same as E()
e.seed(s)
void
Ensures: e == E(s).
same as E(s)
e.seed(q)
void
Ensures: e == E(q).
same as E(q)
e()
T
Advances e's state e to e e) and returns GA(e).
e.discard(z) 248
void
Advances e's state e to e 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).
os << x
reference to the type of os
With os.fmtflags set to ios_­base​::​dec|ios_­base​::​left and the fill character set to the space character, writes to os the textual representation of x's current state.
In the output, adjacent numbers are separated by one or more space characters.
Ensures: The os.fmtflags and fill character are unchanged.
is >> v
reference to the type of is
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​::​failbit) (which may throw ios​::​failure ([iostate.flags])).
If a textual representation written via os << x was subsequently read via is >> v, then x == v provided that there have been no intervening invocations of x or of v.
Requires: 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 arguments charT and traits were respectively the same as those of is.
Ensures: The is.fmtflags are unchanged.
5
#
E shall satisfy the Cpp17CopyConstructible (Table 26) and Cpp17CopyAssignable (Table 28) requirements.
These operations shall each be of complexity no worse than .
247)
This constructor (as well as the subsequent corresponding seed() function) may be particularly useful to applications requiring a large number of independent random sequences.
248)
This operation is common in user code, and can often be implemented in an engine-specific manner so as to provide significant performance improvements over an equivalent naive loop that makes z consecutive calls e().