Skip to content

Commit 8639700

Browse files
authored
Merge 2023-11 LWG Motion 8
P0952R2 A new specification for std::generate_canonical
2 parents 4f057a7 + 5e686a8 commit 8639700

File tree

1 file changed

+37
-25
lines changed

1 file changed

+37
-25
lines changed

source/numerics.tex

Lines changed: 37 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1371,7 +1371,7 @@
13711371
class seed_seq;
13721372

13731373
// \ref{rand.util.canonical}, function template \tcode{generate_canonical}
1374-
template<class RealType, size_t bits, class URBG>
1374+
template<class RealType, size_t digits, class URBG>
13751375
RealType generate_canonical(URBG& g);
13761376

13771377
// \ref{rand.dist.uni.int}, class template \tcode{uniform_int_distribution}
@@ -3971,28 +3971,47 @@
39713971

39723972
\indexlibraryglobal{generate_canonical}%
39733973
\begin{itemdecl}
3974-
template<class RealType, size_t bits, class URBG>
3974+
template<class RealType, size_t digits, class URBG>
39753975
RealType generate_canonical(URBG& g);
39763976
\end{itemdecl}
39773977

39783978
\begin{itemdescr}
39793979
\pnum
3980-
\effects
3981-
Invokes \tcode{g()} $k$ times
3982-
to obtain values $g_0, \dotsc, g_{k-1}$, respectively.
3983-
Calculates a quantity
3980+
Let
3981+
\begin{itemize}
3982+
\item $r$ be \tcode{numeric_limits<RealType>::radix},
3983+
\item $R$ be $\tcode{g.max()} - \tcode{g.min()} + 1$,
3984+
\item $d$ be the smaller of
3985+
\tcode{digits} and \tcode{numeric_limits<RealType>::digits},
3986+
\begin{footnote}
3987+
$d$ is introduced to avoid any attempt
3988+
to produce more bits of randomness
3989+
than can be held in \tcode{RealType}.
3990+
\end{footnote}
3991+
\item $k$ be the smallest integer such that $R^k \ge r^d$, and
3992+
\item $x$ be $\left\lfloor R^k / r^d \right\rfloor$.
3993+
\end{itemize}
3994+
An \defn{attempt} is $k$ invocations of \tcode{g()}
3995+
to obtain values $g_0, \dotsc, g_{k-1}$, respectively,
3996+
and the calculation of a quantity
39843997
\[
39853998
S = \sum_{i=0}^{k-1} (g_i - \tcode{g.min()})
39863999
\cdot R^i
39874000
\]
3988-
using arithmetic of type
3989-
\tcode{RealType}.
4001+
4002+
\pnum
4003+
\effects
4004+
Attempts are made until $S < xr^d$.
4005+
\begin{note}
4006+
When $R$ is a power of $r$, precisely one attempt is made.
4007+
\end{note}
39904008

39914009
\pnum
39924010
\returns
3993-
$S / R^k$.
4011+
$\left\lfloor S / x \right\rfloor / r^d$.
39944012
\begin{note}
3995-
$0 \leq S / R^k < 1$.
4013+
The return value $c$ satisfies
4014+
$0 \leq c < 1$.
39964015
\end{note}
39974016

39984017
\pnum
@@ -4001,21 +4020,7 @@
40014020

40024021
\pnum
40034022
\complexity
4004-
Exactly
4005-
$k = \max(1, \left\lceil b / \log_2 R \right\rceil)$
4006-
invocations
4007-
of \tcode{g},
4008-
where $b$
4009-
\begin{footnote}
4010-
$b$ is introduced
4011-
to avoid any attempt
4012-
to produce more bits of randomness
4013-
than can be held in \tcode{RealType}.
4014-
\end{footnote}
4015-
is the lesser of \tcode{numeric_limits<RealType>::digits}
4016-
and \tcode{bits},
4017-
and
4018-
$R$ is the value of $\tcode{g.max()} - \tcode{g.min()} + 1$.
4023+
Exactly $k$ invocations of \tcode{g} per attempt.
40194024

40204025
\pnum
40214026
\begin{note}
@@ -4028,6 +4033,13 @@
40284033
into a value
40294034
that can be delivered by a random number distribution.
40304035
\end{note}
4036+
4037+
\pnum
4038+
\begin{note}
4039+
When $R$ is a power of $r$,
4040+
an implementation can avoid using an arithmetic type that is wider
4041+
than the output when computing $S$.
4042+
\end{note}
40314043
\end{itemdescr}
40324044

40334045
\indextext{random number generation!utilities|)}

0 commit comments

Comments
 (0)