Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

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

  1. additive_combine_engine();

    Constructs an additive_combine_engine using the default constructors of the two base generators.

  2. explicit additive_combine_engine(result_type seed);

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

  3. 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] 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.

  4. 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.

  5. 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

  1. static result_type min();

    Returns the smallest value that the generator can produce

  2. static result_type max();

    Returns the largest value that the generator can produce

additive_combine_engine public member functions

  1. void seed();

    Seeds an additive_combine_engine using the default seeds of the two base generators.

  2. void seed(result_type seed);

    Seeds an additive_combine_engine, using seed as the seed for both base generators.

  3. 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.

  4. 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.

  5. 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

  6. result_type operator()();

    Returns the next value of the generator.

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

    Fills a range with random values

  8. void discard(boost::uintmax_t z);

    Advances the state of the generator by z.

additive_combine_engine friend functions

  1. 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.

  2. 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.

  3. 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.

  4. 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.


PrevUpHomeNext