Class template uniform_smallint

boost::uniform_smallint

Synopsis

// In header: <boost/random/uniform_smallint.hpp>

template<typename IntType = int> 
class uniform_smallint {
public:
  // types
  typedef IntType input_type; 
  typedef IntType result_type;

  // construct/copy/destruct
  uniform_smallint(IntType = 0, IntType = 9);

  // public member functions
  result_type min() const;
  result_type max() const;
  void reset();
  template<typename Engine> result_type operator()(Engine &);
};

Description

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_out=(max-min+1) the desired range of integer numbers, and let r_base 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_out will be p_out(i) = 1/r_out. Likewise, assume a uniform distribution on r_base for the underlying source of random numbers, i.e. p_base(i) = 1/r_base. Let p_{out_s}(i) denote the random distribution generated by uniform_smallint. Then the sum over all i in r_out of (p_{out_s}(i)/p_out(i) - 1)² shall not exceed r_out/r_base² (r_base mod r_out)(r_out - r_base mod r_out).

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_out(i) and the generated distribution p_{out_s}(i). The property can be fulfilled with the calculation (base_rng mod r_out), as follows: Let r = r_base mod r_out. The base distribution on r_base is folded onto the range r_out. The numbers i < r have assigned (r_base div r_out)+1 numbers of the base distribution, the rest has only (r_base div r_out). Therefore, p_{out_s}(i) = ((r_base div r_out)+1) / r_base for i < r and p_{out_s}(i) = (r_base div r_out)/r_base otherwise. Substituting this in the above sum formula leads to the desired result.

Note: The upper bound for (r_base mod r_out) (r_out - r_base mod r_out) is r_out²/4. Regarding the upper bound for the square sum of the relative quantization error of r_out³/(4*r_base²), it seems wise to either choose r_base so that r_base > 10*r_out² or ensure that r_base is divisible by r_out.

`uniform_smallint` public construct/copy/destruct

```
uniform_smallint(IntType min_arg = 0, IntType max_arg = 9);
```
Constructs a uniform_smallint. min and max are the lower and upper bounds of the output range, respectively.

`uniform_smallint` public member functions

```
result_type min() const;
```
```
result_type max() const;
```
```
void reset();
```

template<typename Engine> result_type operator()(Engine & eng);

Boost C++ Libraries