28 Numerics library [numerics]

28.5 Random number generation [rand]

28.5.8 Utilities [rand.util]

28.5.8.2 Function template generate_canonical [rand.util.canonical]

template<class RealType, size_t bits, class URBG>
  RealType generate_canonical(URBG& g);

Effects: Invokes g() k times to obtain values

g_{0}, \dots, g_{k - 1}

, respectively.

Calculates a quantity

S = k - 1 \sum i = 0 (g_{i} - g.min()) \cdot R^{i}

using arithmetic of type RealType.

Returns:

S / R^{k}

[Note 1:

0 \leq S / R^{k} < 1

— end note]

Throws: What and when g throws.

Complexity: Exactly

k = max (1, ⌈ b / log_{2} R ⌉)

invocations of g, where b230 is the lesser of numeric_limits<RealType>::digits and bits, and R is the value of

g.max() - g.min() + 1

[Note 2:

If the values

g_{i}

produced by g are uniformly distributed, the instantiation's results are distributed as uniformly as possible.

Obtaining a value in this way can be a useful step in the process of transforming a value generated by a uniform random bit generator into a value that can be delivered by a random number distribution.

— end note]

230)230)

b is introduced to avoid any attempt to produce more bits of randomness than can be held in RealType.