29 Numerics library [numerics]

29.5 Random number generation [rand]

29.5.8 Utilities [rand.util]

29.5.8.2 Function template generate_canonical [rand.util.canonical]

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

Let

(1.1)
r be numeric_limits<RealType>::radix,
(1.2)
R be $g.max() - g.min() + 1$ ,
(1.3)
d be the smaller of digits and numeric_limits<RealType>::digits,249
(1.4)
k be the smallest integer such that $R^{k} \geq r^{d}$ , and
(1.5)
x be $⌊ R^{k} / r^{d} ⌋$ .

An attempt is k invocations of g() to obtain values

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

, respectively, and the calculation of a quantity S given by Formula 29.1:

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

Effects: Attempts are made until

S < x r^{d}

[Note 1:

When R is a power of r, precisely one attempt is made.

— end note]

Returns:

⌊ S / x ⌋ / r^{d}

[Note 2:

The return value c satisfies

0 \leq c < 1

— end note]

Throws: What and when g throws.

Complexity: Exactly k invocations of g per attempt.

[Note 3:

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]

[Note 4:

When R is a power of r, an implementation can avoid using an arithmetic type that is wider than the output when computing S.

— end note]

249)249)

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