Namespaces
Variants

std:: 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 < 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イテレータや singular イテレータなど）のデクリメントを必要とする場合、動作は未定義です。

実装例

実装については 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)
イテレータをデクリメントする
(関数テンプレート)
2つのイテレータ間の距離を返す
(関数テンプレート)
(C++20)
イテレータを指定された距離または境界まで進める
(アルゴリズム関数オブジェクト)