reverse_iterator class template — Iterator wrapper to reverse direction
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.