In addition to the random number
generators, this library provides distribution functions which map
one distribution (often a uniform distribution provided by some
generator) to another.

Usually, there are several possible implementations of any given
mapping. Often, there is a choice between using more space, more
invocations of the underlying source of random numbers, or more
time-consuming arithmetic such as trigonometric functions. This
interface description does not mandate any specific implementation.
However, implementations which cannot reach certain values of the
specified distribution or otherwise do not converge statistically to
it are not acceptable.

choosing a random point on Earth (assumed to be a sphere) where to
spend the next vacations

The template parameters of the distribution functions are always in
the order

Underlying source of random numbers

If applicable, return type, with a default to a reasonable type.

The distribution functions no longer satisfy the input iterator
requirements (std:24.1.1 [lib.input.iterators]), because this is
redundant given the Generator interface and imposes a run-time
overhead on all users. Moreover, a Generator interface appeals to
random number generation as being more "natural". Use an
iterator adaptor
if you need to wrap any of the generators in an input iterator
interface.

All of the distribution functions described below store a non-const
reference to the underlying source of random numbers. Therefore, the
distribution functions are not Assignable. However, they are
CopyConstructible. Copying a distribution function will copy the
parameter values. Furthermore, both the copy and the original will
refer to the same underlying source of random numbers. Therefore,
both the copy and the original will obtain their underlying random
numbers from a single sequence.

In this description, I have refrained from documenting those members
in detail which are already defined in the
concept documentation.

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 rout=(max-min+1) the desired range of integer numbers,
and let rbase 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 rout will be
pout(i) = 1/rout. Likewise, assume a uniform
distribution on rbase for the underlying source of random
numbers, i.e. pbase(i) = 1/rbase. Let
pout_s(i) denote the random distribution generated by
uniform_smallint. Then the sum over all i in
rout of (pout_s(i)/pout(i)
-1)2 shall not exceed
rout/rbase2 (rbase mod
rout)(rout - rbase mod
rout).

Note: The property above is the square sum of the relative
differences in probabilities between the desired uniform distribution
pout(i) and the generated distribution
pout_s(i). The property can be fulfilled with the
calculation (base_rng mod rout), as follows: Let r =
rbase mod rout. The base distribution on
rbase is folded onto the range rout. The
numbers i < r have assigned (rbase div
rout)+1 numbers of the base distribution, the rest has only
(rbase div rout). Therefore,
pout_s(i) = ((rbase div rout)+1) /
rbase for i < r and pout_s(i) =
(rbase div rout)/rbase otherwise.
Substituting this in the above sum formula leads to the desired
result.

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

Members

uniform_smallint(IntType min, IntType max)

Effects: Constructs a uniform_smallint
functor. min and max are the lower and upper
bounds of the output range, respectively.

Description

The distribution function uniform_int 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}.

Returns: A uniform random number x in the range 0
<= x < n. [Note: This allows a
variate_generator object with a uniform_int
distribution to be used with std::random_shuffe, see
[lib.alg.random.shuffle]. ]

Description

The distribution function uniform_01 models a
random distribution.
On each invocation, it returns a random floating-point value uniformly
distributed in the range [0..1).
The value is computed using
std::numeric_limits<RealType>::digits random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits. [Note: Should this be configurable?]

The template parameter RealType shall denote a float-like
value type with support for binary operators +, -, and /. It must be
large enough to hold floating-point numbers of value
rng.max()-rng.min()+1.

base_type::result_type must be a number-like value type,
it must support static_cast<> to
RealType and binary operator -.

Note: The current implementation is buggy, because it may not
fill all of the mantissa with random bits. I'm unsure how to fill a
(to-be-invented) boost::bigfloat class with random bits
efficiently. It's probably time for a traits class.

Members

explicit uniform_01(base_type & rng)

Effects: Constructs a uniform_01 functor
with the given uniform random number generator as the underlying
source of random numbers.

Description

The distribution function uniform_real models a
random distribution.
On each invocation, it returns a random floating-point
value uniformly distributed in the range [min..max). The value is
computed using
std::numeric_limits<RealType>::digits random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits.

Note: The current implementation is buggy, because it may not
fill all of the mantissa with random bits.

Members

uniform_real(RealType min = RealType(0), RealType max = RealType(1))

Requires: min <= max
Effects: Constructs a
uniform_real object; min and
max are the parameters of the distribution.

Description

Instantiations of class template triangle_distribution
model a random
distribution. The returned floating-point values x
satisfy a <= x <= c; x has a triangle
distribution, where b is the most probable value for
x.

Members

triangle_distribution(result_type a, result_type b, result_type c)

Effects: Constructs a
triangle_distribution functor. a, b, c are
the parameters for the distribution.

Description

Instantiations of class template uniform_on_sphere model a
random distribution.
Such a distribution produces random numbers uniformly distributed on
the unit sphere of arbitrary dimension dim. The
Cont template parameter must be a STL-like container type
with begin and end operations returning
non-const ForwardIterators of type Cont::iterator.

Members

explicit uniform_on_sphere(int dim = 2)

Effects: Constructs a uniform_on_sphere
functor. dim is the dimension of the sphere.