##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# Iterator library

From cppreference.com
< cpp

The iterator library provides definitions for five kinds of iterators as well as iterator traits, adapters, and utility functions.

### [edit] Iterator categories

There are five (until C++17)six (since C++17) kinds of iterators: `InputIterator`, `OutputIterator`, `ForwardIterator`, `BidirectionalIterator`, `RandomAccessIterator`, and `ContiguousIterator` (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 `RandomAccessIterator`, so a pointer can be used anywhere a `RandomAccessIterator` is expected.

All of the iterator categories (except `OutputIterator`) can be organized into a hierarchy, where more powerful iterator categories (e.g. `RandomAccessIterator`) support the operations of less powerful categories (e.g. `InputIterator`). If an iterator falls into one of these categories and also satisfies the requirements of `OutputIterator`, then it is called a mutable iterator and supports both input and output. Non-mutable iterators are called constant iterators.

Iterator category | Defined operations
--- | ---
`ContiguousIterator` | `RandomAccessIterator` | `BidirectionalIterator` | `ForwardIterator` | `InputIterator` | 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 `OutputIterator` are called mutable iterators.
`OutputIterator` |  | write increment (without multiple passes)

Note: `ContiguousIterator` 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.

### [edit] Iterator primitives

iterator_traits | provides uniform interface to the properties of an iterator (class template) [edit]
input_iterator_tag output_iterator_tag forward_iterator_tag bidirectional_iterator_tag random_access_iterator_tag | empty class types used to indicate iterator categories (class) [edit]
iterator (deprecated in C++17) | base class to ease the definition of required types for simple iterators (class template) [edit]

### [edit] Iterator adaptors

reverse_iterator | iterator adaptor for reverse-order traversal (class template) [edit]
make_reverse_iterator (C++14) | creates a std::reverse_iterator of type inferred from the argument (function template) [edit]
move_iterator (C++11) | iterator adaptor which dereferences to an rvalue reference (class template) [edit]
make_move_iterator (C++11) | creates a std::move_iterator of type inferred from the argument (function template) [edit]
back_insert_iterator | iterator adaptor for insertion at the end of a container (class template) [edit]
back_inserter | creates a std::back_insert_iterator of type inferred from the argument (function template) [edit]
front_insert_iterator | iterator adaptor for insertion at the front of a container (class template) [edit]
front_inserter | creates a std::front_insert_iterator of type inferred from the argument (function template) [edit]
insert_iterator | iterator adaptor for insertion into a container (class template) [edit]
inserter | creates a std::insert_iterator of type inferred from the argument (function template) [edit]

### [edit] Stream iterators

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

### [edit] Iterator operations

Defined in header `<iterator>`
advance | advances an iterator by given distance (function) [edit]
distance | returns the distance between two iterators (function) [edit]
next (C++11) | increment an iterator (function) [edit]
prev (C++11) | decrement an iterator (function) [edit]

### [edit] Range access

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

Defined in header `<iterator>`
begin cbegin (C++11)(C++14) | returns an iterator to the beginning of a container or array (function) [edit]
end cend (C++11)(C++14) | returns an iterator to the end of a container or array (function) [edit]
rbegin crbegin (C++14) | returns a reverse iterator to a container or array (function) [edit]
rend crend (C++14) | returns a reverse end iterator for a container or array (function) [edit]

### [edit] Container access

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

size (C++17) | returns the size of a container or array (function) [edit]
empty (C++17) | checks whether the container is empty (function) [edit]
data (C++17) | obtains the pointer to the underlying array (function) [edit]

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