Namespaces
Variants

Iterator library

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)

イテレータは ポインタ を一般化したものであり、C++プログラムが様々なデータ構造（例えば コンテナ および レンジ (C++20以降) ）を統一的な方法で扱えるようにします。イテレータライブラリは、イテレータの定義とともに、イテレータ特性、アダプタ、およびユーティリティ関数を提供します。

イテレータはポインタの抽象化であるため、その意味論はC++におけるポインタの意味論の大部分を一般化したものです。これにより、 function template を取るすべての関数テンプレートが通常のポインタでも同様に機能することが保証されます。

目次

翻訳の注意点： - 「Contents」を「目次」に翻訳 - C++専門用語（Iterator categories, Definitions, Ranges, Iterator conceptsなど）は原文のまま保持 - HTMLタグ、属性、数値は一切変更せず - 技術文書としての正確性と専門性を維持 - 括弧内のバージョン情報（since C++20など）は原文のまま保持

イテレータカテゴリ

イテレータには 5種類 (C++17まで) 6種類 (C++17以降) 存在します： LegacyInputIterator 、 LegacyOutputIterator 、 LegacyForwardIterator 、 LegacyBidirectionalIterator 、 LegacyRandomAccessIterator 、および LegacyContiguousIterator (C++17以降) 。（最も基本的なイテレータについては LegacyIterator も参照してください。）

イテレータの各カテゴリは、特定の型によって定義されるのではなく、それに対して実行可能な操作によって定義されます。この定義は、必要な操作をサポートする任意の型がイテレータとして使用できることを意味します。例えば、ポインタは LegacyRandomAccessIterator に必要なすべての操作をサポートしているため、 LegacyRandomAccessIterator が期待される場所ではどこでもポインタを使用できます。

すべてのイテレータカテゴリ（ LegacyOutputIterator を除く）は階層構造で整理でき、より強力なイテレータカテゴリ（例： LegacyRandomAccessIterator ）は、より弱いカテゴリ（例： LegacyInputIterator ）の操作をサポートします。イテレータがこれらのカテゴリのいずれかに該当し、かつ LegacyOutputIterator の要件も満たす場合、それは ミュータブル イテレータと呼ばれ、 入力と出力の両方 をサポートします。非ミュータブルなイテレータは コンスタント イテレータと呼ばれます。

イテレータは、イテレータカテゴリ要件を満たすために提供されるすべての操作が constexpr関数 である場合、 constexpr イテレータと呼ばれます。

(C++20以降)
イテレータカテゴリ 操作とストレージ要件
書き込み 読み取り インクリメント デクリメント ランダム
アクセス 		連続
ストレージ
複数パス
なし 		複数パス
あり
LegacyIterator 必須
LegacyOutputIterator 必須 必須
LegacyInputIterator
（書き込み操作をサポートする場合はmutable） 		必須 必須
LegacyForwardIterator
（ LegacyInputIterator も満たす） 		必須 必須 必須
LegacyBidirectionalIterator
（ LegacyForwardIterator も満たす） 		必須 必須 必須 必須
LegacyRandomAccessIterator
（ LegacyBidirectionalIterator も満たす） 		必須 必須 必須 必須 必須
LegacyContiguousIterator [1]
（ LegacyRandomAccessIterator も満たす） 		必須 必須 必須 必須 必須 必須
  1. ↑ LegacyContiguousIterator カテゴリはC++17で初めて正式に規定されたが、 std::vector 、 std::basic_string 、 std::array 、および std::valarray のイテレータ、ならびにC配列へのポインタは、C++17以前のコードではしばしば別個のカテゴリとして扱われていた。

注記: 上記の表の行に記載された必要な操作をサポートする型が、必ずしも対応するカテゴリに該当するとは限りません。完全な要件リストについてはカテゴリページを参照してください。

定義

型と書き込み可能性

入力イテレータ i は式 * i をサポートし、これはある オブジェクト型 T の値を返します。この型はイテレータの 値型 と呼ばれます。

