std::advance

定义于头文件 `<iterator>`
template< class InputIt, class Distance > void advance( InputIt& it, Distance n );		(直到 C++17)
template< class InputIt, class Distance > constexpr void advance( InputIt& it, Distance n );		(自 C++17 起)

将给定的迭代器 it 递增 n 个元素。

如果 n 为负，则迭代器递减。在这种情况下，InputIt 必须满足 LegacyBidirectionalIterator 的要求，否则行为未定义。

[编辑] 参数

it	-	要递增的迭代器
n	-	it 应该递增的元素数量
类型要求
- `InputIt` 必须满足 LegacyInputIterator 的要求。

[编辑] 返回值

（无）

[编辑] 复杂度

线性。

然而，如果 InputIt 额外满足 LegacyRandomAccessIterator 的要求，则复杂度为常数。

[编辑] 注解

如果指定的递增或递减序列需要递增不可递增的迭代器（例如，past-the-end 迭代器），或者递减不可递减的迭代器（例如，front 迭代器或奇异迭代器），则行为未定义。

[编辑] 可能的实现

另请参见 libstdc++ 和 libc++ 中的实现。

非 constexpr 版本

namespace detail
{
    template<class It>
    void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                    std::input_iterator_tag)
    {
        while (n > 0)
        {
            --n;
            ++it;
        }
    }
 
    template<class It>
    void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                    std::bidirectional_iterator_tag)
    {
        while (n > 0)
        {
            --n;
            ++it;
        }
        while (n < 0)
        {
            ++n;
            --it;
        }
    }
 
    template<class It>
    void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                    std::random_access_iterator_tag)
    {
        it += n;
    }
} // namespace detail
 
template<class It, class Distance>
void advance(It& it, Distance n)
{
    detail::do_advance(it, typename std::iterator_traits<It>::difference_type(n),
                       typename std::iterator_traits<It>::iterator_category());
}

constexpr 版本

template<class It, class Distance>
constexpr void advance(It& it, Distance n)
{
    using category = typename std::iterator_traits<It>::iterator_category;
    static_assert(std::is_base_of_v<std::input_iterator_tag, category>);
 
    auto dist = typename std::iterator_traits<It>::difference_type(n);
    if constexpr (std::is_base_of_v<std::random_access_iterator_tag, category>)
        it += dist;
    else
    {
        while (dist > 0)
        {
            --dist;
            ++it;
        }
        if constexpr (std::is_base_of_v<std::bidirectional_iterator_tag, category>)
            while (dist < 0)
            {
                ++dist;
                --it;
            }
    }
}

[编辑] 示例

运行此代码

#include <iostream>
#include <iterator>
#include <vector>
 
int main() 
{
    std::vector<int> v{3, 1, 4};
 
    auto vi = v.begin();
    std::advance(vi, 2);
    std::cout << *vi << ' ';
 
    vi = v.end();
    std::advance(vi, -2);
    std::cout << *vi << '\n';
}

输出

4 1

[编辑] 参见

next (C++11)	递增迭代器（函数模板） [编辑]
prev (C++11)	递减迭代器（函数模板） [编辑]
distance	返回两个迭代器之间的距离（函数模板） [编辑]
ranges::advance (C++20)	将迭代器按给定距离或给定边界推进（算法函数对象）[编辑]

编译器支持
独立和宿主
语言
标准库
标准库头文件
具名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

cppreference.cn

命名空间

变体

视图

操作