Iterator library

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Iterator library

Iterator concepts
indirectly_readable (C++20) indirectly_writable (C++20) weakly_incrementable (C++20) incrementable (C++20) input_or_output_iterator (C++20) sentinel_for (C++20) sized_sentinel_for (C++20)	input_iterator (C++20) output_iterator (C++20) forward_iterator (C++20) bidirectional_iterator (C++20) random_access_iterator (C++20) contiguous_iterator (C++20)
Iterator primitives
iterator_traits input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20) iterator (deprecated in C++17)	incrementable_traits (C++20) indirectly_readable_traits (C++20) iter_value_titer_difference_titer_reference_titer_const_reference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++20)(C++23)(C++20)(C++20)
Algorithm concepts and utilities
Indirect callable concepts
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20)   indirect_unary_predicate (C++20)	indirect_binary_predicate (C++20) indirect_equivalence_relation (C++20) indirect_strict_weak_order (C++20)
Common algorithm requirements
indirectly_movable (C++20) indirectly_movable_storable (C++20) indirectly_copyable (C++20) indirectly_copyable_storable (C++20)	indirectly_swappable (C++20) indirectly_comparable (C++20) permutable (C++20) mergeable (C++20) sortable (C++20)
Utilities
indirect_result_t (C++20)	projected (C++20)
Iterator adaptors
reverse_iterator move_iterator (C++11) move_sentinel (C++20) common_iterator (C++20) counted_iterator (C++20) basic_const_iterator (C++23) const_iterator (C++23) const_sentinel (C++23) back_insert_iterator front_insert_iterator insert_iterator	make_reverse_iterator (C++14) make_move_iterator (C++11) default_sentinel_tdefault_sentinel (C++20)(C++20) unreachable_sentinel_tunreachable_sentinel (C++20)(C++20) make_const_iterator (C++23) make_const_sentinel (C++23) back_inserter front_inserter inserter
Stream iterators
istream_iterator ostream_iterator	istreambuf_iterator ostreambuf_iterator
Iterator customization points
ranges::iter_move (C++20)
ranges::iter_swap (C++20)
Iterator operations
advance distance prev (C++11) next (C++11)	ranges::advance (C++20) ranges::distance (C++20) ranges::prev (C++20) ranges::next (C++20)
Range access
begincbegin (C++11)(C++14) endcend (C++11)(C++14) sizessize (C++17)(C++20)	rbegincrbegin (C++14)(C++14) rendcrend (C++14)(C++14) empty (C++17) data (C++17)

 

The iterator library provides definitions for five (until C++17)six (since C++17) kinds of iterators as well as iterator traits, adaptors, and utility functions.

Iterator categories

There are five (until C++17)six (since C++17) kinds of iterators: LegacyInputIterator, LegacyOutputIterator, LegacyForwardIterator, LegacyBidirectionalIterator, LegacyRandomAccessIterator, and LegacyContiguousIterator (since C++17).

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 by LegacyRandomAccessIterator, so a pointer can be used anywhere a LegacyRandomAccessIterator is expected.

All of the iterator categories (except LegacyOutputIterator) 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 of LegacyOutputIterator, then it is called a mutable iterator and supports both input and output. Non-mutable iterators are called constant iterators.

Iterator category					Defined operations
LegacyContiguousIterator	LegacyRandomAccessIterator	LegacyBidirectionalIterator	LegacyForwardIterator	LegacyInputIterator	read increment (without multiple passes)
					increment (with multiple passes)
					decrement
					random access
					contiguous storage
Iterators that fall into one of the above categories and also meet the requirements of LegacyOutputIterator are called mutable iterators.
LegacyOutputIterator					write increment (without multiple passes)

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

C++20 iterator concepts

C++20 introduces a new system of iterators based on concepts that are different from C++17 iterators. While the basic taxonomy remains similar, the requirements for individual iterator categories are somewhat different.