出力イテレータ i は、イテレータに 書き込み可能 (C++20まで) indirectly_writable (C++20以降) な型の空でない集合を持つ。そのような各型 T について、式 * i = o は有効であり、ここで o は型 T の値である。

等価性が定義されているすべてのイテレータ型 X に対して (C++20まで) 、対応する符号付き 整数型 (C++20まで) 整数様型 (C++20以降) が存在し、これはイテレータの 差分行型 と呼ばれます。

デリファレンス可能性と有効性

通常の array へのポインタが配列の最後の要素を超えた位置を指すポインタ値を保証するのと同様に、任意のイテレータ型についても、対応するシーケンスの最後の要素を超えた位置を指すイテレータ値が存在します。このような値は past-the-end 値と呼ばれます。

イテレータの値 i に対して式 * i が定義されている場合、その値を デリファレンス可能 と呼びます。 標準ライブラリ は、末尾以降の値がデリファレンス可能であることを決して仮定しません。

イテレータは、いずれのシーケンスにも関連付けられていない singular 値を持つこともできます。singular値に対するほとんどの式の結果は未定義です。例外は以下のもののみです：

  • 特異値を持つイテレータへの非特異値の代入、
  • 特異値を持つイテレータの破棄、および、
  • DefaultConstructible 要件を満たすイテレータについて、 値初期化 されたイテレータをコピー操作 またはムーブ操作 (C++11以降) のソースとして使用すること。

これらのケースでは、特異値は他の値と同じ方法で上書きされます。逆参照可能な値は常に非特異です。

無効なイテレータは、singular（特異）である可能性のあるイテレータです。

レンジ

標準ライブラリのアルゴリズムテンプレートの多くは、データ構造を操作する際に範囲を使用するインターフェースを備えています。

イテレータ j は、イテレータ i から 到達可能 であると呼ばれるのは、 ++ i 式を有限回適用することで i == j が成立する場合に限ります。 j が i から到達可能である場合、それらは同じシーケンスの要素を参照します。

範囲 は、計算の開始と終了を指定する2つのイテレータのペアです。範囲 [ i , i ) は空の範囲です。一般的に、範囲 [ i , j ) は、 i が指す要素から始まり、 j が指す要素を含まないまでのデータ構造内の要素を参照します。

範囲 [ i , j ) が 有効 であるのは、 j が i から到達可能である場合に限ります。

(C++20まで)

range は以下のいずれかで表記できる：

  • [ i , s ) ：イテレータ i と sentinel s で計算の開始と終了を指定する（ i と s は異なる型を持てる）、または
  • i + [ ​ 0 ​ , n ) ：イテレータ i とカウント n で計算が適用される開始位置と要素数を指定する。
Iterator-sentinel range

範囲を表すイテレータとセンチネルは比較可能である。 [ i , s ) は i == s の場合空である。それ以外の場合、 [ i , s ) はデータ構造内の要素を参照し、 i が指す要素から始まり、 j == s となる最初のイテレータ j が指す要素（存在する場合）を含まない。

センチネル s がイテレータ i から reachable であるとは、 ++ i 式の有限回の適用によって i == s となる場合に限る。

s が i からreachableである場合、 [ i , s ) は valid な範囲を表す。

Counted range

counted range i + [ ​ 0 ​ , n ) は n == 0 の場合空である。それ以外の場合、 i + [ ​ 0 ​ , n ) はデータ構造内の n 個の要素を参照し、 i が指す要素から始まり、 n 回の ++ i 適用結果が指す要素（存在する場合）を含まない。

counted range i + [ ​ 0 ​ , n ) が valid であるのは以下の場合に限る：

  • n == 0 ；または
  • 以下の条件がすべて満たされる場合：
    • n が正の値、
    • i がデリファレンス可能、かつ
    • ++ i + [ ​ 0 ​ , -- n ) がvalidである。
(C++20以降)

標準ライブラリの関数を無効な範囲に適用した結果は未定義です。

