| 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 algorithm function objects (informally known as niebloids), that is:
- Explicit template argument lists cannot be specified when calling any of them.
- None of them are visible to argument-dependent lookup.
- When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.
Parameters
| i | - | an iterator |
| n | - | number of elements to advance |
| bound | - | sentinel denoting the end of the range i points to
|
Return value
i.nth successor of iterator i.bound.nth successor of iterator i, or the first iterator equivalent to bound, whichever is first.Complexity
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.I and S models both std::random_access_iterator<I> and std::sized_sentinel_for<S, I>; otherwise linear.Possible implementation
|
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
| (C++20) |
decrement an iterator by a given distance or to a bound (algorithm function object) |
| (C++20) |
advances an iterator by given distance or to a given bound (algorithm function object) |
| (C++11) |
increment an iterator (function template) |
Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.