std::ranges::next

Since C++20

Header: <iterator>

Return the nth successor of iterator i.

# Declarations

Call signature

template< std::input_or_output_iterator I >
constexpr I next( I i );

(since C++20)

template< std::input_or_output_iterator I >
constexpr I next( I i, std::iter_difference_t<I> n );

(since C++20)

template< std::input_or_output_iterator I, std::sentinel_for<I> S >
constexpr I next( I i, S bound );

(since C++20)

template< std::input_or_output_iterator I, std::sentinel_for<I> S >
constexpr I next( I i, std::iter_difference_t<I> n, S bound );

(since C++20)

# Parameters

# Notes

Although the expression ++x.begin() often compiles, it is not guaranteed to do so: x.begin() is an rvalue expression, and there is no 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, ++x.begin() does not compile, while ranges::next(x.begin()) does.

# Example

#include <cassert>
#include <iterator>
 
int main() 
{
    auto v = {3, 1, 4};
    {
        auto n = std::ranges::next(v.begin());
        assert(*n == 1);
    }
    {
        auto n = std::ranges::next(v.begin(), 2);
        assert(*n == 4);
    }
    {
        auto n = std::ranges::next(v.begin(), v.end());
        assert(n == v.end());
    }
    {
        auto n = std::ranges::next(v.begin(), 42, v.end());
        assert(n == v.end());
    }
}

# See also