std::ranges::next

Определено в заголовочном файле `<iterator>`
Вызов функции
template< std::input_or_output_iterator I > constexpr I next( I i );	(1)	(с C++20)
template< std::input_or_output_iterator I > constexpr I next( I i, std::iter_difference_t<I> n );	(2)	(с C++20)
template< std::input_or_output_iterator I, std::sentinel_for<I> S > constexpr I next( I i, S bound );	(3)	(с 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)	(с C++20)

Возвращает n-й преемник итератора i.

Функциональные сущности, описанные на этой странице, являются неблоидами, то есть:

Явные списки шаблонных аргументов не могут быть указаны при их вызове.
Ни один из них не виден для поиска зависимого от аргументов.
Если какой-либо из них найден обычным поиском без квалификатора в качестве имени слева от оператора вызова функции, поиск зависимый от аргументов запрещён.

На практике они могут быть реализованы как объекты-функции или с помощью специальных расширений компилятора.

Параметры

i	-	итератор
n	-	число элементов для продвижения
bound	-	контрольная точка, обозначающая конец диапазона, к которому указывает `i`

Значение возврата

1) Преемник итератора i.

2) n-й преемник итератора i.

3) Первый итератор, эквивалентный bound.

4) n-й преемник итератора i, или первый итератор, эквивалентный bound, в зависимости от того, что встретится раньше.

Сложность

1) Постоянная.

2) Постоянная, если I моделирует std::random_access_iterator; в противном случае линейная.

3) Постоянная, если I и S моделируют и std::random_access_iterator<I>, и std::sized_sentinel_for<S, I>, или если I и S моделируют std::assignable_from<I&, S>; в противном случае линейная.

4) Постоянная, если I и S моделируют и std::random_access_iterator<I>, и std::sized_sentinel_for<S, I>; в противном случае линейная.

Возможная реализация

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

Примечания

Хотя выражение ++x.begin() часто компилируется, это не гарантируется: x.begin() является выражением rvalue, и нет требования, которое гарантирует работу инкремента rvalue. В частности, когда итераторы реализуются как указатели или их operator++ является квалифицированной ссылкой lvalue, ++x.begin() не компилируется, в то время как ranges::next(x.begin()) компилируется.

Пример

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

См. также

ranges::prev (C++20)	уменьшить итератор на заданное расстояние или до контрольной точки (неблоид)
ranges::advance (C++20)	продвигает итератор на заданное расстояние или до заданной контрольной точки (неблоид)
next (C++11)	инкрементировать итератор (шаблон функции)

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