Class template shuffle_order

Class template shuffle_order_engine

boost::random::shuffle_order_engine

Synopsis

// In header: <boost/random/shuffle_order.hpp>

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

  // construct/copy/destruct
  shuffle_order_engine();
  explicit shuffle_order_engine(result_type);
  template<typename SeedSeq> explicit shuffle_order_engine(SeedSeq &);
  explicit shuffle_order_engine(const base_type &);
  explicit shuffle_order_engine(base_type &&);
  template<typename It> shuffle_order_engine(It &, It);

  // public member functions
  void seed();
  void seed(result_type);
  template<typename SeedSeq> void seed(SeedSeq &);
  template<typename It> void seed(It &, It);
  const base_type & base() const;
  result_type operator()();
  void discard(boost::uintmax_t);
  template<typename Iter> void generate(Iter, Iter);

  // public static functions
  static result_type min();
  static result_type max();

  // friend functions
  template<typename CharT, typename Traits> 
    friend std::basic_ostream< CharT, Traits > & 
    operator<<(std::basic_ostream< CharT, Traits > &, 
               const shuffle_order_engine &);
  template<typename CharT, typename Traits> 
    friend std::basic_istream< CharT, Traits > & 
    operator>>(std::basic_istream< CharT, Traits > &, 
               const shuffle_order_engine &);
  friend bool operator==(const shuffle_order_engine &, 
                         const shuffle_order_engine &);
  friend bool operator!=(const shuffle_order_engine &, 
                         const shuffle_order_engine &);

  // public data members
  static const bool has_fixed_range;
  static const std::size_t buffer_size;
  static const std::size_t table_size;
};

Description

Instatiations of class template shuffle_order_engine model a pseudo-random number generator . It mixes the output of some (usually linear_congruential_engine) uniform random number generator to get better statistical properties. The algorithm is described in

"Improving a poor random number generator", Carter Bays and S.D. Durham, ACM Transactions on Mathematical Software, Vol 2, No. 1, March 1976, pp. 59-64. http://doi.acm.org/10.1145/355666.355670

The output of the base generator is buffered in an array of length k. Every output X(n) has a second role: It gives an index into the array where X(n+1) will be retrieved. Used array elements are replaced with fresh output from the base generator.

Template parameters are the base generator and the array length k, which should be around 100.

`shuffle_order_engine` public construct/copy/destruct

```
shuffle_order_engine();
```
Constructs a shuffle_order_engine by invoking the default constructor of the base generator.

Complexity: Exactly k+1 invocations of the base generator.
```
explicit shuffle_order_engine(result_type s);
```
Constructs a shuffle_output_engine by invoking the one-argument constructor of the base generator with the parameter seed.

Complexity: Exactly k+1 invocations of the base generator.

template<typename SeedSeq> explicit shuffle_order_engine(SeedSeq & seq);

```
explicit shuffle_order_engine(const base_type & rng);
```
Constructs a shuffle_output_engine by using a copy of the provided generator.

Precondition: The template argument UniformRandomNumberGenerator shall denote a CopyConstructible type.

Complexity: Exactly k+1 invocations of the base generator.

explicit shuffle_order_engine(base_type && rng);

template<typename It> shuffle_order_engine(It & first, It last);

`shuffle_order_engine` public member functions

```
void seed();
```
```
void seed(result_type seed);
```
Invokes the one-argument seed method of the base generator with the parameter seed and re-initializes the internal buffer array.

Complexity: Exactly k+1 invocations of the base generator.
```
template<typename SeedSeq> void seed(SeedSeq & seq);
```
Invokes the one-argument seed method of the base generator with the parameter seq and re-initializes the internal buffer array.

Complexity: Exactly k+1 invocations of the base generator.

template<typename It> void seed(It & first, It last);

```
const base_type & base() const;
```
```
result_type operator()();
```
```
void discard(boost::uintmax_t z);
```
Advances the generator by z steps.

template<typename Iter> void generate(Iter first, Iter last);

Fills a range with pseudo-random values.

`shuffle_order_engine` public static functions

```
static result_type min();
```
Returns the smallest value that the generator can produce.
```
static result_type max();
```
Returns the largest value that the generator can produce.

`shuffle_order_engine` friend functions

template<typename CharT, typename Traits> 
  friend std::basic_ostream< CharT, Traits > & 
  operator<<(std::basic_ostream< CharT, Traits > & os, 
             const shuffle_order_engine & s);

Writes a shuffle_order_engine to a std::ostream.

template<typename CharT, typename Traits> 
  friend std::basic_istream< CharT, Traits > & 
  operator>>(std::basic_istream< CharT, Traits > & is, 
             const shuffle_order_engine & s);

Reads a shuffle_order_engine from a std::istream.

friend bool operator==(const shuffle_order_engine & x, 
                       const shuffle_order_engine & y);

Returns true if the two generators will produce identical sequences.

friend bool operator!=(const shuffle_order_engine & lhs, 
                       const shuffle_order_engine & rhs);

Returns true if the two generators will produce different sequences.