std::advance (3) - Linux Manuals

std::advance: std::advance

NAME

std::advance - std::advance

Synopsis


Defined in header <iterator>
template< class InputIt, class Distance > (until C++17)
void advance( InputIt& it, Distance n );
template< class InputIt, class Distance > (since C++17)
constexpr void advance( InputIt& it, Distance n );


Increments given iterator it by n elements.
If n is negative, the iterator is decremented. In this case, InputIt must meet the requirements of LegacyBidirectionalIterator, otherwise the behavior is undefined.

Parameters


it - iterator to be advanced
n - number of elements it should be advanced

Type requirements


-
InputIt must meet the requirements of LegacyInputIterator.

Return value


(none)

Complexity


Linear.
However, if InputIt additionally meets the requirements of LegacyRandomAccessIterator, complexity is constant.

Notes


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 the singular iterator) is decremented.

Example


// Run this code


  #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 << '\n';
  }

Output:


  4

See also


next increment an iterator
         (function template)
(C++11)
         returns the distance between two iterators
distance (function template)