24 Iterators library [iterators]

Class template reverse_iterator is an iterator adaptor that iterates from the end of the sequence defined by its underlying iterator to the beginning of that sequence.

The member typedef-name iterator_concept denotes

• (1.1)
  random_access_iterator_tag if Iterator models random_access_iterator, and
• (1.2)
  bidirectional_iterator_tag otherwise.

The member typedef-name iterator_category denotes

• (2.1)
  random_access_iterator_tag if the type iterator_traits<​Iterator>​::​iterator_category models derived_from<random_access_iterator_tag>, and
• (2.2)
  iterator_traits<​Iterator>​::​iterator_category otherwise.

The template parameter Iterator shall either meet the requirements of a Cpp17BidirectionalIterator ([bidirectional.iterators]) or model bidirectional_iterator ([iterator.concept.bidir]).

Additionally, Iterator shall either meet the requirements of a Cpp17RandomAccessIterator ([random.access.iterators]) or model random_access_iterator ([iterator.concept.random.access]) if the definitions of any of the members

• (2.1)
  operator+, operator-, operator+=, operator-= ([reverse.iter.nav]), or
• (2.2)
  operator[] ([reverse.iter.elem]),

or the non-member operators ([reverse.iter.cmp])

• (2.3)
  operator<, operator>, operator<=, operator>=, operator-, or operator+ ([reverse.iter.nonmember])

are instantiated ([temp.inst]).

To make it possible to deal with insertion in the same way as writing into an array, a special kind of iterator adaptors, called insert iterators, are provided in the library.

With regular iterator classes, while (first != last) *result++ = *first++; causes a range [first, last) to be copied into a range starting with result.

The same code with result being an insert iterator will insert corresponding elements into the container.

This device allows all of the copying algorithms in the library to work in the insert mode instead of the regular overwrite mode.

An insert iterator is constructed from a container and possibly one of its iterators pointing to where insertion takes place if it is neither at the beginning nor at the end of the container.

Insert iterators meet the requirements of output iterators.

operator* returns the insert iterator itself.

The assignment operator=(const T& x) is defined on insert iterators to allow writing into them, it inserts x right before where the insert iterator is pointing.

In other words, an insert iterator is like a cursor pointing into the container where the insertion takes place.

back_insert_iterator inserts elements at the end of a container, front_insert_iterator inserts elements at the beginning of a container, and insert_iterator inserts elements where the iterator points to in a container.

back_inserter, front_inserter, and inserter are three functions making the insert iterators out of a container.

Class template basic_const_iterator is an iterator adaptor with the same behavior as the underlying iterator except that its indirection operator implicitly converts the value returned by the underlying iterator's indirection operator to a type such that the adapted iterator is a constant iterator ([iterator.requirements]).

Some generic algorithms can be called with constant iterators to avoid mutation.

Specializations of basic_const_iterator are constant iterators.

Given some type I, the concept not-a-const-iterator is defined as false if I is a specialization of basic_const_iterator and true otherwise.

basic_const_iterator<Iterator>​::​iterator_concept is defined as follows:

• (1.1)
  If Iterator models contiguous_iterator, then iterator_concept denotes contiguous_iterator_tag.
• (1.2)
  Otherwise, if Iterator models random_access_iterator, then iterator_concept denotes random_access_iterator_tag.
• (1.3)
  Otherwise, if Iterator models bidirectional_iterator, then iterator_concept denotes bidirectional_iterator_tag.
• (1.4)
  Otherwise, if Iterator models forward_iterator, then iterator_concept denotes forward_iterator_tag.
• (1.5)
  Otherwise, iterator_concept denotes input_iterator_tag.

The member typedef-name iterator_category is defined if and only if Iterator models forward_iterator.

In that case, basic_const_iterator<Iterator>​::​iterator_category denotes the type iterator_traits<​Iterator>​::​iterator_category.

Class template move_iterator is an iterator adaptor with the same behavior as the underlying iterator except that its indirection operator implicitly converts the value returned by the underlying iterator's indirection operator to an rvalue.

Some generic algorithms can be called with move iterators to replace copying with moving.

The member typedef-name iterator_concept is defined as follows:

• (1.1)
  If Iterator models random_access_iterator, then iterator_concept denotes random_access_iterator_tag.
• (1.2)
  Otherwise, if Iterator models bidirectional_iterator, then iterator_concept denotes bidirectional_iterator_tag.
• (1.3)
  Otherwise, if Iterator models forward_iterator, then iterator_concept denotes forward_iterator_tag.
• (1.4)
  Otherwise, iterator_concept denotes input_iterator_tag.

The member typedef-name iterator_category is defined if and only if the qualified-id iterator_traits<Iterator>​::​iterator_category is valid and denotes a type.

In that case, iterator_category denotes

• (2.1)
  random_access_iterator_tag if the type iterator_traits<​Iterator>​::​iterator_category models derived_from<random_access_iterator_tag>, and
• (2.2)
  iterator_traits<​Iterator>​::​iterator_category otherwise.

The template parameter Iterator shall either meet the Cpp17InputIterator requirements ([input.iterators]) or model input_iterator ([iterator.concept.input]).

Additionally, if any of the bidirectional traversal functions are instantiated, the template parameter shall either meet the Cpp17BidirectionalIterator requirements ([bidirectional.iterators]) or model bidirectional_iterator ([iterator.concept.bidir]).

If any of the random access traversal functions are instantiated, the template parameter shall either meet the Cpp17RandomAccessIterator requirements ([random.access.iterators]) or model random_access_iterator ([iterator.concept.random.access]).

Class template move_sentinel is a sentinel adaptor useful for denoting ranges together with move_iterator.

When an input iterator type I and sentinel type S model sentinel_for<S, I>, move_sentinel<S> and move_iterator<I> model sentinel_for<move_sentinel<S>, move_iterator<I>> as well.

Class template common_iterator is an iterator/sentinel adaptor that is capable of representing a non-common range of elements (where the types of the iterator and sentinel differ) as a common range (where they are the same).

It does this by holding either an iterator or a sentinel, and implementing the equality comparison operators appropriately.