boost/random/xor_combine.hpp

   1 /* boost random/xor_combine.hpp header file
   2  *
   3  * Copyright Jens Maurer 2002
   4  * Distributed under the Boost Software License, Version 1.0. (See
   5  * accompanying file LICENSE_1_0.txt or copy at
   6  * http://www.boost.org/LICENSE_1_0.txt)
   7  *
   8  * See http://www.boost.org for most recent version including documentation.
   9  *
  10  * $Id: xor_combine.hpp 71018 2011-04-05 21:27:52Z steven_watanabe $
  11  *
  12  */
  13
  14 #ifndef BOOST_RANDOM_XOR_COMBINE_HPP
  15 #define BOOST_RANDOM_XOR_COMBINE_HPP
  16
  17 #include <istream>
  18 #include <iosfwd>
  19 #include <cassert>
  20 #include <algorithm> // for std::min and std::max
  21 #include <boost/config.hpp>
  22 #include <boost/limits.hpp>
  23 #include <boost/cstdint.hpp>     // uint32_t
  24 #include <boost/random/detail/config.hpp>
  25 #include <boost/random/detail/seed.hpp>
  26 #include <boost/random/detail/seed_impl.hpp>
  27
  28 namespace boost {
  29 namespace random {
  30
  31 /**
  32  * Instantiations of @c xor_combine_engine model a
  33  * \pseudo_random_number_generator.  To produce its output it
  34  * invokes each of the base generators, shifts their results
  35  * and xors them together.
  36  */
  37 template<class URNG1, int s1, class URNG2, int s2>
  38 class xor_combine_engine
  39 {
  40 public:
  41     typedef URNG1 base1_type;
  42     typedef URNG2 base2_type;
  43     typedef typename base1_type::result_type result_type;
  44
  45     BOOST_STATIC_CONSTANT(bool, has_fixed_range = false);
  46     BOOST_STATIC_CONSTANT(int, shift1 = s1);
  47     BOOST_STATIC_CONSTANT(int, shift2 = s2);
  48
  49     /**
  50      * Constructors a @c xor_combine_engine by default constructing
  51      * both base generators.
  52      */
  53     xor_combine_engine() : _rng1(), _rng2() { }
  54
  55     /** Constructs a @c xor_combine by copying two base generators. */
  56     xor_combine_engine(const base1_type & rng1, const base2_type & rng2)
  57       : _rng1(rng1), _rng2(rng2) { }
  58
  59     /**
  60      * Constructs a @c xor_combine_engine, seeding both base generators
  61      * with @c v.
  62      *
  63      * @xmlwarning
  64      * The exact algorithm used by this function may change in the future.
  65      * @endxmlwarning
  66      */
  67     BOOST_RANDOM_DETAIL_ARITHMETIC_CONSTRUCTOR(xor_combine_engine,
  68         result_type, v)
  69     { seed(v); }
  70
  71     /**
  72      * Constructs a @c xor_combine_engine, seeding both base generators
  73      * with values produced by @c seq.
  74      */
  75     BOOST_RANDOM_DETAIL_SEED_SEQ_CONSTRUCTOR(xor_combine_engine,
  76         SeedSeq, seq)
  77     { seed(seq); }
  78
  79     /**
  80      * Constructs a @c xor_combine_engine, seeding both base generators
  81      * with values from the iterator range [first, last) and changes
  82      * first to point to the element after the last one used.  If there
  83      * are not enough elements in the range to seed both generators,
  84      * throws @c std::invalid_argument.
  85      */
  86     template<class It> xor_combine_engine(It& first, It last)
  87       : _rng1(first, last), _rng2( /* advanced by other call */ first, last) { }
  88
  89     /** Calls @c seed() for both base generators. */
  90     void seed() { _rng1.seed(); _rng2.seed(); }
  91
  92     /** @c seeds both base generators with @c v. */
  93     BOOST_RANDOM_DETAIL_ARITHMETIC_SEED(xor_combine_engine, result_type, v)
  94     { _rng1.seed(v); _rng2.seed(v); }
  95
  96     /** @c seeds both base generators with values produced by @c seq. */
  97     BOOST_RANDOM_DETAIL_SEED_SEQ_SEED(xor_combine_engine, SeedSeq, seq)
  98     { _rng1.seed(seq); _rng2.seed(seq); }
  99
 100     /**
 101      * seeds both base generators with values from the iterator
 102      * range [first, last) and changes first to point to the element
 103      * after the last one used.  If there are not enough elements in
 104      * the range to seed both generators, throws @c std::invalid_argument.
 105      */
 106     template<class It> void seed(It& first, It last)
 107     {
 108         _rng1.seed(first, last);
 109         _rng2.seed(first, last);
 110     }
 111
 112     /** Returns the first base generator. */
 113     const base1_type& base1() const { return _rng1; }
 114
 115     /** Returns the second base generator. */
 116     const base2_type& base2() const { return _rng2; }
 117
 118     /** Returns the next value of the generator. */
 119     result_type operator()()
 120     {
 121         return (_rng1() << s1) ^ (_rng2() << s2);
 122     }
 123
 124     /** Fills a range with random values */
 125     template<class Iter>
 126     void generate(Iter first, Iter last)
 127     { detail::generate_from_int(*this, first, last); }
 128
 129     /** Advances the state of the generator by @c z. */
 130     void discard(boost::uintmax_t z)
 131     {
 132         _rng1.discard(z);
 133         _rng2.discard(z);
 134     }
 135
 136     /** Returns the smallest value that the generator can produce. */
 137     static result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () { return (std::min)((URNG1::min)(), (URNG2::min)()); }
 138     /** Returns the largest value that the generator can produce. */
 139     static result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () { return (std::max)((URNG1::min)(), (URNG2::max)()); }
 140
 141     /**
 142      * Writes the textual representation of the generator to a @c std::ostream.
 143      */
 144     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, xor_combine_engine, s)
 145     {
 146         os << s._rng1 << ' ' << s._rng2;
 147         return os;
 148     }
 149
 150     /**
 151      * Reads the textual representation of the generator from a @c std::istream.
 152      */
 153     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, xor_combine_engine, s)
 154     {
 155         is >> s._rng1 >> std::ws >> s._rng2;
 156         return is;
 157     }
 158
 159     /** Returns true if the two generators will produce identical sequences. */
 160     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(xor_combine_engine, x, y)
 161     { return x._rng1 == y._rng1 && x._rng2 == y._rng2; }
 162
 163     /** Returns true if the two generators will produce different sequences. */
 164     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(xor_combine_engine)
 165
 166 private:
 167     base1_type _rng1;
 168     base2_type _rng2;
 169 };
 170
 171 #ifndef BOOST_NO_INCLASS_MEMBER_INITIALIZATION
 172 //  A definition is required even for integral static constants
 173 template<class URNG1, int s1, class URNG2, int s2>
 174 const bool xor_combine_engine<URNG1, s1, URNG2, s2>::has_fixed_range;
 175 template<class URNG1, int s1, class URNG2, int s2>
 176 const int xor_combine_engine<URNG1, s1, URNG2, s2>::shift1;
 177 template<class URNG1, int s1, class URNG2, int s2>
 178 const int xor_combine_engine<URNG1, s1, URNG2, s2>::shift2;
 179 #endif
 180
 181 /// \cond show_private
 182
 183 /** Provided for backwards compatibility. */
 184 template<class URNG1, int s1, class URNG2, int s2,
 185     typename URNG1::result_type v = 0>
 186 class xor_combine : public xor_combine_engine<URNG1, s1, URNG2, s2>
 187 {
 188     typedef xor_combine_engine<URNG1, s1, URNG2, s2> base_type;
 189 public:
 190     typedef typename base_type::result_type result_type;
 191     xor_combine() {}
 192     xor_combine(result_type val) : base_type(val) {}
 193     template<class It>
 194     xor_combine(It& first, It last) : base_type(first, last) {}
 195     xor_combine(const URNG1 & rng1, const URNG2 & rng2)
 196       : base_type(rng1, rng2) { }
 197
 198     result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (std::min)((this->base1().min)(), (this->base2().min)()); }
 199     result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return (std::max)((this->base1().min)(), (this->base2().max)()); }
 200 };
 201
 202 /// \endcond
 203
 204 } // namespace random
 205 } // namespace boost
 206
 207 #endif // BOOST_RANDOM_XOR_COMBINE_HPP