Class template additive_combine

Class template additive_combine_engine

boost::random::additive_combine_engine

Synopsis

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

template<typename MLCG1, typename MLCG2> 
class additive_combine_engine {
public:
  // types
  typedef MLCG1              first_base; 
  typedef MLCG2              second_base;
  typedef MLCG1::result_type result_type;

  // construct/copy/destruct
  additive_combine_engine();
  explicit additive_combine_engine(result_type);
  template<typename SeedSeq> explicit additive_combine_engine(SeedSeq &);
  additive_combine_engine(typename MLCG1::result_type, 
                          typename MLCG2::result_type);
  template<typename It> additive_combine_engine(It &, It);

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

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

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

  // public data members
  static const bool has_fixed_range;
};

Description

An instantiation of class template additive_combine_engine models a pseudo-random number generator . It combines two multiplicative linear_congruential_engine number generators, i.e. those with c = 0. It is described in

"Efficient and Portable Combined Random Number Generators", Pierre L'Ecuyer, Communications of the ACM, Vol. 31, No. 6, June 1988, pp. 742-749, 774

The template parameters MLCG1 and MLCG2 shall denote two different linear_congruential_engine number generators, each with c = 0. Each invocation returns a random number X(n) := (MLCG1(n) - MLCG2(n)) mod (m1 - 1), where m1 denotes the modulus of MLCG1.

`additive_combine_engine` public construct/copy/destruct

```
additive_combine_engine();
```
Constructs an additive_combine_engine using the default constructors of the two base generators.
```
explicit additive_combine_engine(result_type seed);
```
Constructs an additive_combine_engine, using seed as the constructor argument for both base generators.

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

Constructs an additive_combine_engine, using seq as the constructor argument for both base generators.

	Warning
	The semantics of this function are liable to change. A `seed_seq` is designed to generate all the seeds in one shot, but this seeds the two base engines independantly and probably ends up giving the same sequence to both.

additive_combine_engine(typename MLCG1::result_type seed1, 
                        typename MLCG2::result_type seed2);

Constructs an additive_combine_engine, using seed1 and seed2 as the constructor argument to the first and second base generators, respectively.

```
template<typename It> additive_combine_engine(It & first, It last);
```
Contructs an additive_combine_engine with values from the range defined by the input iterators first and last. first will be modified to point to the element after the last one used.

Throws: std::invalid_argument if the input range is too small.

Exception Safety: Basic

`additive_combine_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

`additive_combine_engine` public member functions

```
void seed();
```
Seeds an additive_combine_engine using the default seeds of the two base generators.
```
void seed(result_type seed);
```
Seeds an additive_combine_engine, using seed as the seed for both base generators.
```
template<typename SeedSeq> void seed(SeedSeq & seq);
```
Seeds an additive_combine_engine, using seq to seed both base generators.

See the warning on the corresponding constructor.
```
void seed(typename MLCG1::result_type seed1, 
          typename MLCG2::result_type seed2);
```
Seeds an additive_combine generator, using seed1 and seed2 as the seeds to the first and second base generators, respectively.
```
template<typename It> void seed(It & first, It last);
```
Seeds an additive_combine_engine with values from the range defined by the input iterators first and last. first will be modified to point to the element after the last one used.

Throws: std::invalid_argument if the input range is too small.

Exception Safety: Basic
```
result_type operator()();
```
Returns the next value of the generator.

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

Fills a range with random values

```
void discard(boost::uintmax_t z);
```
Advances the state of the generator by z.

`additive_combine_engine` friend functions

```
template<typename CharT, typename Traits> 
  friend std::basic_ostream< CharT, Traits > & 
  operator<<(std::basic_ostream< CharT, Traits > & os, 
             const additive_combine_engine & r);
```
Writes the state of an additive_combine_engine to a std::ostream. The textual representation of an additive_combine_engine is the textual representation of the first base generator followed by the textual representation of the second base generator.

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

Reads the state of an additive_combine_engine from a std::istream.

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

Returns: true iff the two additive_combine_engines will produce the same sequence of values.

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

Returns: true iff the two additive_combine_engines will produce different sequences of values.