Namespaces
Variants

std::ranges:: advance

From cppreference.net
C++
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
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)
定义于头文件 <iterator>
调用签名
template < std:: input_or_output_iterator I >
constexpr void advance ( I & i, std:: iter_difference_t < I > n ) ;
(1) (C++20 起)
template < std:: input_or_output_iterator I, std:: sentinel_for < I > S >
constexpr void advance ( I & i, S bound ) ;
(2) (C++20 起)
template < std:: input_or_output_iterator I, std:: sentinel_for < I > S >
constexpr std:: iter_difference_t < I > advance ( I & i, std:: iter_difference_t < I > n, S bound ) ;
(3) (C++20 起)
1) 将给定迭代器 i 递增 n 次。
2) 递增给定迭代器 i 直到 i == bound 。
3) 对给定迭代器 i 递增 n 次，或直至 i == bound 条件满足为止（以先达到者为准）。

如果 n 为负数，迭代器将递减。此时 I 必须满足 std::bidirectional_iterator 概念，且当提供 bound 时 S 必须与 I 类型相同，否则行为未定义。

本页面描述的函数式实体是 算法函数对象 （非正式称为 niebloids ），即：

目录

参数

i - 待推进的迭代器
bound - 表示 i 所属范围的结束哨位
n - i 的最大递增次数

返回值

3) n 与实际遍历距离 i 之间的差值。

复杂度

线性。

然而，若 I 额外满足 std::random_access_iterator ，或 S 满足 std:: sized_sentinel_for < I > ，或 I 与 S 共同满足 std:: assignable_from < I & , S > ，则时间复杂度为常数。

注释

如果指定的递增或递减序列要求对不可递增的迭代器（如尾后迭代器）进行递增，或对不可递减的迭代器（如首前迭代器或奇异迭代器）进行递减，则行为未定义。

可能的实现 

struct advance_fn
{
    template<std::input_or_output_iterator I>
    constexpr void operator()(I& i, std::iter_difference_t<I> n) const
    {
        if constexpr (std::random_access_iterator<I>)
            i += n;
        else
        {
            while (n > 0)
            {
                --n;
                ++i;
            }
            if constexpr (std::bidirectional_iterator<I>)
            {
                while (n < 0)
                {
                    ++n;
                    --i;
                }
            }
        }
    }
    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
    constexpr void operator()(I& i, S bound) const
    {
        if constexpr (std::assignable_from<I&, S>)
            i = std::move(bound);
        else if constexpr (std::sized_sentinel_for<S, I>)
            (*this)(i, bound - i);
        else
            while (i != bound)
                ++i;
    }
    template<std::input_or_output_iterator I, std::sentinel_for<I> S>
    constexpr std::iter_difference_t<I>
    operator()(I& i, std::iter_difference_t<I> n, S bound) const
    {
        if constexpr (std::sized_sentinel_for<S, I>)
        {
            // std::abs 在 C++23 之前不是 constexpr
            auto abs = [](const std::iter_difference_t<I> x) { return x < 0 ? -x : x; };
            if (const auto dist = abs(n) - abs(bound - i); dist < 0)
            {
                (*this)(i, bound);
                return -dist;
            }
            (*this)(i, n);
            return 0;
        }
        else
        {
            while (n > 0 && i != bound)
            {
                --n;
                ++i;
            }
            if constexpr (std::bidirectional_iterator<I>)
            {
                while (n < 0 && i != bound)
                {
                    ++n;
                    --i;
                }
            }
            return n;
        }
    }
};
inline constexpr auto advance = advance_fn();

示例

运行此代码 
#include <iostream>
#include <iterator>
#include <vector>
int main()
{
    std::vector<int> v {3, 1, 4};
    auto vi = v.begin();
    std::ranges::advance(vi, 2);
    std::cout << "1) 值: " << *vi << '\n' << std::boolalpha;
    std::ranges::advance(vi, v.end());
    std::cout << "2) vi == v.end(): " << (vi == v.end()) << '\n';
    std::ranges::advance(vi, -3);
    std::cout << "3) 值: " << *vi << '\n';
    std::cout << "4) 差值: " << std::ranges::advance(vi, 2, v.end())
              << ", 值: " << *vi << '\n';
    std::cout << "5) 差值: " << std::ranges::advance(vi, 4, v.end())
              << ", vi == v.end(): " << (vi == v.end()) << '\n';
}

输出： 

1) 值: 4
2) vi == v.end(): true
3) 值: 3
4) 差值: 0, 值: 4
5) 差值: 3, vi == v.end(): true

参见

(C++20)
将迭代器递增给定距离或至边界
(算法函数对象)
(C++20)
将迭代器递减给定距离或至边界
(算法函数对象)
(C++20)
返回迭代器与哨位之间，或范围起始与末尾之间的距离
(算法函数对象)
按给定距离前移迭代器
(函数模板)