Iterators are a generalization ofpointers that allow a C++ program to work with different data structures (for example,containers andranges(since C++20)) in a uniform manner. The iterator library provides definitions for iterators, as well as iterator traits, adaptors, and utility functions.

Since iterators are an abstraction of pointers, their semantics are a generalization of most of the semantics of pointers in C++. This ensures that everyfunction template that takes iterators works as well with regular pointers.

[edit]Iterator categories

There arefive(until C++17)six(since C++17) kinds of iterators:LegacyInputIterator,LegacyOutputIterator,LegacyForwardIterator,LegacyBidirectionalIterator,LegacyRandomAccessIterator, andLegacyContiguousIterator(since C++17). (See alsoLegacyIterator for the most basic kind of iterator.)

Instead of being defined by specific types, each category of iterator is defined by the operations that can be performed on it. This definition means that any type that supports the necessary operations can be used as an iterator -- for example, a pointer supports all of the operations required byLegacyRandomAccessIterator, so a pointer can be used anywhere aLegacyRandomAccessIterator is expected.

All of the iterator categories (exceptLegacyOutputIterator) can be organized into a hierarchy, where more powerful iterator categories (e.g.LegacyRandomAccessIterator) support the operations of less powerful categories (e.g.LegacyInputIterator). If an iterator falls into one of these categories and also satisfies the requirements ofLegacyOutputIterator, then it is called amutable iterator and supportsboth input and output. Non-mutable iterators are calledconstant iterators.

1. ↑LegacyContiguousIterator category was only formally specified in C++17, but the iterators ofstd::vector,std::basic_string,std::array, andstd::valarray, as well as pointers into C arrays are often treated as a separate category in pre-C++17 code.

Note: A type supporting the required operations in a row of the table above does not necessarily fall into the corresponding category, see the category page for the complete list of requirements.

[edit]Definitions

[edit]Types and writability

An input iteratori supports the expression*i, resulting in a value of someobject typeT, called thevalue type of the iterator.

An output iteratori has a non-empty set of types that arewritable(until C++20)indirectly_writable(since C++20) to the iterator; for each such typeT, the expression*i= o is valid whereo is a value of typeT.

For every iterator typeXfor which equality is defined(until C++20), there is a corresponding signedinteger(until C++20)integer-like(since C++20) type called thedifference type of the iterator.

[edit]Dereferenceability and validity

Just as a regular pointer to anarray guarantees that there is a pointer value pointing past the last element of the array, so for any iterator type there is an iterator value that points past the last element of a corresponding sequence. Such a value is called apast-the-end value.

Values of an iteratori for which the expression*i is defined are calleddereferenceable. Thestandard library never assumes that past-the-end values are dereferenceable.

Iterators can also havesingular values that are not associated with any sequence. Results of most expressions are undefined for singular values; the only exceptions are

• the assignment of a non-singular value to an iterator that holds a singular value,
• destroying an iterator that holds a singular value, and,
• for iterators that meet theDefaultConstructible requirements, using avalue-initialized iterator as the source of a copyor move(since C++11) operation.

In these cases the singular value is overwritten the same way as any other value. Dereferenceable values are always non-singular.

Aninvalid iterator is an iterator that may be singular.

[edit]Ranges

Most of the standard library’s algorithmic templates that operate on data structures have interfaces that use ranges.

The result of the application of functions in the standard library to invalid ranges is undefined.

[edit]Iterator concepts(since C++20)

A new system of iterators based onconcepts that are different from C++17 iterators. While the basic taxonomy remains similar, the requirements for individual iterator categories are somewhat different.

[edit]Iterator associated types(since C++20)

[edit]Iterator primitives

[edit]Iterator customization points(since C++20)

[edit]Algorithm concepts and utilities(since C++20)

A set of concepts and related utility templates designed to ease constraining common algorithm operations.

[edit]Iterator adaptors

[edit]Stream iterators

[edit]Iterator operations

[edit]Range access(since C++11)

These non-member function templates provide a generic interface for containers, plain arrays, andstd::initializer_list.

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• In other languages

• العربية
• Deutsch
• Español
• Français
• Italiano
• 日本語
• 한국어
• Português
• Русский
• Türkçe
• 中文