P0769R2 Add shift to <algorithm>

Author: jensmaurer

source/algorithms.tex

@@ -565,6 +565,26 @@
                  RandomAccessIterator last,
                  UniformRandomBitGenerator&& g);
 
+  // \ref{alg.shift}, shift
+  template<class ForwardIterator>
+    constexpr ForwardIterator
+      shift_left(ForwardIterator first, ForwardIterator last,
+                 typename iterator_traits<ForwardIterator>::difference_type n);
+  template<class ExecutionPolicy, class ForwardIterator>
+    ForwardIterator
+      shift_left(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}
+                 ForwardIterator first, ForwardIterator last,
+                 typename iterator_traits<ForwardIterator>::difference_type n);
+  template<class ForwardIterator>
+    ForwardIterator
+      shift_right(ForwardIterator first, ForwardIterator last,
+                  typename iterator_traits<ForwardIterator>::difference_type n);
+  template<class ExecutionPolicy, class ForwardIterator>
+    ForwardIterator
+      shift_right(ExecutionPolicy&& exec, // see \ref{algorithms.parallel.overloads}
+                  ForwardIterator first, ForwardIterator last,
+                  typename iterator_traits<ForwardIterator>::difference_type n);
+
   // \ref{alg.partitions}, partitions
   template<class InputIterator, class Predicate>
     constexpr bool is_partitioned(InputIterator first, InputIterator last, Predicate pred);
@@ -3526,6 +3546,89 @@
 
 \end{itemdescr}
 
+\rSec2[alg.shift]{Shift}
+
+\indexlibrary{\idxcode{shift_left}}%
+\begin{itemdecl}
+template<class ForwardIterator>
+  constexpr ForwardIterator
+    shift_left(ForwardIterator first, ForwardIterator last,
+               typename iterator_traits<ForwardIterator>::difference_type n);
+template<class ExecutionPolicy, class ForwardIterator>
+  ForwardIterator
+    shift_left(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
+               typename iterator_traits<ForwardIterator>::difference_type n);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\requires
+The type of \tcode{*first} shall satisfy
+the \tcode{MoveAssignable} requirements.
+
+\pnum
+\effects
+If \tcode{n <= 0} or \tcode{n >= last - first}, does nothing.
+Otherwise, moves the element
+from position \tcode{first + n + i}
+into position \tcode{first + i}
+for each non-negative integer \tcode{i < (last - first) - n}.
+In the first overload case, does so in order starting
+from \tcode{i = 0} and proceeding to \tcode{i = (last - first) - n - 1}.
+
+\pnum
+\returns
+\tcode{first + (last - first) - n}
+if \tcode{n} is positive and \tcode{n < last - first},
+otherwise \tcode{first} if \tcode{n} is positive, otherwise \tcode{last}.
+
+\pnum
+\complexity
+At most \tcode{(last - first) - n} assignments.
+\end{itemdescr}
+
+\indexlibrary{\idxcode{shift_right}}%
+\begin{itemdecl}
+template<class ForwardIterator>
+  ForwardIterator
+    shift_right(ForwardIterator first, ForwardIterator last,
+                typename iterator_traits<ForwardIterator>::difference_type n);
+template<class ExecutionPolicy, class ForwardIterator>
+  ForwardIterator
+    shift_right(ExecutionPolicy&& exec, ForwardIterator first, ForwardIterator last,
+                typename iterator_traits<ForwardIterator>::difference_type n);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\requires
+The type of \tcode{*first} shall satisfy
+the \tcode{MoveAssignable} requirements.
+\tcode{ForwardIterator} shall meet
+the \tcode{BidirectionalIterator} or \tcode{ValueSwappable} requirements.
+
+\pnum
+\effects
+If \tcode{n <= 0} or \tcode{n >= last - first}, does nothing.
+Otherwise, moves the element
+from position \tcode{first + i} into \tcode{position first + n + i}
+for each non-negative integer \tcode{i < (last - first) - n}.
+In the first overload case, if \tcode{ForwardIterator} satisfies
+the \tcode{BidirectionalIterator} requirements,
+does so in order starting
+from \tcode{i = (last - first) - n - 1} and proceeding to \tcode{i = 0}.
+
+\pnum
+\returns
+\tcode{first + n}
+if \tcode{n} is positive and \tcode{n < last - first},
+otherwise \tcode{last} if \tcode{n} is positive, otherwise \tcode{first}.
+
+\pnum
+\complexity
+At most \tcode{(last - first) - n} assignments or swaps.
+\end{itemdescr}
+
 \rSec1[alg.sorting]{Sorting and related operations}
 
 \pnum