Boost C++ Libraries

boost/random/uniform_smallint.hpp

/* 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