# Iterator library

From cppreference.com
< cpp

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 and LegacyContiguousIterator) 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
--- | ---

LegacyRandomAccessIterator

LegacyBidirectionalIterator

LegacyForwardIterator

LegacyInputIterator

- read
- increment (without multiple passes)

- increment (with multiple passes)

- decrement

- random access

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)

Iterators that fall into one of the above categories and also meet the requirements of LegacyContiguousIterator are called contiguous iterators.

LegacyContiguousIterator

- contiguous storage

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`
Readable | specifies that a type is readable by applying operator `*` (concept)
Writable | specifies that a value can be written to an iterator's referenced object (concept)
WeaklyIncrementable | specifies that a `Semiregular` type can be incremented with pre- and post-increment operators (concept)
Incrementable | specifies that the increment operation on a `WeaklyIncrementable` type is equality-preserving and that the type is `EqualityComparable` (concept)
Iterator | specifies that objects of a type can be incremented and dereferenced (concept)
Sentinel | specifies a type is a sentinel for an `Iterator` type (concept)
SizedSentinel | specifies that the - operator can be applied to an iterator and a sentinel to calculate their difference in constant time (concept)
InputIterator | 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)
OutputIterator | 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)
ForwardIterator | specifies that an `InputIterator` is a forward iterator, supporting equality comparison and multi-pass (concept)
BidirectionalIterator | specifies that a `ForwardIterator` is a bidirectional interator, supporting movement backwards (concept)
RandomAccessIterator | specifies that a `BidirectionalIterator` is a random-access iterator, supporting advancement in constant time and subscripting (concept)
ContiguousIterator | specifies that a `RandomAccessIterator` is a contiguous iterator, referring to elements that are contiguous in memory (concept)

### Iterator associated types

Defined in namespace `std`
incrementable_traits | computes the difference type of a `WeaklyIncrementable` type (class template)
readable_traits | computes the value type of a `Readable` type (class template)
iter_value_t iter_reference_t iter_difference_t iter_rvalue_reference_t iter_common_reference_t | computes the associate types of an iterator (alias template)

### Iterator customization points

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

(since C++20)

### Iterator primitives

iterator_traits | provides uniform interface to the properties of an iterator (class template)
input_iterator_tag output_iterator_tag forward_iterator_tag bidirectional_iterator_tag random_access_iterator_tag contiguous_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 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 `WeaklyIncrementable` 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 `<iterator>`
Defined in namespace `std`
begin cbegin (C++11)(C++14) | returns an iterator to the beginning of a container or array (function template)
end cend (C++11)(C++14) | returns an iterator to the end of a container or array (function template)
rbegin crbegin (C++14) | returns a reverse iterator to a container or array (function template)
rend crend (C++14) | returns a reverse end iterator for a container or array (function template)
Defined in header `<ranges>`
Defined in namespace `std::ranges`
begin cbegin | returns an iterator to the beginning of a range (customization point object)
end cend | returns an iterator to the end of a range (customization point object)
rbegin crbegin | returns a reverse iterator to a range (customization point object)
rend crend | returns a reverse end iterator to a range (customization point object)

### Container access

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

Defined in header `<iterator>`
size ssize (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)
Defined in header `<ranges>`
Defined in namespace `std::ranges`
size | obtains the size of a range whose size can be calculated in constant time (customization point object)
empty | checks whether a range is empty (customization point object)
data cdata | obtains a pointer to the beginning of a contiguous range (customization point object)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/iterator&oldid=109818"