Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
__reverse_bi_iterator, reverse_iterator
- An iterator that traverses a collection backwards.
__reverse_bi_iterator is included for those compilers that
do not support partial specialization. The template signa-
ture for reverse_iterator matches that of
__reverse_bi_iterator when partial specialization is not
available (in other words, it has six template parameters
rather than one).
SYNOPSIS
#include <iterator>
template <class Iterator,
class Category,
class T,
class Reference = T&,
class Pointer = T*
class Distance = ptrdiff_t>
class __reverse_bi_iterator ;
template <class Iterator>
class reverse_iterator ;
DESCRIPTION
The iterators reverse_iterator and___reverse_bi_iterator
correspond to random_access_iterator and
bidirectional_iterator, except that they traverse collec-
tions in the opposite direction. The fundamental relation-
ship between a reverse iterator and its corresponding itera-
tor i is established by the identity:
&*(reverse_iterator(i)) == &*(i-1);
This mapping is dictated by the fact that, while there is
always a pointer past the end of a container, there might
not be a valid pointer before its beginning.
The following are true for __reverse_bi_iterators:
o These iterators may be instantiated with the default
constructor or by a single argument constructor that
initializes the new __reverse_bi_iterator with a
bidirectional_iterator.
o operator* returns a reference to the current value.
o operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
o operator++(int) advances the iterator to the previous
item (--current) and returns the old value of *this.
o operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
o operator--(int) advances the iterator to the following
item (++current) and returns the old value of *this.
o operator== is a non-member operator that returns true
if the iterators x and y point to the same item.
The following are true for reverse_iterators:
o These iterators may be instantiated with the default
constructor or by a single argument constructor that
initializes the new reverse_iterator with a
random_access_iterator.
o operator* returns a reference to the current value.
o operator++ advances the iterator to the previous item
(--current) and returns a reference to *this.
o operator++(int) advances the iterator to the previous
item (--current) and returns the old value of *this.
o operator-- advances the iterator to the following item
(++current) and returns a reference to *this.
o operator--(int) advances the iterator to the following
item (++current) and returns the old value of *this.
o operator== is a non-member operator that returns true
if the iterators x and y point to the same item.
o operator!= is a non-member operator that returns
!(x==y).
o operator< is a non-member operator that returns true if
the iterator x precedes the iterator y.
o operator> is a non-member operator that returns y < x.
o operator<= is a non-member operator that returns !(y <
x).
o operator>= is a non-member operator that returns !(x <
y).
o The remaining operators (<, +, -, +=, -=) are redefined
to behave exactly as they would in a
random_access_iterator, except with the sense of direc-
tion reversed.
COMPLEXITY
All iterator operations are required to take at most amor-
tized constant time.
INTERFACE
template <class Iterator,
class Category,
class T,
class Reference = T&,
class Pointer = T*,
class Distance = ptrdiff_t>
class __reverse_bi_iterator
: public iterator<bidirectional_iterator_tag, Category T,
Distance> {
typedef
__reverse_bi_iterator<Iterator,
Category T, Reference, Pointer, Distance> self;
friend bool operator== (const self&, const self&);
public:
__reverse_bi_iterator ();
explicit __reverse_bi_iterator
(Iterator);
Iterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
};
// Non-member Operators
template <class Iterator, class Category
class T, class Reference,
class Pointer, class Distance>
bool operator== (
const __reverse_bi_iterator
<Iterator,Category T,Reference,Pointer,Distance>&,
const __reverse_bi_iterator
<Iterator,Category T,Reference,Pointer,Distance>&);
template <class Iterator,
class T, class Reference, class Category,
class Pointer, class Distance>
bool operator!= (
const __reverse_bi_iterator
<Iterator,Category T,Reference,Pointer,Distance>&,
const __reverse_bi_iterator
<Iterator,Category T,Reference,Pointer,Distance>&);
template <class 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>
{
typedef reverse_iterator<Iterator> self;
friend bool operator== (const self&, const self&);
friend bool operator< (const self&, const self&);
friend Distance operator- (const self&, const self&);
friend self operator+ (Distance, const self&);
public:
reverse_iterator ();
explicit reverse_iterator (Iterator);
Iterator base ();
Reference operator* ();
self& operator++ ();
self operator++ (int);
self& operator-- ();
self operator-- (int);
self operator+ (Distance) const;
self& operator+= (Distance);
self operator- (Distance) const;
self& operator-= (Distance);
Reference operator[] (Distance);
};
// Non-member Operators
template <class Iterator> bool operator==
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> bool operator!=
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> bool operator< (
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> bool operator>
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> bool operator<=
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> bool operator>=
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator> Distance operator-
const reverse_iterator<Iterator>&,
const reverse_iterator<Iterator>&);
template <class Iterator>
reverse_iterator<Iterator> operator+ Distance,
const reverse_iterator<Iterator>&);
EXAMPLE
//
// rev_itr.cpp
//
#include <iterator>
#include <vector>
#include <iostream>
using namespace std;
int main()
{
//Initialize a vector using an array
int arr[4] = {3,4,7,8};
vector<int> v(arr,arr+4);
//Output the original vector
cout << "Traversing vector with iterator: " << endl
<< " ";
for(vector<int>::iterator i = v.begin(); i != v.end();
i++)
cout << *i << " ";
//Declare the reverse_iterator
vector<int>::reverse_iterator rev(v.end());
vector<int>::reverse_iterator rev_end(v.begin());
//Output the vector backwards
cout << endl << endl;
cout << "Same vector, same loop, reverse_iterator: "
<< endl << " ";
for(; rev != rev_end; rev++)
cout << *rev << " ";
return 0;
}
Program Output
Traversing vector with iterator:
3 4 7 8
Same vector, same loop, reverse_iterator:
8 7 4 3
WARNINGS
If your compiler does not support default template parame-
ters, then you always need to supply the Allocator template
argument. For instance, you need to write:
vector<int, allocator<int> >
instead of:
vector<int>
If your compiler does not support namespaces, then you do
not need the using declaration for std.
SEE ALSO
Iterators