Defined in header
template<classForwardIt>constexprForwardItshift_left(ForwardItfirst,ForwardItlast,typenamestd::iterator_traits<ForwardIt>::difference_typecount); (1) (since C++20)template<classForwardIt>constexprForwardItshift_right(ForwardItfirst,ForwardItlast,typenamestd::iterator_traits<ForwardIt>::difference_typecount); (2) (since C++20)template<classExecutionPolicy,classForwardIt>ForwardItshift_left(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,typenamestd::iterator_traits<ForwardIt>::difference_typecount); (3) (since C++20)template<classExecutionPolicy,classForwardIt>ForwardItshift_right(ExecutionPolicy&&policy,ForwardItfirst,ForwardItlast,typenamestd::iterator_traits<ForwardIt>::difference_typecount); (4) (since C++20)Shifts the elements in the target range [first, last) by count positions. If count is not less than std::distance(first,last), does nothing.
1)shift_left shifts the elements towards the beginning of the target range.
For every integer i starting from 0 to std::distance(first,last)-count-1, moves the element originally at position std::next(first,count+i) to position std::next(first,i).
2)shift_right shifts the elements towards the end of the target range.
For every integer i starting from std::distance(first,last)-count-1 to 0, moves the element originally at position std::next(first,i) to position std::next(first,count+i).
If ForwardIt does not meet the requirements of
, the shifting process is performed by swapping elements instead, the swap order is unspecified.
3,4) Same as (1,2), but the move order is determined by policy.
These overloads participate in overload resolution only if std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true.
If any of the following conditions is satisfied, the behavior is undefined:
count>=0 is not true.
The type of *first is not
.
For shift_right, ForwardIt is neither
nor
.
Parameters
first, last - the pair of iterators defining the target
count - the shift offset policy - the
to use Type requirements -ForwardIt must meet the requirements of
. Return value
Let size be the std::distance(first,last):
1,3)std::next(first,std::max(size-count,0))
2,4)std::next(first,std::min(size,count))
Complexity
Given N as std::distance(first,last):
1,3) At most max(N-count,0) assignments.
2,4) At most max(N-count,0) assignment or swaps.
Exceptions
3,4) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Notes
macroValueStdFeature
(C++20)
and
Example
Run this code
importstd;structS{intvalue{0};boolspecified_state{true};S(intv=0):value{v}{}S(constS&rhs)=default;S(S&&rhs){*this=std::move(rhs);}S&operator=(constS&rhs)=default;S&operator=(S&&rhs){if(this!=&rhs){value=rhs.value;specified_state=rhs.specified_state;rhs.specified_state=false;}return*this;}};template<typenameT>std::ostream&operator<<(std::ostream&os,conststd::vector<T>&v){for(constauto&s:v){ifconstexpr(std::is_same_v<T,S>)s.specified_state?os<<s.value<<' ':os<<". ";elseifconstexpr(std::is_same_v<T,std::string>)os<<(s.empty()?".":s)<<' ';elseos<<s<<' ';}returnos;}template<intwidth=16>voidprintln(auto&&...s){std::cout<<std::left;std::stringstreamss;((ss.str(""),ss<<s,std::cout<<std::setw(width)<<ss.str()),...);std::cout<<'\n';}intmain(){std::vector<S>a{1,2,3,4,5,6,7};std::vector<int>b{1,2,3,4,5,6,7};std::vector<std::string>c{"α","β","γ","δ","ε","ζ","η"};println("vector<S>","vector<int>","vector<string>");println(a,b,c);std::shift_left(begin(a),end(a),3);std::shift_left(begin(b),end(b),3);std::shift_left(begin(c),end(c),3);println(a,b,c);std::shift_right(begin(a),end(a),2);std::shift_right(begin(b),end(b),2);std::shift_right(begin(c),end(c),2);println(a,b,c);std::shift_left(begin(a),end(a),8);// has no effect: n >= last - firststd::shift_left(begin(b),end(b),8);// dittostd::shift_left(begin(c),end(c),8);// dittoprintln(a,b,c);// std::shift_left(begin(a), end(a), -3); // UB, e.g. segfault}Possible output:
vector<S> vector<int> vector<string> 1 2 3 4 5 6 7 1 2 3 4 5 6 7 α β γ δ ε ζ η 4 5 6 7 . . . 4 5 6 7 5 6 7 δ ε ζ η . . . . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . . . 4 5 6 7 . 4 5 4 5 6 7 5 . . δ ε ζ η . See also
ranges::shift_leftranges::shift_right
(C++23)(C++23)
shifts elements in a range
(algorithm function object)
(C++11)
moves a range of elements to a new location
(function template & algorithm function object)
(C++20)
(C++11)
moves a range of elements to a new location in backwards order
(function template & algorithm function object)
(C++20)
rotates the order of elements in a range
(function template & algorithm function object)
(C++20)