Edit

<iterator>

  • Article

Defines predefined iterators and stream iterators, iterator primitives, and supporting templates.

Requirements

Header: <iterator>

Namespace: std

Remarks

Iterators are a generalization of pointers that allow a C++ program to work with different data structures in a uniform way. Instead of operating on specific data types, algorithms operate on a range of values as specified by a kind of iterator. Algorithms can operate on any data structure that satisfies the requirements of the iterator.

In C++20, there are six categories of iterators. Iterators are arranged in a hierarchy of capability. Their capabilities are specified by C++20 concepts. For a description of the various iterators and their capabilities, see Iterator concepts

Visual Studio has added extensions to C++ Standard Library iterators to support debugging for checked and unchecked iterators. For more information, see Safe Libraries: C++ Standard Library.

Members

Functions

Name Description
advance Increments an iterator by a specified number of positions.
back_inserter Creates an iterator that can insert elements at the back of a specified container.
begin Retrieves an iterator to the first element in a specified container.
cbegin Retrieves a read-only iterator to the first element in a specified container.
cend Retrieves a read-only iterator to the element that follows the last element in the specified container.
crbegin Get a reverse read-only iterator to the beginning of the specified container.
crend Get the sentinel at the end of what crbegin() returns.
data Get a pointer to the first element in the specified container.
distance Determines the number of increments between the positions addressed by two iterators.
end Retrieves an iterator to the element that follows the last element in the specified container.
empty Test if the specified container is empty.
front_inserter Creates an iterator that can insert elements at the front of a specified container.
inserter An iterator adaptor that adds a new element to a container at a specified point of insertion.
make_checked_array_iterator Creates a checked_array_iterator that can be used by other algorithms. Note: This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.
make_move_iterator Returns a move iterator containing the provided iterator as its stored base iterator.
make_unchecked_array_iterator Creates an unchecked_array_iterator that can be used by other algorithms. Note: This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.
next Iterates a specified number of times and returns the new iterator position.
prev Iterates in reverse a specified number of times and returns the new iterator position.
rbegin Get a reverse iterator to the beginning of the specified container.
rend Get a reverse iterator to the sentinel at the end of the specified container.
size Get the number of elements.

Operators

Name Description
operator!= Tests if the iterator object on the left side of the operator isn't equal to the iterator object on the right side.
operator== Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.
operator< Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.
operator<= Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.
operator> Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.
operator>= Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.
operator+ Adds an offset to an iterator and returns the new reverse_iterator addressing the inserted element at the new offset position.
operator- Subtracts one iterator from another and returns the difference.

Classes

Name Description
back_insert_iterator The class template describes an output iterator object. It inserts elements into a container of type Container, which it accesses through the protected pointer object it stores called container.
bidirectional_iterator_tag A class that provides a return type for an iterator_category function that represents a bidirectional iterator.
checked_array_iterator A class that accesses an array using a random access, checked iterator. Note: This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.
forward_iterator_tag A class that provides a return type for an iterator_category function that represents a forward iterator.
front_insert_iterator The class template describes an output iterator object. It inserts elements into a container of type Container, which it accesses through the protected pointer object it stores called container.
input_iterator_tag A class that provides a return type for an iterator_category function that represents an input iterator.
insert_iterator The class template describes an output iterator object. It inserts elements into a container of type Container, which it accesses through the protected pointer object it stores called container. It also stores the protected iterator object, of class Container::iterator, called iter.
istream_iterator The class template describes an input iterator object. It extracts objects of class Ty from an input stream, which it accesses through an object it stores, of type pointer to basic_istream<Elem, Tr>.
istreambuf_iterator The class template describes an input iterator object. It inserts elements of class Elem into an output stream buffer, which it accesses through an object it stores, of type pointer to basic_streambuf<Elem, Tr>.
iterator The class template is used as a base type for all iterators.
iterator_traits A template helper class providing critical types that are associated with different iterator types so that they can be referred to in the same way.
move_iterator A move_iterator object stores a random-access iterator of type RandomIterator. It behaves like a random-access iterator, except when dereferenced. The result of operator* is implicitly cast to value_type&&: to make an rvalue reference.
ostream_iterator The class template describes an output iterator object. It inserts objects of class Type into an output stream, which it accesses through an object it stores, of type pointer to basic_ostream<Elem, Tr>.
ostreambuf_iterator The class template describes an output iterator object. It inserts elements of class Elem into an output stream buffer, which it accesses through an object it stores, of type pointer to basic_streambuf<Elem, Tr>.
output_iterator_tag A class that provides a return type for iterator_category function that represents an output iterator.
random_access_iterator_tag A class that provides a return type for iterator_category function that represents a random-access iterator.
reverse_iterator The class template describes an object that behaves like a random-access iterator, only in reverse.
unchecked_array_iterator A class that accesses an array using a random access, unchecked iterator. Note: This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.

Concepts

The following concepts are defined in the std namespace. They apply to iterators, and are also related to the iterator categories for ranges described in <ranges> concepts.

Iterator concept Description
bidirectional_iteratorC++20 Specifies an iterator that can read and write both forwards and backwards.
contiguous_iteratorC++20 Specifies an iterator whose elements are sequential in memory, the same size, and can be accessed using pointer arithmetic.
forward_iteratorC++20 Specifies an iterator that can read (and possibly write) multiple times.
input_iteratorC++20 Specifies an iterator that you can read from at least once.
input_or_output_iteratorC++20 The basis of the iterator concept taxonomy.
output_iterator Specifies an iterator that you can write to.
random_access_iteratorC++20 Specifies an iterator that you can read and write by index.
sentinel_forC++20 Specifies a sentinel for an iterator type.
sized_sentinel_forC++20 Specifies that an iterator and its sentinel can be subtracted (using -) to find their difference in constant time.

See also

Header Files Reference
Thread Safety in the C++ Standard Library
C++ Standard Library Reference