Defined in namespace std
indirectly_readable (C++20)	specifies that a type is indirectly readable by applying operator * (concept)
indirectly_writable (C++20)	specifies that a value can be written to an iterator's referenced object (concept)
weakly_incrementable (C++20)	specifies that a semiregular type can be incremented with pre- and post-increment operators (concept)
incrementable (C++20)	specifies that the increment operation on a weakly_incrementable type is equality-preserving and that the type is equality_comparable (concept)
input_or_output_iterator (C++20)	specifies that objects of a type can be incremented and dereferenced (concept)
sentinel_for (C++20)	specifies a type is a sentinel for an input_or_output_iterator type (concept)
sized_sentinel_for (C++20)	specifies that the - operator can be applied to an iterator and a sentinel to calculate their difference in constant time (concept)
input_iterator (C++20)	specifies that a type is an input iterator, that is, its referenced values can be read and it can be both pre- and post-incremented (concept)
output_iterator (C++20)	specifies that a type is an output iterator for a given value type, that is, values of that type can be written to it and it can be both pre- and post-incremented (concept)
forward_iterator (C++20)	specifies that an input_iterator is a forward iterator, supporting equality comparison and multi-pass (concept)
bidirectional_iterator (C++20)	specifies that a forward_iterator is a bidirectional iterator, supporting movement backwards (concept)
random_access_iterator (C++20)	specifies that a bidirectional_iterator is a random-access iterator, supporting advancement in constant time and subscripting (concept)
contiguous_iterator (C++20)	specifies that a random_access_iterator is a contiguous iterator, referring to elements that are contiguous in memory (concept)

Iterator associated types

Defined in namespace std
incrementable_traits (C++20)	computes the difference type of a weakly_incrementable type (class template)
indirectly_readable_traits (C++20)	computes the value type of an indirectly_readable type (class template)
iter_value_titer_reference_titer_const_reference_titer_difference_titer_rvalue_reference_titer_common_reference_t (C++20)(C++20)(C++23)(C++20)(C++20)(C++20)	computes the associated types of an iterator (alias template)

Iterator primitives

iterator_traits	provides uniform interface to the properties of an iterator (class template)
input_iterator_tagoutput_iterator_tagforward_iterator_tagbidirectional_iterator_tagrandom_access_iterator_tagcontiguous_iterator_tag (C++20)	empty class types used to indicate iterator categories (class)
iterator (deprecated in C++17)	base class to ease the definition of required types for simple iterators (class template)

Iterator customization points

Defined in namespace std::ranges
iter_move (C++20)	casts the result of dereferencing an object to its associated rvalue reference type (customization point object)
iter_swap (C++20)	swaps the values referenced by two dereferenceable objects (customization point object)

Algorithm concepts and utilities

C++20 also provides a set of concepts and related utility templates designed to ease constraining common algorithm operations.

Defined in header <iterator>
Defined in namespace std
Indirect callable concepts
indirectly_unary_invocableindirectly_regular_unary_invocable (C++20)(C++20)	specifies that a callable type can be invoked with the result of dereferencing an indirectly_readable type (concept)
indirect_unary_predicate (C++20)	specifies that a callable type, when invoked with the result of dereferencing an indirectly_readable type, satisfies predicate (concept)
indirect_binary_predicate (C++20)	specifies that a callable type, when invoked with the result of dereferencing two indirectly_readable types, satisfies predicate (concept)
indirect_equivalence_relation (C++20)	specifies that a callable type, when invoked with the result of dereferencing two indirectly_readable types, satisfies equivalence_relation (concept)
indirect_strict_weak_order (C++20)	specifies that a callable type, when invoked with the result of dereferencing two indirectly_readable types, satisfies strict_weak_order (concept)
Common algorithm requirements
indirectly_movable (C++20)	specifies that values may be moved from an indirectly_readable type to an indirectly_writable type (concept)
indirectly_movable_storable (C++20)	specifies that values may be moved from an indirectly_readable type to an indirectly_writable type and that the move may be performed via an intermediate object (concept)
indirectly_copyable (C++20)	specifies that values may be copied from an indirectly_readable type to an indirectly_writable type (concept)
indirectly_copyable_storable (C++20)	specifies that values may be copied from an indirectly_readable type to an indirectly_writable type and that the copy may be performed via an intermediate object (concept)
indirectly_swappable (C++20)	specifies that the values referenced by two indirectly_readable types can be swapped (concept)
indirectly_comparable (C++20)	specifies that the values referenced by two indirectly_readable types can be compared (concept)
permutable (C++20)	specifies the common requirements of algorithms that reorder elements in place (concept)
mergeable (C++20)	specifies the requirements of algorithms that merge sorted sequences into an output sequence by copying elements (concept)
sortable (C++20)	specifies the common requirements of algorithms that permute sequences into ordered sequences (concept)
Utilities
indirect_result_t (C++20)	computes the result of invoking a callable object on the result of dereferencing some set of indirectly_readable types (alias template)
projected (C++20)	helper template for specifying the constraints on algorithms that accept projections (class template)

