Name

reverse_iterator class template — Iterator wrapper to reverse direction

Synopsis

template <typename Iterator>
class reverse_iterator : public iterator<
  typename iterator_traits<Iterator>::iterator_category,
  typename iterator_traits<Iterator>::value_type,
  typename iterator_traits<Iterator>::difference_type,
  typename iterator_traits<Iterator>::pointer,
  typename iterator_traits<Iterator>::reference>
{
protected:
  Iterator current;
public:
  typedef Iterator iterator_type;
  typedef typename iterator_traits<Iterator>::difference_type
    difference_type;
  typedef typename iterator_traits<Iterator>::reference reference;
  typedef typename iterator_traits<Iterator>::pointer pointer;
  reverse_iterator(  );
  explicit reverse_iterator(Iterator x);
  template <typename U>
  reverse_iterator(const reverse_iterator<U>& u);
  Iterator base(  ) const;  // Explicit
  reference operator*(  ) const;
  pointer operator->(  ) const;
  reverse_iterator& operator++(  );
  reverse_iterator operator++(int);
  reverse_iterator& operator--(  );
  reverse_iterator operator--(int);
  reverse_iterator operator+(difference_type n) const;
  reverse_iterator& operator+=(difference_type n);
  reverse_iterator operator-(difference_type n) const;
  reverse_iterator& operator-=(difference_type n);
  reference operator[](difference_type n) const;
};

The reverse_iterator class template is an adapter for a bidirectional or random access iterator to iterate the sequence in the opposite direction of the adapted iterator. In other words, if the adapted iterator advances from the first to the last item in a container, a reverse iterator starts with the last items and "advances" to the first item. In addition to the reverse_iterator template, there are also several function templates for the comparison and arithmetic (+ and -) operators.

The standard containers return reverse_iterator objects from the rbegin( ) and rend( ) functions. The following example shows a simple implementation of these functions:

reverse_iterator rbegin(  ) { return reverse_iterator(end(  )); }
reverse_iterator rend(  ) { return reverse_iterator(begin(  )); }

Because an iterator can point to one past the last item in a container but cannot point to one item before the first, a reverse iterator conceptually points to one item before the position to which the adapted iterator points. In other words, given an iterator, iter, which points to 42 in Example 13-23, if you construct a reverse iterator that adapts iter, the reverse iterator appears to point to 29. When you increment the reverse iterator, it decrements the adapted iterator. Thus, the "next" element in the sequence of the reverse iterator is 12. (The adapted iterator points to 29.) The adapted iterator is also called the base iterator. See Chapter 10 for a discussion of some of the interesting ramifications of using reverse_iterator.

The following member functions of reverse_iterator refer to adapted as the data member that stores the base( ) iterator. The adapted member is actually named current, and is a protected data member of reverse_iterator:

reverse_iterator ( )

Initializes the adapted data member with its default constructor.

explicit reverse_iterator (Iterator iter)

Initializes the adapted data member to iter.

template <typename U> reverse_iterator (const reverse_iterator<U>& ri)

Initializes the adapted data member to ri.base( ).

Iterator base ( ) const

Returns the adapted iterator, adapted. Note that the adapted iterator points to one position after the reverse iterator's logical position.

reference operator *( ) const

Returns a reference to the item that the reverse iterator logically points to, which is one item before the item to which base( ) points. Thus, you can think of the dereference function working as follows:

reference operator*(  ) const {
  iterator_type tmp = base(  );
  --tmp;
  return *tmp;
}
pointer operator ->( ) const

Returns a pointer to the item that the reverse iterator logically points to, that is, &(operator*( )).

reverse_iterator& operator ++( )

Decrements adapted and returns *this.

reverse_iterator operator++ (int)

Saves a copy of (*this), decrements adapted, and returns the saved copy of *this.

reverse_iterator& operator --( )

Increments adapted and returns *this.

reverse_iterator operator-- (int)

Saves a copy of the current item (operator*( )), increments adapted, and returns the saved item.

reverse_iterator operator+ (difference_type n) const

Returns reverse_iterator(base( ) - n).

reverse_iterator& operator+= (difference_type n)

Subtracts n from adapted and returns *this.

reverse_iterator operator- (difference_type n) const

Returns reverse_iterator(base( ) + n).

reverse_iterator& operator-= (difference_type n)

Adds n to adapted and returns *this.

reference operator[] (difference_type n) const

Returns base( )[-n-1].

The following are several nonmember functions that compare reverse iterators and perform basic arithmetic such as finding the distance between two reverse iterators and advancing a reverse iterator by an integer:

template <typename Iterator>, bool operator== (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when the base iterators are equal, that is, x.base( ) == y.base( ).

template <typename Iterator>, bool operator!= (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when x and y have different base iterators, that is, x.base( ) != y.base( ).

template <typename Iterator>, bool operator< (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when x is closer than y to the beginning of the sequence. Because x and y are reverse iterators, the function returns y.base( ) < x.base( ).

template <typename Iterator>, bool operator> (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when x is farther than y from the beginning of the sequence. Because x and y are reverse iterators, the function returns y.base( ) > x.base( ).

template <typename Iterator>, bool operator>= (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when x is farther than y from the beginning of the sequence or x equals y. Because x and y are reverse iterators, the function returns y.base( ) >= x.base( ).

template <typename Iterator>, bool operator<= (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns true when x is closer than y to the beginning of the sequence or x equals y. Because x and y are reverse iterators, the function returns y.base( ) <= x.base( ).

template <typename Iterator>, typename reverse_iterator<Iterator>::difference_type, operator- (const reverse_iterator<Iterator>& x, const reverse_iterator<Iterator>& y)

Returns the distance between two reverse iterators, that is, y.base( ) - x.base( ).

template <typename Iter>, reverse_iterator<Iter>, operator+ (typename reverse_iterator<Iter>::difference_type n, constreverse_iterator<Iter>& ri)

Advances a reverse iterator ri by n. This function is a counterpart to the operator+ member function, allowing you to write ri + n and n + ri, which yield the same result.