From 5e686a89ecb9a4989c5b00548e7d229c6a3ac226 Mon Sep 17 00:00:00 2001
From: Dawn Perchik <dawn@brightsidecomputing.com>
Date: Tue, 14 Nov 2023 16:35:25 -0800
Subject: [PATCH] P0952R2 A new specification for std::generate_canonical

Editorial note: In [rand.util.canonical], moved veriables and
definitions used elsewhere outside of Effects: element.
---
 source/numerics.tex | 62 +++++++++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 25 deletions(-)

diff --git a/source/numerics.tex b/source/numerics.tex
index a8293f2c3a..50fbb0d68a 100644
--- a/source/numerics.tex
+++ b/source/numerics.tex
@@ -1371,7 +1371,7 @@
   class seed_seq;
 
   // \ref{rand.util.canonical}, function template \tcode{generate_canonical}
-  template<class RealType, size_t bits, class URBG>
+  template<class RealType, size_t digits, class URBG>
     RealType generate_canonical(URBG& g);
 
   // \ref{rand.dist.uni.int}, class template \tcode{uniform_int_distribution}
@@ -3971,28 +3971,47 @@
 
 \indexlibraryglobal{generate_canonical}%
 \begin{itemdecl}
-template<class RealType, size_t bits, class URBG>
+template<class RealType, size_t digits, class URBG>
   RealType generate_canonical(URBG& g);
 \end{itemdecl}
 
 \begin{itemdescr}
 \pnum
-\effects
- Invokes \tcode{g()} $k$ times
- to obtain values $g_0, \dotsc, g_{k-1}$, respectively.
- Calculates a quantity
+Let
+\begin{itemize}
+\item $r$ be \tcode{numeric_limits<RealType>::radix},
+\item $R$ be $\tcode{g.max()} - \tcode{g.min()} + 1$,
+\item $d$ be the smaller of
+  \tcode{digits} and \tcode{numeric_limits<RealType>::digits},
+  \begin{footnote}
+  $d$ is introduced to avoid any attempt
+  to produce more bits of randomness
+  than can be held in \tcode{RealType}.
+  \end{footnote}
+\item $k$ be the smallest integer such that $R^k \ge r^d$, and
+\item $x$ be $\left\lfloor R^k / r^d \right\rfloor$.
+\end{itemize}
+An \defn{attempt} is $k$ invocations of \tcode{g()}
+to obtain values $g_0, \dotsc, g_{k-1}$, respectively,
+and the calculation of a quantity
  \[
    S = \sum_{i=0}^{k-1} (g_i - \tcode{g.min()})
                         \cdot R^i
  \]
- using arithmetic of type
- \tcode{RealType}.
+
+\pnum
+\effects
+Attempts are made until $S < xr^d$.
+\begin{note}
+When $R$ is a power of $r$, precisely one attempt is made.
+\end{note}
 
 \pnum
 \returns
-$S / R^k$.
+$\left\lfloor S / x \right\rfloor / r^d$.
 \begin{note}
-$0 \leq S / R^k < 1$.
+The return value $c$ satisfies
+$0 \leq c < 1$.
 \end{note}
 
 \pnum
@@ -4001,21 +4020,7 @@
 
 \pnum
 \complexity
-Exactly
- $k = \max(1, \left\lceil b / \log_2 R \right\rceil)$
- invocations
- of \tcode{g},
- where $b$
-\begin{footnote}
-$b$ is introduced
-   to avoid any attempt
-   to produce more bits of randomness
-   than can be held in \tcode{RealType}.
-\end{footnote}
-   is the lesser of \tcode{numeric_limits<RealType>::digits}
-                and \tcode{bits},
- and
-   $R$ is the value of $\tcode{g.max()} - \tcode{g.min()} + 1$.
+Exactly $k$ invocations of \tcode{g} per attempt.
 
 \pnum
 \begin{note}
@@ -4028,6 +4033,13 @@
 into a value
 that can be delivered by a random number distribution.
 \end{note}
+
+\pnum
+\begin{note}
+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}
 \end{itemdescr}
 
 \indextext{random number generation!utilities|)}