| Iterator concepts | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Iterator primitives | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Algorithm concepts and utilities | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Indirect callable concepts | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Common algorithm requirements | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Utilities | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Iterator adaptors | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <iterator> | ||
template<class InputIt,class Distance> void advance( InputIt& it, Distance n); | (until C++17) | |
template<class InputIt,class Distance> constexprvoid advance( InputIt& it, Distance n); | (since C++17) | |
Increments given iteratorit byn elements.
Ifn is negative, the iterator is decremented. In this case,InputIt must meet the requirements ofLegacyBidirectionalIterator, otherwise the behavior is undefined.
Contents |
| it | - | iterator to be advanced |
| n | - | number of elementsit should be advanced |
| Type requirements | ||
-InputIt must meet the requirements ofLegacyInputIterator. | ||
(none)
Linear.
However, ifInputIt additionally meets the requirements ofLegacyRandomAccessIterator, complexity is constant.
The behavior is undefined if the specified sequence of increments or decrements would require that a non-incrementable iterator (such as the past-the-end iterator) is incremented, or that a non-decrementable iterator (such as the front iterator or thesingular iterator) is decremented.
See also the implementations inlibstdc++ andlibc++.
| Non-constexpr version |
|---|
namespace detail{template<class It>void do_advance(It& it,typenamestd::iterator_traits<It>::difference_type n,std::input_iterator_tag){while(n>0){--n;++it;}} template<class It>void do_advance(It& it,typenamestd::iterator_traits<It>::difference_type n,std::bidirectional_iterator_tag){while(n>0){--n;++it;}while(n<0){++n;--it;}} template<class It>void do_advance(It& it,typenamestd::iterator_traits<It>::difference_type n,std::random_access_iterator_tag){ it+= n;}}// namespace detail template<class It,class Distance>void advance(It& it, Distance n){ detail::do_advance(it,typenamestd::iterator_traits<It>::difference_type(n),typenamestd::iterator_traits<It>::iterator_category());} |
| constexpr version |
template<class It,class Distance>constexprvoid advance(It& it, Distance n){using category=typenamestd::iterator_traits<It>::iterator_category; static_assert(std::is_base_of_v<std::input_iterator_tag, category>); auto dist=typenamestd::iterator_traits<It>::difference_type(n);ifconstexpr(std::is_base_of_v<std::random_access_iterator_tag, category>) it+= dist;else{while(dist>0){--dist;++it;}ifconstexpr(std::is_base_of_v<std::bidirectional_iterator_tag, category>)while(dist<0){++dist;--it;}}} |
#include <iostream>#include <iterator>#include <vector> int main(){std::vector<int> v{3,1,4}; auto vi= v.begin(); std::advance(vi,2);std::cout<<*vi<<' '; vi= v.end(); std::advance(vi,-2);std::cout<<*vi<<'\n';}
Output:
4 1
(C++11) | increment an iterator (function template)[edit] |
(C++11) | decrement an iterator (function template)[edit] |
| returns the distance between two iterators (function template)[edit] | |
(C++20) | advances an iterator by given distance or to a given bound (algorithm function object)[edit] |
