• Class / Function / Type

      std::
    • Header file

      <>
    • Other / All

    最終更新日時(UTC):
    が更新

    履歴 編集

    function template
    <iterator>

    std::advance

    namespace std {
      template <class InputIterator, class Distance>
      void advance(InputIterator& i, Distance n);               // C++03
    
      template <class InputIterator, class Distance>
      constexpr void advance(InputIterator& i, Distance n);     // C++17
    }
    

    概要

    イテレータをn回進める。

    next()prev()と違い、引数として渡されたイテレータへの参照を書き換える。

    要件

    双方向イテレータもしくはランダムアクセスイテレータの場合のみ、nが負数であることを許可する。

    効果

    イテレータへの参照in回進める(nが負数の場合は逆方向に進める)。

    戻り値

    なし

    計算量

    • 入力イテレータ、前方向イテレータ : n回のインクリメント
    • 双方向イテレータ: n回のインクリメント、もしくはデクリメント
    • ランダムアクセスイテレータ: O(1)

    #include <iostream>
    #include <iterator>
    #include <vector>
    
    int main()
    {
      std::vector<int> v = {3, 1, 4, 2, 5};
    
      decltype(v)::iterator i = v.begin();
      std::advance(i, 3); // イテレータiを3回進める
    
      std::cout << *i << std::endl;
    }
    

    出力

    2
    

    実装例

    // 入力イテレータ(or 前方向イテレータ)
    template <class InputIterator, class Distance>
    void advance_impl(InputIterator& i, Distance n, std::input_iterator_tag)
    {
      assert(n >= 0);
    
      for (; 0 < n; --n) { ++i; }
    }
    
    // 双方向イテレータ
    template <class BidirectionalIterator, class Distance>
    void advance_impl(BidirectionalIterator& i, Distance n, std::bidirectional_iterator_tag)
    {
      if (n > 0) {
        for (; 0 < n; --n) { ++i; }
      }
      else {
        for (; n < 0; ++n) { --i; }
      }
    }
    
    // ランダムアクセスイテレータ
    template <class RandomAccessIterator, class Distance>
    void advance_impl(RandomAccessIterator& i, Distance n, std::random_access_iterator_tag)
    {
      i += n;
    }
    
    template <class Iterator, class Distance>
    void advance(Iterator& i, Distance n)
    {
      advance_impl(i, n,
              typename std::iterator_traits<Iterator>::iterator_category());
              // イテレータのカテゴリごとに最適な実装を選択させる
    }
    

    関連項目

    名前 説明
    next() n回前方に進めたイテレータを返す
    prev() n回後方に進めたイテレータを返す

    参照