26 Numerics library [numerics]

Each type instantiated from a class template specified in this section [rand.eng] satisfies the requirements of a random number engine adaptor ([rand.req.adapt]) type.

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

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

Descriptions are provided in this section [rand.adapt] only for adaptor operations that are not described in section [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 this section [rand.adapt] requires one or more relationships, involving the value(s) of its non-type template parameter(s), to hold. A program instantiating any of these templates is ill-formed if any such required relationship fails to hold.

A discard_block_engine random number engine adaptor produces random numbers selected from those produced by some base engine e. The state x_i of a discard_block_engine engine adaptor object x consists of the state e_i of its base engine e and an additional integer n. The size of the state is the size of e's state plus 1.

The transition algorithm discards all but r > 0 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_i to e_i+p-r and set n to 0. In any case, then increment n and advance e's then-current state e_j to e_j+1.

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

template<class Engine, size_t p, size_t r>
 class discard_block_engine{
public:
 // types
 typedef typename Engine::result_type result_type;

 // engine characteristics
 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(); }

 // constructors and seeding functions
 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);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;   // exposition only
 int n;      // exposition only
};

The following relations shall hold: 0 < r and r <= p.

The textual representation consists of the textual representation of e followed by the value of n.

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

An independent_bits_engine random 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 x_i of an independent_bits_engine engine adaptor object x consists of the state e_i 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:

1. (2.1)

   Let R = e.max() - e.min() + 1 and m = ⌊ log₂ R ⌋ .

2. (2.2)

   With n as determined below, let w₀ = ⌊ w / n ⌋ , n₀ = n - w mod n , y₀ = 2^w₀ ⌊ R / 2^w₀ ⌋ , and y₁ = 2^{w₀ + 1} ⌊ R / 2^{w₀ + 1} ⌋ .

3. (2.3)

   Let n = ⌈ w / m ⌉ if and only if the relation R - y₀ ≤ ⌊ y₀ / n ⌋ holds as a result. Otherwise let n = 1 + ⌈ w / m ⌉ .

[ Note: The relation w = n₀ w₀ + (n - n₀)(w₀ + 1) always holds.  — end note ]

The transition algorithm is carried out by invoking e() as often as needed to obtain n₀ values less than y₀ + e.min() and n - n₀ values less than y₁ + e.min() .

The generation algorithm uses the values produced while advancing the state as described above to yield a quantity S obtained as if by the following algorithm:

S = 0;
for (k = 0; k ≠ n0; k += 1)  {
 do u = e() - e.min(); while ( u ≥ y0 );
 S =  2w0 · S + u mod 2w0 ;
}
for (k = n0; k ≠ n; k += 1)  {
 do u = e() - e.min(); while ( u ≥ y1 );
 S =  2w0 + 1 · S + u mod 2w0 + 1 ;
}

template<class Engine, size_t w, class UIntType>
class independent_bits_engine{
public:
 // types
 typedef UIntType result_type;

 // engine characteristics
 static constexpr result_type min() { return 0; }
 static constexpr result_type max() { return 2w - 1; }

 // constructors and seeding functions
 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);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;   // exposition only
};

The following relations shall hold: 0 < w and w <= numeric_limits<result_type>::digits.

The textual representation consists of the textual representation of e.

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 x_i of a shuffle_order_engine engine adaptor object x consists of the state e_i 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 k+1.

The transition algorithm permutes the values produced by e. The state transition is performed as follows:

1. (2.1)

   Calculate an integer .

2. (2.2)

   Set Y to V_j and then set V_j to e().

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

template<class Engine, size_t k>
 class shuffle_order_engine{
public:
 // types
 typedef typename Engine::result_type result_type;

 // engine characteristics
 static constexpr size_t table_size = k;
 static constexpr result_type min() { return Engine::min(); }
 static constexpr result_type max() { return Engine::max(); }

 // constructors and seeding functions
 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);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;           // exposition only
 result_type Y;      // exposition only
 result_type V[k];   // exposition only
};

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 section [rand.req.adapt], each constructor that is not a copy constructor initializes V[0], …, V[k-1] and Y, in that order, with values returned by successive invocations of e().