イテレータコンセプト (C++20以降)

C++17イテレータとは異なる concepts に基づく新しいイテレータシステム。基本的な分類体系は類似しているが、個々のイテレータカテゴリに対する要件は多少異なる。

namespace std で定義
(C++20)
* 演算子を適用することで間接的に読み取り可能な型であることを指定する
(コンセプト)
(C++20)
イテレータの参照先オブジェクトに値を書き込めることを指定する
(コンセプト)
(C++20)
semiregular 型が前置および後置インクリメント演算子でインクリメント可能であることを指定する
(コンセプト)
(C++20)
weakly_incrementable 型に対するインクリメント操作が 等価性を保存する こと、およびその型が equality_comparable であることを指定する
(コンセプト)
(C++20) (C++20)
型が（符号付き）整数型のように振る舞うことを指定する
( 説明専用コンセプト* )
(C++20)
型のオブジェクトがインクリメントおよびデリファレンス可能であることを指定する
(コンセプト)
(C++20)
型が input_or_output_iterator 型に対するセンチネルであることを指定する
(コンセプト)
(C++20)
イテレータとセンチネルに - 演算子を適用して定数時間でそれらの差を計算できることを指定する
(コンセプト)
(C++20)
型が入力イテレータであること、つまり参照する値を読み取ることができ、前置および後置インクリメントが可能であることを指定する
(コンセプト)
(C++20)
型が与えられた値型に対する出力イテレータであること、つまりその型の値を書き込むことができ、前置および後置インクリメントが可能であることを指定する
(コンセプト)
(C++20)
input_iterator が前方イテレータであり、等値比較とマルチパスをサポートすることを指定する
(コンセプト)
(C++20)
forward_iterator が双方向イテレータであり、後方への移動をサポートすることを指定する
(コンセプト)
(C++20)
bidirectional_iterator がランダムアクセスイテレータであり、定数時間での前進と添字演算をサポートすることを指定する
(コンセプト)
(C++20)
random_access_iterator が隣接イテレータであり、メモリ上で連続した要素を参照することを指定する
(コンセプト)

イテレータ関連型 (C++20以降)

namespace std で定義
(C++20)
weakly_incrementable 型の差型を計算する
(クラステンプレート)
(C++20)
indirectly_readable 型の値型を計算する
(クラステンプレート)
(C++20) (C++20) (C++23) (C++20) (C++20) (C++20)
イテレータの関連型を計算する
(エイリアステンプレート)

イテレータ基本要素

イテレータのプロパティに対する統一インターフェースを提供する
(クラステンプレート)
(C++20)
イテレータカテゴリを示すために使用される空のクラス型
(クラス)
(C++17で非推奨)
単純なイテレータのための必須型の定義を容易にする基底クラス
(クラステンプレート)

イテレータカスタマイゼーションポイント (C++20以降)

namespace std::ranges で定義
(C++20)
オブジェクトを間接参照した結果を、関連付けられた右辺値参照型にキャストする
(カスタマイゼーションポイントオブジェクト)
(C++20)
2つの間接参照可能なオブジェクトが参照する値を交換する
(カスタマイゼーションポイントオブジェクト)

アルゴリズムコンセプトとユーティリティ (C++20以降)

共通のアルゴリズム操作を制約することを容易にするために設計された、一連のコンセプトと関連するユーティリティテンプレートのセット。

