[rand.adapt] (original) (raw)

29 Numerics library [numerics]

29.5 Random number generation [rand]

29.5.5 Random number engine adaptor class templates [rand.adapt]

29.5.5.1 General [rand.adapt.general]

Except where specified otherwise, the complexity of each function specified in [rand.adapt] is constant.

Except where specified otherwise, no function described in [rand.adapt] throws an exception.

Every function described in [rand.adapt] that has a function parameter q of type Sseq&for a template type parameter named Sseqthat is different from type seed_seqthrows what and when the invocation of q.generate throws.

Descriptions are provided in [rand.adapt] only for adaptor operations that are not described in subclause [rand.req.adapt]or for operations where there is additional semantic information.

In particular, declarations for copy constructors, for copy assignment operators, for streaming operators, and for equality and inequality operators are not shown in the synopses.

Each template specified in [rand.adapt] requires one or more relationships, involving the value(s) of its constant template parameter(s), to hold.

A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

29.5.5.2 Class template discard_block_engine [rand.adapt.disc]

A discard_block_engine random number engine adaptor produces random numbers selected from those produced by some base engine e.

The state xof a discard_block_engine engine adaptor object xconsists of the state e of its base engine eand an additional integer n.

The size of the state is the size of e's state plus 1.

The transition algorithm discards all but values from each block of p ≥ r values delivered by e.

The state transition is performed as follows: If n ≥ r, advance the state of e from e to e and set n to 0.

In any case, then increment n and advance e's then-current state e to e.

The generation algorithm yields the value returned by the last invocation of e() while advancing e's state as described above.

namespace std { template<class Engine, size_t p, size_t r> class discard_block_engine { public: using result_type = typename Engine::result_type;static constexpr size_t block_size = p;static constexpr size_t used_block = r;static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } discard_block_engine();explicit discard_block_engine(const Engine& e);explicit discard_block_engine(Engine&& e);explicit discard_block_engine(result_type s);template<class Sseq> explicit discard_block_engine(Sseq& q);void seed();void seed(result_type s);template<class Sseq> void seed(Sseq& q);friend bool operator==(const discard_block_engine& x, const discard_block_engine& y); result_type operator()();void discard(unsigned long long z);const Engine& base() const noexcept { return e; } template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const discard_block_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, discard_block_engine& x); private: Engine e; size_t n; };}

The following relations shall hold:0 < randr <= p.

The textual representation consists of the textual representation of efollowed by the value of n.

In addition to its behavior pursuant to subclause [rand.req.adapt], each constructorthat is not a copy constructor sets n to 0.

29.5.5.3 Class template independent_bits_engine [rand.adapt.ibits]

An independent_bits_enginerandom number engine adaptor combines random numbers that are produced by some base engine e, so as to produce random numbers with a specified number of bits w.

The state xof an independent_bits_engineengine adaptor object xconsists of the state e of its base engine e; the size of the state is the size of e's state.

The transition and generation algorithms are described in terms of the following integral constants:

[Note 1:

The relation always holds.

— _end note_]

The transition algorithm is carried out by invoking e()as often as needed to obtain values less than and values less than .

The generation algorithm uses the values produced while advancing the state as described above to yield a quantity Sobtained as if by the following algorithm:S = 0;for (k = 0; ; k += 1) { do u = e() - e.min(); while ();S = ;} for (k = ; k ≠ n; k += 1) { do u = e() - e.min(); while ();S = ;}

namespace std { template<class Engine, size_t w, class UIntType> class independent_bits_engine { public: using result_type = UIntType;static constexpr result_type min() { return 0; } static constexpr result_type max() { return ; } independent_bits_engine();explicit independent_bits_engine(const Engine& e);explicit independent_bits_engine(Engine&& e);explicit independent_bits_engine(result_type s);template<class Sseq> explicit independent_bits_engine(Sseq& q);void seed();void seed(result_type s);template<class Sseq> void seed(Sseq& q);friend bool operator==(const independent_bits_engine& x, const independent_bits_engine& y); result_type operator()();void discard(unsigned long long z);const Engine& base() const noexcept { return e; } template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const independent_bits_engine& x); template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, independent_bits_engine& x); private: Engine e; };}

The following relations shall hold:0 < wandw <= numeric_limits<result_type>​::​digits.

The textual representation consists of the textual representation of e.

29.5.5.4 Class template shuffle_order_engine [rand.adapt.shuf]

A shuffle_order_engine random number engine adaptor produces the same random numbers that are produced by some base engine e, but delivers them in a different sequence.

The state xof a shuffle_order_engine engine adaptor object xconsists of the state e of its base engine e, an additional value Y of the type delivered by e, and an additional sequence V of k values also of the type delivered by e.

The size of the state is the size of e's state plus .

The transition algorithm permutes the values produced by e.

The state transition is performed as follows:

The generation algorithm yields the last value of Y produced while advancing e's state as described above.

namespace std { template<class Engine, size_t k> class shuffle_order_engine { public: using result_type = typename Engine::result_type;static constexpr size_t table_size = k;static constexpr result_type min() { return Engine::min(); } static constexpr result_type max() { return Engine::max(); } shuffle_order_engine();explicit shuffle_order_engine(const Engine& e);explicit shuffle_order_engine(Engine&& e);explicit shuffle_order_engine(result_type s);template<class Sseq> explicit shuffle_order_engine(Sseq& q);void seed();void seed(result_type s);template<class Sseq> void seed(Sseq& q);friend bool operator==(const shuffle_order_engine& x, const shuffle_order_engine& y); result_type operator()();void discard(unsigned long long z);const Engine& base() const noexcept { return e; } template<class charT, class traits> friend basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const shuffle_order_engine& x);template<class charT, class traits> friend basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, shuffle_order_engine& x);private: Engine e; result_type V[k]; result_type Y; };}

The following relation shall hold:0 < k.

The textual representation consists of the textual representation of e, followed by the k values of V, followed by the value of Y.

In addition to its behavior pursuant to subclause [rand.req.adapt], each constructorthat is not a copy constructor initializes V[0], …, V[k - 1] and Y, in that order, with values returned by successive invocations of e().