P1068R11 Vector API for random number generation

- adjust subclause labels
- adjust subclause heading to fit the surroundings

Author: jensmaurer

source/algorithms.tex

@@ -24,6 +24,7 @@
 \ref{alg.sorting}              & Sorting and related operations    & \\ \rowsep
 \ref{numeric.ops}              & Generalized numeric operations    & \tcode{<numeric>} \\ \rowsep
 \ref{specialized.algorithms}   & Specialized \tcode{<memory>} algorithms & \tcode{<memory>} \\ \rowsep
+\ref{alg.rand}                 & Specialized \tcode{<random>} algorithms & \tcode{<random>} \\ \rowsep
 \ref{alg.c.library}            & C library algorithms              & \tcode{<cstdlib>} \\
 \end{libsumtab}
 
@@ -11580,6 +11581,138 @@
 \end{codeblock}
 \end{itemdescr}
 
+\rSec1[alg.rand]{Specialized \tcode{<random>} algorithms}
+
+\rSec2[alg.rand.general]{General}
+
+\pnum
+The contents specified in \ref{alg.rand}
+are declared in the header \libheaderrefx{random}{rand.synopsis}.
+
+\rSec2[alg.rand.generate]{\tcode{generate_random}}
+
+\begin{itemdecl}
+template<class R, class G>
+  requires @\libconcept{output_range}@<R, invoke_result_t<G&>> && @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+constexpr borrowed_iterator_t<R> ranges::generate_random(R&& r, G&& g);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+\begin{itemize}
+\item
+Calls \tcode{g.generate_random(std::forward<R>(r))}
+if this expression is well-formed.
+\item
+Otherwise, if \tcode{R} models \tcode{sized_range},
+fills \tcode{r} with \tcode{ranges::size(r)} values of
+type \tcode{invoke_result_t<G\&>} by performing
+an unspecified number of invocations of
+the form \tcode{g()} or \tcode{g.generate_random(s)},
+if such an expression is well-formed for a value \tcode{N} and
+an object \tcode{s} of type \tcode{span<invoke_result_t<G\&>, N>}.
+\begin{note}
+Values of \tcode{N} can differ between invocations.
+\end{note}
+\item
+Otherwise, calls \tcode{ranges::generate(std::forward<R>(r), ref(g))}.
+\end{itemize}
+
+\pnum
+\returns
+\tcode{ranges::end(r)}.
+
+\pnum
+\remarks
+The effects of \tcode{generate_random(r, g)} shall be equivalent to
+\tcode{ranges::generate(std::for\-ward<R>(r), ref(g))}.
+\begin{note}
+This implies that \tcode{g.generate_random(a)} fills \tcode{a}
+with the same values as produced by invocation of \tcode{g()}.
+\end{note}
+\end{itemdescr}
+
+\begin{itemdecl}
+template<class G, @\libconcept{output_iterator}@<invoke_result_t<G&>> O, @\libconcept{sentinel_for}@<O> S>
+  requires @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+constexpr O ranges::generate_random(O first, S last, G&& g);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Equivalent to:
+\begin{codeblock}
+return generate_random(subrange<O, S>(std::move(first), last), g);
+\end{codeblock}
+\end{itemdescr}
+
+\begin{itemdecl}
+template<class R, class G, class D>
+  requires @\libconcept{output_range}@<R, invoke_result_t<D&, G&>> && @\libconcept{invocable}@<D&, G&> &&
+           @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+constexpr borrowed_iterator_t<R> ranges::generate_random(R&& r, G&& g, D&& d);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+\begin{itemize}
+\item
+Calls \tcode{d.generate_random(std::forward<R>(r), g)}
+if this expression is well-formed.
+\item
+Otherwise, if \tcode{R} models \tcode{sized_range},
+fills \tcode{r} with \tcode{ranges::size(r)} values of
+type \tcode{invoke_result_t<D\&, G\&>}
+by performing an unspecified number of invocations of
+the form \tcode{invoke(d, g)} or \tcode{d.generate_random(s, g)},
+if such an expression is well-formed
+for a value \tcode{N} and
+an object \tcode{s} of type \tcode{span<invoke_result_t<D\&, G\&>, N>}.
+\begin{note}
+Values of N can differ between invocations.
+\end{note}
+\item
+Otherwise, calls
+\begin{codeblock}
+ranges::generate(std::forward<R>(r), [&d, &g] { return invoke(d, g); });
+\end{codeblock}
+\end{itemize}
+
+\pnum
+\returns
+\tcode{ranges::end(r)}
+
+\pnum
+\remarks
+The effects of \tcode{generate_random(r, g, d)} shall be equivalent to
+\begin{codeblock}
+ranges::generate(std::forward<R>(r), [&d, &g] { return invoke(d, g); })}
+\end{codeblock}
+\begin{note}
+This implies that \tcode{d.generate_random(a, g)}
+fills \tcode{a} with the values with the same random distribution
+as produced by invocation of \tcode{invoke(d, g)}.
+\end{note}
+\end{itemdescr}
+
+\begin{itemdecl}
+template<class G, class D, @\libconcept{output_iterator}@<invoke_result_t<D&, G&>> O, @\libconcept{sentinel_for}@<O> S>
+  requires @\libconcept{invocable}@<D&, G&> && @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+constexpr O ranges::generate_random(O first, S last, G&& g, D&& d);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Equivalent to:
+\begin{codeblock}
+return generate_random(subrange<O, S>(std::move(first), last), g, d);
+\end{codeblock}
+\end{itemdescr}
+
 \rSec1[alg.c.library]{C library algorithms}
 
 \pnum