定義済みヘッダー <iterator>
名前空間 std で定義
間接呼び出し可能コンセプト
(C++20) (C++20)
呼び出し可能型が indirectly_readable 型の間接参照結果で呼び出し可能であることを指定する
(コンセプト)
(C++20)
呼び出し可能型が、間接参照可能な indirectly_readable 型の結果で呼び出されたときに、 predicate を満たすことを指定する
(コンセプト)
(C++20)
呼び出し可能な型が、2つの indirectly_readable 型の間接参照結果で呼び出されたときに、 predicate を満たすことを指定する
(concept)
(C++20)
呼び出し可能な型が、2つの indirectly_readable 型の間接参照結果で呼び出されたときに、 equivalence_relation を満たすことを指定する
(コンセプト)
(C++20)
呼び出し可能型が、二つの indirectly_readable 型の間接参照結果で呼び出されたときに、 strict_weak_order を満たすことを指定する
(コンセプト)
共通アルゴリズム要件
(C++20)
indirectly_readable 型から indirectly_writable 型へ値がムーブ可能であることを指定する
(コンセプト)
(C++20)
indirectly_readable 型から indirectly_writable 型へ値を移動可能であり、その移動が中間オブジェクトを介して実行されうることを指定する
(コンセプト)
(C++20)
indirectly_readable 型から indirectly_writable 型へ値がコピー可能であることを指定する
(コンセプト)
(C++20)
indirectly_readable 型から indirectly_writable 型へ値をコピー可能であり、そのコピーが中間オブジェクトを介して実行され得ることを指定する
(コンセプト)
(C++20)
2つの indirectly_readable 型によって参照される値を交換できることを指定する
(コンセプト)
(C++20)
2つの indirectly_readable 型によって参照される値を比較できることを指定する
(コンセプト)
(C++20)
要素をその場で並べ替えるアルゴリズムの共通要件を指定する
(コンセプト)
(C++20)
ソート済みシーケンスを要素のコピーによって出力シーケンスにマージするアルゴリズムの要件を指定する
(concept)
(C++20)
シーケンスを順序付けられたシーケンスに並べ替えるアルゴリズムの共通要件を指定する
(コンセプト)
ユーティリティ
(C++20)
いくつかの indirectly_readable 型の間接参照結果に対して呼び出し可能オブジェクトを呼び出した結果を計算する
(エイリアステンプレート)
(C++20)
射影を受け入れるアルゴリズムの制約を指定するためのヘルパーテンプレート
(エイリアステンプレート)
(C++26)
射影によって indirectly_readable 型の値型を計算する
(エイリアステンプレート)

イテレータアダプタ

逆順走査のためのイテレータアダプタ
(クラステンプレート)
(C++14)
引数から型が推論される std::reverse_iterator を作成する
(関数テンプレート)
コンテナの末尾への挿入用イテレータアダプタ
(クラステンプレート)
引数から推測される型の std::back_insert_iterator を作成する
(関数テンプレート)
コンテナの先頭への挿入用イテレータアダプタ
(クラステンプレート)
引数から推測される型の std::front_insert_iterator を作成する
(関数テンプレート)
コンテナへの挿入用イテレータアダプタ
(クラステンプレート)
引数から推測される型の std::insert_iterator を作成する
(関数テンプレート)
(C++23)
イテレータを定数イテレータに変換するイテレータアダプタ
(クラステンプレート)
(C++23)
指定された型に対する定数イテレータ型を計算する
(エイリアステンプレート)
(C++23)
定数イテレータで使用するセンチネル型を計算する
(エイリアステンプレート)
(C++23)
引数から推論された型の std::const_iterator を作成する
(関数テンプレート)
(C++23)
引数の型から推論される型の std::const_sentinel を作成する
(関数テンプレート)
(C++11)
右辺値にデリファレンスするイテレータアダプタ
(クラステンプレート)
(C++20)
std::move_iterator のためのセンチネルアダプタ
(クラステンプレート)
(C++11)
引数から推論された型の std::move_iterator を作成する
(関数テンプレート)
(C++20)
イテレータ型とその番兵を共通のイテレータ型に適合させる
(クラステンプレート)
(C++20)
範囲の境界を知っているイテレータで使用するデフォルトセンチネル
(class)
(C++20)
範囲の終端までの距離を追跡するイテレータアダプタ
(クラステンプレート)
(C++20)
任意の weakly_incrementable 型と常に等しくないと比較されるセンチネル
(クラス)

ストリームイテレータ

