std::ranges::next
From cppreference.com
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Iterator library
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)(C++20)(C++20)(C++23)(C++20)(C++20)
(deprecated in C++17)
(C++20)
(C++20)
(C++20)(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++14)
(C++11)
(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++23)
(C++11)(C++14)
(C++14)(C++14)
Defined in header
<iterator>
Call signature
template< std::input_or_output_iterator I >
constexpr I next( I i );
(1)
(since C++20)
constexpr I next( I i );
template< std::input_or_output_iterator I >
constexpr I next( I i, std::iter_difference_t <I> n );
(2)
(since C++20)
constexpr I next( I i, std::iter_difference_t <I> n );
template< std::input_or_output_iterator I, std::sentinel_for <I> S >
constexpr I next( I i, S bound );
(3)
(since C++20)
constexpr I next( I i, S bound );
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)
constexpr I next( I i, std::iter_difference_t <I> n, S bound );
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.
Contents
[edit] Parameters
i
-
an iterator
n
-
number of elements to advance
bound
-
sentinel denoting the end of the range i points to
[edit] 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.
[edit] Complexity
1) Constant.
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.[edit] Possible implementation
struct next_fn { template<std::input_or_output_iterator I> constexpr I operator()(I i) const { ++i; 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();
[edit] 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.
[edit] Example
Run this code
#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()); } }