source/numerics.tex

@@ -1432,6 +1432,27 @@
   template<class RealType, size_t digits, class URBG>
     RealType generate_canonical(URBG& g);
 
+  namespace ranges {
+    // \ref{alg.rand.generate}, \tcode{generate_random}
+    template<class R, class G>
+      requires @\libconcept{output_range}@<R, invoke_result_t<G&>> &&
+               @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+      constexpr borrowed_iterator_t<R> generate_random(R&& r, G&& g);
+
+    template<class G, @\libconcept{output_iterator}@<invoke_result_t<G&>> O, @\libconcept{sentinel_for}@<O> S>
+      requires @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+      constexpr O generate_random(O first, S last, G&& g);
+
+    template<class R, class G, class D>
+      requires @\libconcept{output_range}@<R, invoke_result_t<D&, G&>> && @\libconcept{invocable}@<D&, G&> &&
+               @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+    constexpr borrowed_iterator_t<R> generate_random(R&& r, G&& g, D&& d);
+
+    template<class G, class D, @\libconcept{output_iterator}@<invoke_result_t<D&, G&>> O, @\libconcept{sentinel_for}@<O> S>
+      requires @\libconcept{invocable}@<D&, G&> && @\libconcept{uniform_random_bit_generator}@<remove_cvref_t<G>>
+    constexpr O generate_random(O first, S last, G&& g, D&& d);
+  }
+
   // \ref{rand.dist.uni.int}, class template \tcode{uniform_int_distribution}
   template<class IntType = int>
     class uniform_int_distribution;

source/support.tex

@@ -664,6 +664,7 @@
 #define @\defnlibxname{cpp_lib_fstream_native_handle}@             202306L // also in \libheader{fstream}
 #define @\defnlibxname{cpp_lib_function_ref}@                      202306L // also in \libheader{functional}
 #define @\defnlibxname{cpp_lib_gcd_lcm}@                           201606L // also in \libheader{numeric}
+#define @\defnlibxname{cpp_lib_generate_random}@                   202403  // also in \libheader{random}
 #define @\defnlibxname{cpp_lib_generator}@                         202207L // also in \libheader{generator}
 #define @\defnlibxname{cpp_lib_generic_associative_lookup}@        201304L // also in \libheader{map}, \libheader{set}
 #define @\defnlibxname{cpp_lib_generic_unordered_lookup}@          201811L