23 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 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_­category denotes

• (1.1)
  random_­access_­iterator_­tag if the type iterator_­traits<​Iterator>​::​iterator_­category models derived_­from<random_­access_­iterator_­tag>, and
• (1.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.

The nested typedef-names of the specialization of iterator_­traits for common_­iterator<I, S> are defined as follows.

Class template counted_­iterator is an iterator adaptor with the same behavior as the underlying iterator except that it keeps track of the distance to the end of its range.

It can be used together with default_­sentinel in calls to generic algorithms to operate on a range of N elements starting at a given position without needing to know the end position a priori.

Two values i1 and i2 of types counted_­iterator<I1> and counted_­iterator<I2> refer to elements of the same sequence if and only if next(i1.base(), i1.count()) and next(i2.base(), i2.count()) refer to the same (possibly past-the-end) element.