cpp / latest / iterator / ranges / next.html /

std::ranges::next

Defined in header <iterator>
Call signature
template< std::input_or_output_iterator I >
constexpr I next( I i );
(1) (since C++20)
template< std::input_or_output_iterator I >
constexpr I next( I i, std::iter_difference_t<I> n );
(2) (since C++20)
template< std::input_or_output_iterator I, std::sentinel_for<I> S >
constexpr I next( I i, S bound );
(3) (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 );
(4) (since C++20)

Return the nth successor of iterator i.

The function-like entities described on this page are niebloids, that is:

In practice, they may be implemented as function objects, or with special compiler extensions.

Parameters

i - an iterator
n - number of elements to advance
bound - sentinel denoting the end of the range i points to

Return value

1) The successor of iterator i
2) The nth successor of iterator i
3) The first iterator equivalent to bound
4) The nth successor of iterator i, or the first iterator equivalent to bound, whichever is first.

Complexity

1) Constant.
2) Constant if I models std::random_access_iterator; otherwise linear.
3) Constant if I and S models both std::random_access_iterator<I> and std::sized_sentinel_for<S, I>, or if I and S models std::assignable_from<I&, S>; otherwise linear.
4) Constant if I and S models both std::random_access_iterator<I> and std::sized_sentinel_for<S, I>; otherwise linear.

Possible implementation

struct next_fn {
  template<std::input_or_output_iterator I>
  constexpr I operator()(I i) const
  {
    return ++i;
  }
 
  template<std::input_or_output_iterator I>
  constexpr I operator()(I i, std::iter_difference_t<I> n) const
  {
    ranges::advance(i, n);
    return i;
  }
 
  template<std::input_or_output_iterator I, std::sentinel_for<I> S>
  constexpr I operator()(I i, S bound) const
  {
    ranges::advance(i, bound);
    return i;
  }
 
  template<std::input_or_output_iterator I, std::sentinel_for<I> S>
  constexpr I operator()(I i, std::iter_difference_t<I> n, S bound) const
  {
    ranges::advance(i, n, bound);
    return i;
  }
};
 
inline constexpr auto next = next_fn();

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 <iomanip>
#include <iostream>
#include <iterator>
#include <vector>
 
int main() 
{
    std::cout << std::boolalpha;
    std::vector<int> v{ 3, 1, 4 };
    {
        auto n = std::ranges::next(v.begin());
        std::cout << *n << '\n';
    }
    {
        auto n = std::ranges::next(v.begin(), 2);
        std::cout << *n << '\n';
    }
    {
        auto n = std::ranges::next(v.begin(), v.end());
        std::cout << (n == v.end()) << '\n';
    }
    {
        auto n = std::ranges::next(v.begin(), 42, v.end());
        std::cout << (n == v.end()) << '\n';
    }
}

Output:

1
4
true
true

See also

(C++20)
decrement an iterator by a given distance or to a bound
(niebloid)
(C++20)
advances an iterator by given distance or to a given bound
(niebloid)
(C++11)
increment an iterator
(function template)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/iterator/ranges/next