std::advance

来自cppreference.com
< cpp‎ | iterator
 
 
迭代器库
迭代器概念
迭代器原语
算法概念与工具
间接可调用概念
常用算法要求
工具
迭代器适配器
流迭代器
迭代器定制点
迭代器操作
advance
(C++11)
(C++11)
范围访问
(C++11)(C++14)
(C++11)(C++14)
(C++17)(C++20)
(C++14)(C++14)
(C++14)(C++14)
(C++17)
(C++17)
 
在标头 <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 起)

增加给定的迭代器 itn 个元素的步长。

如果 n 为负,那么迭代器会自减。此时 InputIt 必须满足老式双向迭代器 (LegacyBidirectionalIterator) 的要求,否则行为未定义。

参数

it - 要前进的迭代器
n - it 要前进的元素数
类型要求
-
InputIt 必须符合老式输入迭代器 (LegacyInputIterator) 的要求。

返回值

(无)

复杂度

线性。

然而,如果 InputIt 额外满足老式随机访问迭代器 (LegacyRandomAccessIterator) 的要求,那么复杂度是常数。

注解

如果指定的自增或自减序列要求一个不可自增迭代器(例如尾后迭代器)自增,或不可自减迭代器(例如首迭代器或持有奇异值的迭代器)自减,那么行为未定义。

可能的实现

参阅 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

参阅

(C++11)
令迭代器自增
(函数模板)
(C++11)
令迭代器自减
(函数模板)
返回两个迭代器间的距离
(函数模板)
令迭代器前进给定的距离或到给定的边界
(niebloid)