Namespaces
Variants
Views
Actions

std::ranges::next

From cppreference.com
< cpp‎ | iterator
 
 
Iterator library
Iterator concepts
Iterator primitives
Algorithm concepts and utilities
Indirect callable concepts
Common algorithm requirements
(C++20)
(C++20)
(C++20)
Utilities
(C++20)

Iterator adaptors
Iterator customization points
Iterator operations
(C++11)    
(C++11)
ranges::next
(C++20)
Range access
(C++11)(C++14)
(C++14)(C++14)    
(C++11)(C++14)
(C++14)(C++14)    
(C++17)(C++20)
(C++17)
(C++17)
 
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.

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.
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.

[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

#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());
    }
}

[edit] See also

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