Chris@16: /* boost random/uniform_int_distribution.hpp header file
Chris@16:  *
Chris@16:  * Copyright Jens Maurer 2000-2001
Chris@16:  * Copyright Steven Watanabe 2011
Chris@16:  * Distributed under the Boost Software License, Version 1.0. (See
Chris@16:  * accompanying file LICENSE_1_0.txt or copy at
Chris@16:  * http://www.boost.org/LICENSE_1_0.txt)
Chris@16:  *
Chris@16:  * See http://www.boost.org for most recent version including documentation.
Chris@16:  *
Chris@101:  * $Id$
Chris@16:  *
Chris@16:  * Revision history
Chris@16:  *  2001-04-08  added min<max assertion (N. Becker)
Chris@16:  *  2001-02-18  moved to individual header files
Chris@16:  */
Chris@16: 
Chris@16: #ifndef BOOST_RANDOM_UNIFORM_INT_DISTRIBUTION_HPP
Chris@16: #define BOOST_RANDOM_UNIFORM_INT_DISTRIBUTION_HPP
Chris@16: 
Chris@16: #include <iosfwd>
Chris@16: #include <ios>
Chris@16: #include <istream>
Chris@16: #include <boost/config.hpp>
Chris@16: #include <boost/limits.hpp>
Chris@16: #include <boost/assert.hpp>
Chris@16: #include <boost/random/detail/config.hpp>
Chris@16: #include <boost/random/detail/operators.hpp>
Chris@16: #include <boost/random/detail/uniform_int_float.hpp>
Chris@16: #include <boost/random/detail/signed_unsigned_tools.hpp>
Chris@16: #include <boost/type_traits/make_unsigned.hpp>
Chris@16: #include <boost/type_traits/is_integral.hpp>
Chris@101: #include <boost/mpl/bool.hpp>
Chris@16: 
Chris@16: namespace boost {
Chris@16: namespace random {
Chris@16: namespace detail {
Chris@16:     
Chris@16: 
Chris@16: #ifdef BOOST_MSVC
Chris@16: #pragma warning(push)
Chris@16: // disable division by zero warning, since we can't
Chris@16: // actually divide by zero.
Chris@16: #pragma warning(disable:4723)
Chris@16: #endif
Chris@16: 
Chris@16: template<class Engine, class T>
Chris@16: T generate_uniform_int(
Chris@16:     Engine& eng, T min_value, T max_value,
Chris@16:     boost::mpl::true_ /** is_integral<Engine::result_type> */)
Chris@16: {
Chris@16:     typedef T result_type;
Chris@16:     typedef typename make_unsigned<T>::type range_type;
Chris@16:     typedef typename Engine::result_type base_result;
Chris@16:     // ranges are always unsigned
Chris@16:     typedef typename make_unsigned<base_result>::type base_unsigned;
Chris@16:     const range_type range = random::detail::subtract<result_type>()(max_value, min_value);
Chris@16:     const base_result bmin = (eng.min)();
Chris@16:     const base_unsigned brange =
Chris@16:       random::detail::subtract<base_result>()((eng.max)(), (eng.min)());
Chris@16: 
Chris@16:     if(range == 0) {
Chris@16:       return min_value;    
Chris@16:     } else if(brange == range) {
Chris@16:       // this will probably never happen in real life
Chris@16:       // basically nothing to do; just take care we don't overflow / underflow
Chris@16:       base_unsigned v = random::detail::subtract<base_result>()(eng(), bmin);
Chris@16:       return random::detail::add<base_unsigned, result_type>()(v, min_value);
Chris@16:     } else if(brange < range) {
Chris@16:       // use rejection method to handle things like 0..3 --> 0..4
Chris@16:       for(;;) {
Chris@16:         // concatenate several invocations of the base RNG
Chris@16:         // take extra care to avoid overflows
Chris@16: 
Chris@16:         //  limit == floor((range+1)/(brange+1))
Chris@16:         //  Therefore limit*(brange+1) <= range+1
Chris@16:         range_type limit;
Chris@16:         if(range == (std::numeric_limits<range_type>::max)()) {
Chris@16:           limit = range/(range_type(brange)+1);
Chris@16:           if(range % (range_type(brange)+1) == range_type(brange))
Chris@16:             ++limit;
Chris@16:         } else {
Chris@16:           limit = (range+1)/(range_type(brange)+1);
Chris@16:         }
Chris@16: 
Chris@16:         // We consider "result" as expressed to base (brange+1):
Chris@16:         // For every power of (brange+1), we determine a random factor
Chris@16:         range_type result = range_type(0);
Chris@16:         range_type mult = range_type(1);
Chris@16: 
Chris@16:         // loop invariants:
Chris@16:         //  result < mult
Chris@16:         //  mult <= range
Chris@16:         while(mult <= limit) {
Chris@16:           // Postcondition: result <= range, thus no overflow
Chris@16:           //
Chris@16:           // limit*(brange+1)<=range+1                   def. of limit       (1)
Chris@16:           // eng()-bmin<=brange                          eng() post.         (2)
Chris@16:           // and mult<=limit.                            loop condition      (3)
Chris@16:           // Therefore mult*(eng()-bmin+1)<=range+1      by (1),(2),(3)      (4)
Chris@16:           // Therefore mult*(eng()-bmin)+mult<=range+1   rearranging (4)     (5)
Chris@16:           // result<mult                                 loop invariant      (6)
Chris@16:           // Therefore result+mult*(eng()-bmin)<range+1  by (5), (6)         (7)
Chris@16:           //
Chris@16:           // Postcondition: result < mult*(brange+1)
Chris@16:           //
Chris@16:           // result<mult                                 loop invariant      (1)
Chris@16:           // eng()-bmin<=brange                          eng() post.         (2)
Chris@16:           // Therefore result+mult*(eng()-bmin) <
Chris@16:           //           mult+mult*(eng()-bmin)            by (1)              (3)
Chris@16:           // Therefore result+(eng()-bmin)*mult <
Chris@16:           //           mult+mult*brange                  by (2), (3)         (4)
Chris@16:           // Therefore result+(eng()-bmin)*mult <
Chris@16:           //           mult*(brange+1)                   by (4)
Chris@16:           result += static_cast<range_type>(random::detail::subtract<base_result>()(eng(), bmin) * mult);
Chris@16: 
Chris@16:           // equivalent to (mult * (brange+1)) == range+1, but avoids overflow.
Chris@16:           if(mult * range_type(brange) == range - mult + 1) {
Chris@16:               // The destination range is an integer power of
Chris@16:               // the generator's range.
Chris@16:               return(result);
Chris@16:           }
Chris@16: 
Chris@16:           // Postcondition: mult <= range
Chris@16:           // 
Chris@16:           // limit*(brange+1)<=range+1                   def. of limit       (1)
Chris@16:           // mult<=limit                                 loop condition      (2)
Chris@16:           // Therefore mult*(brange+1)<=range+1          by (1), (2)         (3)
Chris@16:           // mult*(brange+1)!=range+1                    preceding if        (4)
Chris@16:           // Therefore mult*(brange+1)<range+1           by (3), (4)         (5)
Chris@16:           // 
Chris@16:           // Postcondition: result < mult
Chris@16:           //
Chris@16:           // See the second postcondition on the change to result. 
Chris@16:           mult *= range_type(brange)+range_type(1);
Chris@16:         }
Chris@16:         // loop postcondition: range/mult < brange+1
Chris@16:         //
Chris@16:         // mult > limit                                  loop condition      (1)
Chris@16:         // Suppose range/mult >= brange+1                Assumption          (2)
Chris@16:         // range >= mult*(brange+1)                      by (2)              (3)
Chris@16:         // range+1 > mult*(brange+1)                     by (3)              (4)
Chris@16:         // range+1 > (limit+1)*(brange+1)                by (1), (4)         (5)
Chris@16:         // (range+1)/(brange+1) > limit+1                by (5)              (6)
Chris@16:         // limit < floor((range+1)/(brange+1))           by (6)              (7)
Chris@16:         // limit==floor((range+1)/(brange+1))            def. of limit       (8)
Chris@16:         // not (2)                                       reductio            (9)
Chris@16:         //
Chris@16:         // loop postcondition: (range/mult)*mult+(mult-1) >= range
Chris@16:         //
Chris@16:         // (range/mult)*mult + range%mult == range       identity            (1)
Chris@16:         // range%mult < mult                             def. of %           (2)
Chris@16:         // (range/mult)*mult+mult > range                by (1), (2)         (3)
Chris@16:         // (range/mult)*mult+(mult-1) >= range           by (3)              (4)
Chris@16:         //
Chris@16:         // Note that the maximum value of result at this point is (mult-1),
Chris@16:         // so after this final step, we generate numbers that can be
Chris@16:         // at least as large as range.  We have to really careful to avoid
Chris@16:         // overflow in this final addition and in the rejection.  Anything
Chris@16:         // that overflows is larger than range and can thus be rejected.
Chris@16: 
Chris@16:         // range/mult < brange+1  -> no endless loop
Chris@16:         range_type result_increment =
Chris@16:             generate_uniform_int(
Chris@16:                 eng,
Chris@16:                 static_cast<range_type>(0),
Chris@16:                 static_cast<range_type>(range/mult),
Chris@16:                 boost::mpl::true_());
Chris@16:         if((std::numeric_limits<range_type>::max)() / mult < result_increment) {
Chris@16:           // The multiplcation would overflow.  Reject immediately.
Chris@16:           continue;
Chris@16:         }
Chris@16:         result_increment *= mult;
Chris@16:         // unsigned integers are guaranteed to wrap on overflow.
Chris@16:         result += result_increment;
Chris@16:         if(result < result_increment) {
Chris@16:           // The addition overflowed.  Reject.
Chris@16:           continue;
Chris@16:         }
Chris@16:         if(result > range) {
Chris@16:           // Too big.  Reject.
Chris@16:           continue;
Chris@16:         }
Chris@16:         return random::detail::add<range_type, result_type>()(result, min_value);
Chris@16:       }
Chris@16:     } else {                   // brange > range
Chris@16:       base_unsigned bucket_size;
Chris@16:       // it's safe to add 1 to range, as long as we cast it first,
Chris@16:       // because we know that it is less than brange.  However,
Chris@16:       // we do need to be careful not to cause overflow by adding 1
Chris@16:       // to brange.
Chris@16:       if(brange == (std::numeric_limits<base_unsigned>::max)()) {
Chris@16:         bucket_size = brange / (static_cast<base_unsigned>(range)+1);
Chris@16:         if(brange % (static_cast<base_unsigned>(range)+1) == static_cast<base_unsigned>(range)) {
Chris@16:           ++bucket_size;
Chris@16:         }
Chris@16:       } else {
Chris@16:         bucket_size = (brange+1) / (static_cast<base_unsigned>(range)+1);
Chris@16:       }
Chris@16:       for(;;) {
Chris@16:         base_unsigned result =
Chris@16:           random::detail::subtract<base_result>()(eng(), bmin);
Chris@16:         result /= bucket_size;
Chris@16:         // result and range are non-negative, and result is possibly larger
Chris@16:         // than range, so the cast is safe
Chris@16:         if(result <= static_cast<base_unsigned>(range))
Chris@16:           return random::detail::add<base_unsigned, result_type>()(result, min_value);
Chris@16:       }
Chris@16:     }
Chris@16: }
Chris@16: 
Chris@16: #ifdef BOOST_MSVC
Chris@16: #pragma warning(pop)
Chris@16: #endif
Chris@16: 
Chris@16: template<class Engine, class T>
Chris@16: inline T generate_uniform_int(
Chris@16:     Engine& eng, T min_value, T max_value,
Chris@16:     boost::mpl::false_ /** is_integral<Engine::result_type> */)
Chris@16: {
Chris@16:     uniform_int_float<Engine> wrapper(eng);
Chris@16:     return generate_uniform_int(wrapper, min_value, max_value, boost::mpl::true_());
Chris@16: }
Chris@16: 
Chris@16: template<class Engine, class T>
Chris@16: inline T generate_uniform_int(Engine& eng, T min_value, T max_value)
Chris@16: {
Chris@16:     typedef typename Engine::result_type base_result;
Chris@16:     return generate_uniform_int(eng, min_value, max_value,
Chris@16:         boost::is_integral<base_result>());
Chris@16: }
Chris@16: 
Chris@16: }
Chris@16: 
Chris@16: /**
Chris@16:  * The class template uniform_int_distribution models a \random_distribution.
Chris@16:  * On each invocation, it returns a random integer value uniformly
Chris@16:  * distributed in the set of integers {min, min+1, min+2, ..., max}.
Chris@16:  *
Chris@16:  * The template parameter IntType shall denote an integer-like value type.
Chris@16:  */
Chris@16: template<class IntType = int>
Chris@16: class uniform_int_distribution
Chris@16: {
Chris@16: public:
Chris@16:     typedef IntType input_type;
Chris@16:     typedef IntType result_type;
Chris@16: 
Chris@16:     class param_type
Chris@16:     {
Chris@16:     public:
Chris@16: 
Chris@16:         typedef uniform_int_distribution distribution_type;
Chris@16: 
Chris@16:         /**
Chris@16:          * Constructs the parameters of a uniform_int_distribution.
Chris@16:          *
Chris@16:          * Requires min <= max
Chris@16:          */
Chris@16:         explicit param_type(
Chris@16:             IntType min_arg = 0,
Chris@16:             IntType max_arg = (std::numeric_limits<IntType>::max)())
Chris@16:           : _min(min_arg), _max(max_arg)
Chris@16:         {
Chris@16:             BOOST_ASSERT(_min <= _max);
Chris@16:         }
Chris@16: 
Chris@16:         /** Returns the minimum value of the distribution. */
Chris@16:         IntType a() const { return _min; }
Chris@16:         /** Returns the maximum value of the distribution. */
Chris@16:         IntType b() const { return _max; }
Chris@16: 
Chris@16:         /** Writes the parameters to a @c std::ostream. */
Chris@16:         BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, param_type, parm)
Chris@16:         {
Chris@16:             os << parm._min << " " << parm._max;
Chris@16:             return os;
Chris@16:         }
Chris@16: 
Chris@16:         /** Reads the parameters from a @c std::istream. */
Chris@16:         BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, param_type, parm)
Chris@16:         {
Chris@16:             IntType min_in, max_in;
Chris@16:             if(is >> min_in >> std::ws >> max_in) {
Chris@16:                 if(min_in <= max_in) {
Chris@16:                     parm._min = min_in;
Chris@16:                     parm._max = max_in;
Chris@16:                 } else {
Chris@16:                     is.setstate(std::ios_base::failbit);
Chris@16:                 }
Chris@16:             }
Chris@16:             return is;
Chris@16:         }
Chris@16: 
Chris@16:         /** Returns true if the two sets of parameters are equal. */
Chris@16:         BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(param_type, lhs, rhs)
Chris@16:         { return lhs._min == rhs._min && lhs._max == rhs._max; }
Chris@16: 
Chris@16:         /** Returns true if the two sets of parameters are different. */
Chris@16:         BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(param_type)
Chris@16: 
Chris@16:     private:
Chris@16: 
Chris@16:         IntType _min;
Chris@16:         IntType _max;
Chris@16:     };
Chris@16: 
Chris@16:     /**
Chris@16:      * Constructs a uniform_int_distribution. @c min and @c max are
Chris@16:      * the parameters of the distribution.
Chris@16:      *
Chris@16:      * Requires: min <= max
Chris@16:      */
Chris@16:     explicit uniform_int_distribution(
Chris@16:         IntType min_arg = 0,
Chris@16:         IntType max_arg = (std::numeric_limits<IntType>::max)())
Chris@16:       : _min(min_arg), _max(max_arg)
Chris@16:     {
Chris@16:         BOOST_ASSERT(min_arg <= max_arg);
Chris@16:     }
Chris@16:     /** Constructs a uniform_int_distribution from its parameters. */
Chris@16:     explicit uniform_int_distribution(const param_type& parm)
Chris@16:       : _min(parm.a()), _max(parm.b()) {}
Chris@16: 
Chris@16:     /**  Returns the minimum value of the distribution */
Chris@16:     IntType min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return _min; }
Chris@16:     /**  Returns the maximum value of the distribution */
Chris@16:     IntType max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return _max; }
Chris@16: 
Chris@16:     /**  Returns the minimum value of the distribution */
Chris@16:     IntType a() const { return _min; }
Chris@16:     /**  Returns the maximum value of the distribution */
Chris@16:     IntType b() const { return _max; }
Chris@16: 
Chris@16:     /** Returns the parameters of the distribution. */
Chris@16:     param_type param() const { return param_type(_min, _max); }
Chris@16:     /** Sets the parameters of the distribution. */
Chris@16:     void param(const param_type& parm)
Chris@16:     {
Chris@16:         _min = parm.a();
Chris@16:         _max = parm.b();
Chris@16:     }
Chris@16: 
Chris@16:     /**
Chris@16:      * Effects: Subsequent uses of the distribution do not depend
Chris@16:      * on values produced by any engine prior to invoking reset.
Chris@16:      */
Chris@16:     void reset() { }
Chris@16: 
Chris@16:     /** Returns an integer uniformly distributed in the range [min, max]. */
Chris@16:     template<class Engine>
Chris@16:     result_type operator()(Engine& eng) const
Chris@16:     { return detail::generate_uniform_int(eng, _min, _max); }
Chris@16: 
Chris@16:     /**
Chris@16:      * Returns an integer uniformly distributed in the range
Chris@16:      * [param.a(), param.b()].
Chris@16:      */
Chris@16:     template<class Engine>
Chris@16:     result_type operator()(Engine& eng, const param_type& parm) const
Chris@16:     { return detail::generate_uniform_int(eng, parm.a(), parm.b()); }
Chris@16: 
Chris@16:     /** Writes the distribution to a @c std::ostream. */
Chris@16:     BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os, uniform_int_distribution, ud)
Chris@16:     {
Chris@16:         os << ud.param();
Chris@16:         return os;
Chris@16:     }
Chris@16: 
Chris@16:     /** Reads the distribution from a @c std::istream. */
Chris@16:     BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is, uniform_int_distribution, ud)
Chris@16:     {
Chris@16:         param_type parm;
Chris@16:         if(is >> parm) {
Chris@16:             ud.param(parm);
Chris@16:         }
Chris@16:         return is;
Chris@16:     }
Chris@16: 
Chris@16:     /**
Chris@16:      * Returns true if the two distributions will produce identical sequences
Chris@16:      * of values given equal generators.
Chris@16:      */
Chris@16:     BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(uniform_int_distribution, lhs, rhs)
Chris@16:     { return lhs._min == rhs._min && lhs._max == rhs._max; }
Chris@16:     
Chris@16:     /**
Chris@16:      * Returns true if the two distributions may produce different sequences
Chris@16:      * of values given equal generators.
Chris@16:      */
Chris@16:     BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(uniform_int_distribution)
Chris@16: 
Chris@16: private:
Chris@16:     IntType _min;
Chris@16:     IntType _max;
Chris@16: };
Chris@16: 
Chris@16: } // namespace random
Chris@16: } // namespace boost
Chris@16: 
Chris@16: #endif // BOOST_RANDOM_UNIFORM_INT_HPP