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-ref, ++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/cpp/iterator/ranges/next