std::next (3) - Linux Man Pages

std::next: std::next

NAME

std::next - std::next

Synopsis


Defined in header <iterator>
template< class ForwardIt >
ForwardIt next( (since C++11)
ForwardIt it, (until C++17)
typename std::iterator_traits<ForwardIt>::difference_type n = 1 );
template< class InputIt >
constexpr InputIt next( (since C++17)
InputIt it,
typename std::iterator_traits<InputIt>::difference_type n = 1 );


Return the nth successor of iterator it.

Parameters


it - an iterator
n - number of elements to advance

Type requirements


-
ForwardIt must meet the requirements of LegacyForwardIterator.
-
InputIt must meet the requirements of LegacyInputIterator.

Return value


The nth successor of iterator it.

Complexity


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

Possible implementation


  template<class ForwardIt>
  ForwardIt next(ForwardIt it,
                 typename std::iterator_traits<ForwardIt>::difference_type n = 1)
  {
      std::advance(it, n);
      return it;
  }

Notes


Although the expression ++c.begin() often compiles, it is not guaranteed to do so: c.begin() is an rvalue expression, and there is no LegacyBidirectionalIterator requirement that specifies that increment of an rvalue is guaranteed to work. In particular, when iterators are implemented as pointers, ++c.begin() does not compile, while std::next(c.begin()) does.

Example


// Run this code


  #include <iostream>
  #include <iterator>
  #include <vector>


  int main()
  {
      std::vector<int> v{ 3, 1, 4 };


      auto it = v.begin();


      auto nx = std::next(it, 2);


      std::cout << *it << ' ' << *nx << '\n';
  }

Output:


  3 4

See also


prev decrement an iterator
        (function template)
(C++11)
        advances an iterator by given distance
advance (function template)