diff --git a/source/algorithms.tex b/source/algorithms.tex index a175a9a2b6..ec47564de5 100644 --- a/source/algorithms.tex +++ b/source/algorithms.tex @@ -24,6 +24,7 @@ \ref{alg.sorting} & Sorting and related operations & \\ \rowsep \ref{numeric.ops} & Generalized numeric operations & \tcode{} \\ \rowsep \ref{specialized.algorithms} & Specialized \tcode{} algorithms & \tcode{} \\ \rowsep +\ref{alg.rand} & Specialized \tcode{} algorithms & \tcode{} \\ \rowsep \ref{alg.c.library} & C library algorithms & \tcode{} \\ \end{libsumtab} @@ -11667,6 +11668,138 @@ \end{codeblock} \end{itemdescr} +\rSec1[alg.rand]{Specialized \tcode{} 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 + requires @\libconcept{output_range}@> && @\libconcept{uniform_random_bit_generator}@> +constexpr borrowed_iterator_t ranges::generate_random(R&& r, G&& g); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +\begin{itemize} +\item +Calls \tcode{g.generate_random(std::forward(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} 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, N>}. +\begin{note} +Values of \tcode{N} can differ between invocations. +\end{note} +\item +Otherwise, calls \tcode{ranges::generate(std::forward(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), 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> O, @\libconcept{sentinel_for}@ S> + requires @\libconcept{uniform_random_bit_generator}@> +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(std::move(first), last), g); +\end{codeblock} +\end{itemdescr} + +\begin{itemdecl} +template + requires @\libconcept{output_range}@> && @\libconcept{invocable}@ && + @\libconcept{uniform_random_bit_generator}@> +constexpr borrowed_iterator_t 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), 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} +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, N>}. +\begin{note} +Values of N can differ between invocations. +\end{note} +\item +Otherwise, calls +\begin{codeblock} +ranges::generate(std::forward(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), [&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> O, @\libconcept{sentinel_for}@ S> + requires @\libconcept{invocable}@ && @\libconcept{uniform_random_bit_generator}@> +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(std::move(first), last), g, d); +\end{codeblock} +\end{itemdescr} + \rSec1[alg.c.library]{C library algorithms} \pnum diff --git a/source/numerics.tex b/source/numerics.tex index d6635df3da..807fed24cb 100644 --- a/source/numerics.tex +++ b/source/numerics.tex @@ -1432,6 +1432,27 @@ template RealType generate_canonical(URBG& g); + namespace ranges { + // \ref{alg.rand.generate}, \tcode{generate_random} + template + requires @\libconcept{output_range}@> && + @\libconcept{uniform_random_bit_generator}@> + constexpr borrowed_iterator_t generate_random(R&& r, G&& g); + + template> O, @\libconcept{sentinel_for}@ S> + requires @\libconcept{uniform_random_bit_generator}@> + constexpr O generate_random(O first, S last, G&& g); + + template + requires @\libconcept{output_range}@> && @\libconcept{invocable}@ && + @\libconcept{uniform_random_bit_generator}@> + constexpr borrowed_iterator_t generate_random(R&& r, G&& g, D&& d); + + template> O, @\libconcept{sentinel_for}@ S> + requires @\libconcept{invocable}@ && @\libconcept{uniform_random_bit_generator}@> + 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 uniform_int_distribution; diff --git a/source/support.tex b/source/support.tex index e0ab97c30b..5e055e0d2b 100644 --- a/source/support.tex +++ b/source/support.tex @@ -740,6 +740,7 @@ #define @\defnlibxname{cpp_lib_ranges_enumerate}@ 202302L // also in \libheader{ranges}, \libheader{version} #define @\defnlibxname{cpp_lib_ranges_find_last}@ 202207L // also in \libheader{algorithm} #define @\defnlibxname{cpp_lib_ranges_fold}@ 202207L // also in \libheader{algorithm} +#define @\defnlibxname{cpp_lib_ranges_generate_random}@ 202403L // also in \libheader{random} #define @\defnlibxname{cpp_lib_ranges_iota}@ 202202L // also in \libheader{numeric} #define @\defnlibxname{cpp_lib_ranges_join_with}@ 202202L // freestanding, also in \libheader{ranges} #define @\defnlibxname{cpp_lib_ranges_repeat}@ 202207L // freestanding, also in \libheader{ranges}