P0220R1: algorithms (section 9).

Author: zygoloid

source/algorithms.tex

@@ -245,6 +245,7 @@
                         ForwardIterator2 first2, ForwardIterator2 last2,
                         BinaryPredicate pred);
 
+  // \ref{alg.search}, search:
   template<class ForwardIterator1, class ForwardIterator2>
     ForwardIterator1 search(
       ForwardIterator1 first1, ForwardIterator1 last1,
@@ -284,6 +285,10 @@
                              Size count, const T& value,
                              BinaryPredicate pred);
 
+  template <class ForwardIterator, class Searcher>
+    ForwardIterator search(ForwardIterator first, ForwardIterator last,
+                           const Searcher &searcher);
+
   // \ref{alg.modifying.operations}, modifying sequence operations:
   // \ref{alg.copy}, copy:
   template<class InputIterator, class OutputIterator>
@@ -512,6 +517,13 @@
       ForwardIterator first, ForwardIterator middle,
       ForwardIterator last, OutputIterator result);
 
+  // \ref{alg.random.sample}, sample:
+  template<class PopulationIterator, class SampleIterator,
+           class Distance, class UniformRandomNumberGenerator>
+    SampleIterator sample(PopulationIterator first, PopulationIterator last,
+                          SampleIterator out, Distance n,
+                          UniformRandomNumberGenerator&& g);
+
   // \ref{alg.random.shuffle}, shuffle:
   template<class RandomAccessIterator, class UniformRandomNumberGenerator>
     void shuffle(RandomAccessIterator first,
@@ -2081,6 +2093,24 @@
 applications of the corresponding predicate.
 \end{itemdescr}
 
+\indexlibrary{\idxcode{search}}%
+\begin{itemdecl}
+template<class ForwardIterator, class Searcher>
+  ForwardIterator search(ForwardIterator first, ForwardIterator last,
+                         const Searcher& searcher);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\effects
+Equivalent to \tcode{return searcher(first, last);}
+
+\pnum
+\remarks
+\tcode{Searcher} need not meet the \tcode{CopyConstructible} requirements.
+\end{itemdescr}
+
+
 \rSec1[alg.modifying.operations]{Mutating sequence operations}
 
 \rSec2[alg.copy]{Copy}
@@ -2930,14 +2960,78 @@
 assignments.
 \end{itemdescr}
 
+\rSec2[alg.random.sample]{Sample}
+
+\indexlibrary{\idxcode{sample}}%
+\begin{itemdecl}
+template<class PopulationIterator, class SampleIterator,
+         class Distance, class UniformRandomNumberGenerator>
+  SampleIterator sample(PopulationIterator first, PopulationIterator last,
+                        SampleIterator out, Distance n,
+                        UniformRandomNumberGenerator&& g);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\requires
+\begin{itemize}
+\item
+\tcode{PopulationIterator} shall meet the requirements of an \tcode{InputIterator} type.
+\item
+\tcode{SampleIterator} shall meet the requirements of an \tcode{OutputIterator} type.
+\item
+\tcode{SampleIterator} shall meet the additional requirements of a \tcode{RandomAccessIterator} type
+unless \tcode{PopulationIterator} meets the additional requirements of a \tcode{ForwardIterator} type.
+\item
+\tcode{PopulationIterator}'s value type shall be writable to \tcode{out}.
+\item
+\tcode{Distance} shall be an integer type.
+\item
+\tcode{UniformRandomNumberGenerator} shall meet the requirements of a uniform random number generator type (\ref{rand.req.urng})
+whose return type is convertible to \tcode{Distance}.
+\item
+\tcode{out} shall not be in the range \range{first}{last}.
+\end{itemize}
+
+\pnum
+\effects
+Copies \tcode{min(last - first, n)} elements (the \defn{sample})
+from \range{first}{last} (the \defn{population}) to \tcode{out}
+such that each possible sample has equal probability of appearance.
+\enternote
+Algorithms that obtain such effects include \term{selection sampling}
+and \term{reservoir sampling}.
+\exitnote
+
+\pnum
+\returns
+The end of the resulting sample range.
+
+\pnum
+\complexity
+O(\tcode{last - first}).
+
+\pnum
+\remarks
+\begin{itemize}
+\item
+Stable if and only if \tcode{PopulationIterator} meets the
+requirements of a \tcode{ForwardIterator} type.
+\item
+To the extent that the implementation of this function makes use of
+random numbers, the object \tcode{g} shall serve as the
+implementation's source of randomness.
+\end{itemize}
+\end{itemdescr}
+
 \rSec2[alg.random.shuffle]{Shuffle}
 
 \indexlibrary{\idxcode{shuffle}}%
 \begin{itemdecl}
 template<class RandomAccessIterator, class UniformRandomNumberGenerator>
   void shuffle(RandomAccessIterator first,
-                      RandomAccessIterator last,
-                      UniformRandomNumberGenerator&& g);
+               RandomAccessIterator last,
+               UniformRandomNumberGenerator&& g);
 \end{itemdecl}
 
 \begin{itemdescr}