27 Algorithms library [algorithms]

27.7 Mutating sequence operations [alg.modifying.operations]

27.7.14 Shift [alg.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, ForwardIterator first, ForwardIterator last, typename iterator_traits<ForwardIterator>::difference_type n); template<permutable I, sentinel_­for<I> S> constexpr subrange<I> ranges::shift_left(I first, S last, iter_difference_t<I> n); template<forward_­range R> requires permutable<iterator_t<R>> constexpr borrowed_subrange_t<R> ranges::shift_left(R&& r, range_difference_t<R> n)
Preconditions: n >= 0 is true.
For the overloads in namespace std, the type of *first meets the Cpp17MoveAssignable requirements.
Effects: If n == 0 or n >= last - first, does nothing.
Otherwise, moves the element from position first + n + i into position first + i for each non-negative integer i < (last - first) - n.
For the overloads without an ExecutionPolicy template parameter, does so in order starting from i = 0 and proceeding to i = (last - first) - n - 1.
Returns: Let NEW_­LAST be first + (last - first - n) if n < last - first, otherwise first.
  • NEW_­LAST for the overloads in namespace std.
  • {first, NEW_­LAST} for the overloads in namespace ranges.
Complexity: At most (last - first) - n assignments.
template<class ForwardIterator> constexpr 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); template<permutable I, sentinel_­for<I> S> constexpr subrange<I> ranges::shift_right(I first, S last, iter_difference_t<I> n); template<forward_­range R> requires permutable<iterator_t<R>> constexpr borrowed_subrange_t<R> ranges::shift_right(R&& r, range_difference_t<R> n);
Preconditions: n >= 0 is true.
For the overloads in namespace std, the type of *first meets the Cpp17MoveAssignable requirements, and ForwardIterator meets the Cpp17BidirectionalIterator requirements ([bidirectional.iterators]) or the Cpp17ValueSwappable requirements.
Effects: If n == 0 or n >= last - first, does nothing.
Otherwise, moves the element from position first + i into position first + n + i for each non-negative integer i < (last - first) - n.
Does so in order starting from i = (last - first) - n - 1 and proceeding to i = 0 if:
  • for the overload in namespace std without an ExecutionPolicy template parameter, ForwardIterator meets the Cpp17BidirectionalIterator requirements,
  • for the overloads in namespace ranges, I models bidirectional_­iterator.
Returns: Let NEW_­FIRST be first + n if n < last - first, otherwise last.
  • NEW_­FIRST for the overloads in namespace std.
  • {NEW_­FIRST, last} for the overloads in namespace ranges.
Complexity: At most (last - first) - n assignments or swaps.