std::basic_istream から読み込む入力イテレータ
(クラステンプレート)
std::basic_ostream に書き込む出力イテレータ
(クラステンプレート)
std::basic_streambuf から読み込む入力イテレータ
(クラステンプレート)
std::basic_streambuf に書き込む出力イテレータ
(クラステンプレート)

イテレータ操作

定義済みヘッダー <iterator>
イテレータを指定された距離だけ進める
(関数テンプレート)
2つのイテレータ間の距離を返す
(関数テンプレート)
(C++11)
イテレータをインクリメントする
(関数テンプレート)
(C++11)
イテレータをデクリメントする
(関数テンプレート)
(C++20)
イテレータを指定された距離または指定された境界まで進める
(アルゴリズム関数オブジェクト)
(C++20)
イテレータとセンチネル間、または範囲の先頭と終端間の距離を返す
(アルゴリズム関数オブジェクト)
(C++20)
イテレータを指定された距離または境界までインクリメントする
(アルゴリズム関数オブジェクト)
(C++20)
イテレータを指定された距離または境界までデクリメントする
(アルゴリズム関数オブジェクト)

範囲アクセス (since C++11)

これらの非メンバ関数テンプレートは、コンテナ、プレーン配列、および std::initializer_list に対する汎用的なインターフェースを提供します。

ヘッダーで定義 <array>
ヘッダーで定義 <deque>
ヘッダーで定義 <flat_map>
ヘッダーで定義 <flat_set>
ヘッダーで定義 <forward_list>
ヘッダーで定義 <inplace_vector>
ヘッダーで定義 <iterator>
ヘッダーで定義 <list>
ヘッダーで定義 <map>
ヘッダーで定義 <regex>
ヘッダーで定義 <set>
ヘッダーで定義 <span>
ヘッダーで定義 <string>
ヘッダーで定義 <string_view>
ヘッダーで定義 <unordered_map>
ヘッダーで定義 <unordered_set>
ヘッダーで定義 <vector>
名前空間 std で定義
(C++11) (C++14)
コンテナまたは配列の先頭を指すイテレータを返す
(関数テンプレート)
(C++11) (C++14)
コンテナまたは配列の終端を指すイテレータを返す
(関数テンプレート)
(C++14)
コンテナまたは配列の先頭を指す逆方向イテレータを返す
(関数テンプレート)
(C++14)
コンテナまたは配列の終端を指す逆方向イテレータを返す
(関数テンプレート)
(C++17) (C++20)
コンテナまたは配列のサイズを返す
(関数テンプレート)
(C++17)
コンテナが空かどうかをチェックする
(関数テンプレート)
(C++17)
基となる配列へのポインタを取得する
(関数テンプレート)

欠陥報告

以下の動作変更に関する欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

DR 適用バージョン 公開時の動作 修正後の動作
CWG 1181 C++98 配列型は値型になれなかった 値型になれる
LWG 208 C++98 末尾イテレータは常に非特異的だった 特異的になりうる
LWG 278 C++98 イテレータの有効性が定義されていなかった 常に非特異的と定義
LWG 324 C++98 出力イテレータは値型を持っていた 出力イテレータは書き込み可能型を持つ
LWG 407 C++98 特異的イテレータは破棄できなかった 許可
LWG 408
( N3066 ) 		C++98 特異的イテレータはコピーできなかった 値初期化されている場合は許可
LWG 1185
( N3066 ) 		C++98 LegacyForwardIterator , LegacyBidirectionalIterator
および LegacyRandomAccessIterator
は常に LegacyOutputIterator を満たす 		必ずしも LegacyOutputIterator を満たさない場合がある
LWG 1210
( N3066 ) 		C++98 イテレータの特異性と到達可能性の定義が
コンテナに依存していた 		シーケンスに依存するように変更
LWG 3009 C++17 <string_view> は範囲アクセス関数テンプレートを
提供していなかった 		これらのテンプレートを提供
LWG 3987 C++23 <flat_map> および <flat_set> は
範囲アクセス関数テンプレートを提供していなかった 		これらのテンプレートを提供