Iterator adaptors

reverse_iterator	iterator adaptor for reverse-order traversal (class template)
make_reverse_iterator (C++14)	creates a std::reverse_iterator of type inferred from the argument (function template)
move_iterator (C++11)	iterator adaptor which dereferences to an rvalue reference (class template)
move_sentinel (C++20)	sentinel adaptor for use with std::move_iterator (class template)
make_move_iterator (C++11)	creates a std::move_iterator of type inferred from the argument (function template)
common_iterator (C++20)	adapts an iterator type and its sentinel into a common iterator type (class template)
default_sentinel_t (C++20)	default sentinel for use with iterators that know the bound of their range (class)
counted_iterator (C++20)	iterator adaptor that tracks the distance to the end of the range (class template)
unreachable_sentinel_t (C++20)	sentinel that always compares unequal to any weakly_incrementable type (class)
back_insert_iterator	iterator adaptor for insertion at the end of a container (class template)
back_inserter	creates a std::back_insert_iterator of type inferred from the argument (function template)
front_insert_iterator	iterator adaptor for insertion at the front of a container (class template)
front_inserter	creates a std::front_insert_iterator of type inferred from the argument (function template)
insert_iterator	iterator adaptor for insertion into a container (class template)
inserter	creates a std::insert_iterator of type inferred from the argument (function template)

Stream iterators

istream_iterator	input iterator that reads from std::basic_istream (class template)
ostream_iterator	output iterator that writes to std::basic_ostream (class template)
istreambuf_iterator	input iterator that reads from std::basic_streambuf (class template)
ostreambuf_iterator	output iterator that writes to std::basic_streambuf (class template)

Iterator operations

Defined in header <iterator>
advance	advances an iterator by given distance (function template)
distance	returns the distance between two iterators (function template)
next (C++11)	increment an iterator (function template)
prev (C++11)	decrement an iterator (function template)
ranges::advance (C++20)	advances an iterator by given distance or to a given bound (niebloid)
ranges::distance (C++20)	returns the distance between an iterator and a sentinel, or between the beginning and end of a range (niebloid)
ranges::next (C++20)	increment an iterator by a given distance or to a bound (niebloid)
ranges::prev (C++20)	decrement an iterator by a given distance or to a bound (niebloid)

Range access

These non-member functions provide a generic interface for containers, plain arrays, and std::initializer_list.

Defined in header <array>
Defined in header <deque>
Defined in header <forward_list>
Defined in header <iterator>
Defined in header <list>
Defined in header <map>
Defined in header <regex>
Defined in header <set>
Defined in header <span>
Defined in header <string>
Defined in header <string_view>
Defined in header <unordered_map>
Defined in header <unordered_set>
Defined in header <vector>
Defined in namespace std
begincbegin (C++11)(C++14)	returns an iterator to the beginning of a container or array (function template)
endcend (C++11)(C++14)	returns an iterator to the end of a container or array (function template)
rbegincrbegin (C++14)	returns a reverse iterator to the beginning of a container or array (function template)
rendcrend (C++14)	returns a reverse end iterator for a container or array (function template)
sizessize (C++17)(C++20)	returns the size of a container or array (function template)
empty (C++17)	checks whether the container is empty (function template)
data (C++17)	obtains the pointer to the underlying array (function template)