std::next

template< class InputIt >
InputIt next( InputIt iter, typename std::iterator_traits
                                         <InputIt>::difference_type count = 1 );

Return the countth successor (or -countth predecessor if count is negative) of iterator iter.

Parameters

Return value

As described above.

Complexity

Linear in count.

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

Possible implementation

template<class InputIt>
constexpr // since C++17
InputIt next(InputIt iter,
             typename std::iterator_traits<InputIt>::difference_type count = 1)
{
    std::advance(iter, count);
    return iter;
}

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 LegacyInputIterator requirement that specifies that increment of an rvalue is guaranteed to work. In particular, when iterators are implemented as pointers or its operator++ is lvalue-ref-qualified, ++c.begin() does not compile, while std::next(c.begin()) does.

Example

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

int main()
{
    std::vector<int> v{4, 5, 6};
    
    auto it = v.begin();
    auto nx = std::next(it, 2);
    std::cout << *it << ' ' << *nx << '\n';
    
    it = v.end();
    nx = std::next(it, -2);
    std::cout << ' ' << *nx << '\n';
}

4 6
 5

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also