| /* boost random/uniform_smallint.hpp header file |
| * |
| * Copyright Jens Maurer 2000-2001 |
| * Distributed under the Boost Software License, Version 1.0. (See |
| * accompanying file LICENSE_1_0.txt or copy at |
| * http://www.boost.org/LICENSE_1_0.txt) |
| * |
| * See http://www.boost.org for most recent version including documentation. |
| * |
| * $Id: uniform_smallint.hpp 60755 2010-03-22 00:45:06Z steven_watanabe $ |
| * |
| * Revision history |
| * 2001-04-08 added min<max assertion (N. Becker) |
| * 2001-02-18 moved to individual header files |
| */ |
| |
| #ifndef BOOST_RANDOM_UNIFORM_SMALLINT_HPP |
| #define BOOST_RANDOM_UNIFORM_SMALLINT_HPP |
| |
| #include <cassert> |
| #include <iostream> |
| #include <boost/config.hpp> |
| #include <boost/limits.hpp> |
| #include <boost/static_assert.hpp> |
| #include <boost/random/detail/config.hpp> |
| #include <boost/random/uniform_01.hpp> |
| #include <boost/detail/workaround.hpp> |
| |
| namespace boost { |
| |
| // uniform integer distribution on a small range [min, max] |
| |
| /** |
| * The distribution function uniform_smallint models a \random_distribution. |
| * On each invocation, it returns a random integer value uniformly distributed |
| * in the set of integer numbers {min, min+1, min+2, ..., max}. It assumes |
| * that the desired range (max-min+1) is small compared to the range of the |
| * underlying source of random numbers and thus makes no attempt to limit |
| * quantization errors. |
| * |
| * Let r<sub>out</sub>=(max-min+1) the desired range of integer numbers, and |
| * let r<sub>base</sub> be the range of the underlying source of random |
| * numbers. Then, for the uniform distribution, the theoretical probability |
| * for any number i in the range r<sub>out</sub> will be p<sub>out</sub>(i) = |
| * 1/r<sub>out</sub>. Likewise, assume a uniform distribution on r<sub>base</sub> for |
| * the underlying source of random numbers, i.e. p<sub>base</sub>(i) = |
| * 1/r<sub>base</sub>. Let p<sub>out_s</sub>(i) denote the random |
| * distribution generated by @c uniform_smallint. Then the sum over all |
| * i in r<sub>out</sub> of (p<sub>out_s</sub>(i)/p<sub>out</sub>(i) - 1)<sup>2</sup> |
| * shall not exceed r<sub>out</sub>/r<sub>base</sub><sup>2</sup> |
| * (r<sub>base</sub> mod r<sub>out</sub>)(r<sub>out</sub> - |
| * r<sub>base</sub> mod r<sub>out</sub>). |
| * |
| * The template parameter IntType shall denote an integer-like value type. |
| * |
| * Note: The property above is the square sum of the relative differences |
| * in probabilities between the desired uniform distribution |
| * p<sub>out</sub>(i) and the generated distribution p<sub>out_s</sub>(i). |
| * The property can be fulfilled with the calculation |
| * (base_rng mod r<sub>out</sub>), as follows: Let r = r<sub>base</sub> mod |
| * r<sub>out</sub>. The base distribution on r<sub>base</sub> is folded onto the |
| * range r<sub>out</sub>. The numbers i < r have assigned (r<sub>base</sub> |
| * div r<sub>out</sub>)+1 numbers of the base distribution, the rest has |
| * only (r<sub>base</sub> div r<sub>out</sub>). Therefore, |
| * p<sub>out_s</sub>(i) = ((r<sub>base</sub> div r<sub>out</sub>)+1) / |
| * r<sub>base</sub> for i < r and p<sub>out_s</sub>(i) = (r<sub>base</sub> |
| * div r<sub>out</sub>)/r<sub>base</sub> otherwise. Substituting this in the |
| * above sum formula leads to the desired result. |
| * |
| * Note: The upper bound for (r<sub>base</sub> mod r<sub>out</sub>) |
| * (r<sub>out</sub> - r<sub>base</sub> mod r<sub>out</sub>) is |
| * r<sub>out</sub><sup>2</sup>/4. Regarding the upper bound for the |
| * square sum of the relative quantization error of |
| * r<sub>out</sub><sup>3</sup>/(4*r<sub>base</sub><sup>2</sup>), it |
| * seems wise to either choose r<sub>base</sub> so that r<sub>base</sub> > |
| * 10*r<sub>out</sub><sup>2</sup> or ensure that r<sub>base</sub> is |
| * divisible by r<sub>out</sub>. |
| */ |
| template<class IntType = int> |
| class uniform_smallint |
| { |
| public: |
| typedef IntType input_type; |
| typedef IntType result_type; |
| |
| /** |
| * Constructs a @c uniform_smallint. @c min and @c max are the |
| * lower and upper bounds of the output range, respectively. |
| */ |
| explicit uniform_smallint(IntType min_arg = 0, IntType max_arg = 9) |
| : _min(min_arg), _max(max_arg) |
| { |
| #ifndef BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS |
| // MSVC fails BOOST_STATIC_ASSERT with std::numeric_limits at class scope |
| BOOST_STATIC_ASSERT(std::numeric_limits<IntType>::is_integer); |
| #endif |
| } |
| |
| result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () const { return _min; } |
| result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () const { return _max; } |
| void reset() { } |
| |
| template<class Engine> |
| result_type operator()(Engine& eng) |
| { |
| typedef typename Engine::result_type base_result; |
| base_result _range = static_cast<base_result>(_max-_min)+1; |
| base_result _factor = 1; |
| |
| // LCGs get bad when only taking the low bits. |
| // (probably put this logic into a partial template specialization) |
| // Check how many low bits we can ignore before we get too much |
| // quantization error. |
| base_result r_base = (eng.max)() - (eng.min)(); |
| if(r_base == (std::numeric_limits<base_result>::max)()) { |
| _factor = 2; |
| r_base /= 2; |
| } |
| r_base += 1; |
| if(r_base % _range == 0) { |
| // No quantization effects, good |
| _factor = r_base / _range; |
| } else { |
| // carefully avoid overflow; pessimizing here |
| for( ; r_base/_range/32 >= _range; _factor *= 2) |
| r_base /= 2; |
| } |
| |
| return static_cast<result_type>(((eng() - (eng.min)()) / _factor) % _range + _min); |
| } |
| |
| #ifndef BOOST_RANDOM_NO_STREAM_OPERATORS |
| template<class CharT, class Traits> |
| friend std::basic_ostream<CharT,Traits>& |
| operator<<(std::basic_ostream<CharT,Traits>& os, const uniform_smallint& ud) |
| { |
| os << ud._min << " " << ud._max; |
| return os; |
| } |
| |
| template<class CharT, class Traits> |
| friend std::basic_istream<CharT,Traits>& |
| operator>>(std::basic_istream<CharT,Traits>& is, uniform_smallint& ud) |
| { |
| is >> std::ws >> ud._min >> std::ws >> ud._max; |
| return is; |
| } |
| #endif |
| |
| private: |
| |
| result_type _min; |
| result_type _max; |
| }; |
| |
| } // namespace boost |
| |
| #endif // BOOST_RANDOM_UNIFORM_SMALLINT_HPP |