__reverse_bi_iterator(3C++) - __reverse_bi_iterator(3C++)
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 sup‐
port partial specialization. The template signature for reverse_itera‐
tor 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 collections in the opposite direction. The fundamental rela‐
tionship between a reverse iterator and its corresponding iterator 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:
· 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.
· operator* returns a reference to the current value.
· operator++ advances the iterator to the previous item (--current)
and returns a reference to *this.
· operator++(int) advances the iterator to the previous item (--cur‐
rent) and returns the old value of *this.
· operator-- advances the iterator to the following item (++current)
and returns a reference to *this.
· operator--(int) advances the iterator to the following item
(++current) and returns the old value of *this.
· operator== is a non-member operator that returns true if the iter‐
ators x and y point to the same item.
The following are true for reverse_iterators:
· 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.
· operator* returns a reference to the current value.
· operator++ advances the iterator to the previous item (--current)
and returns a reference to *this.
· operator++(int) advances the iterator to the previous item (--cur‐
rent) and returns the old value of *this.
· operator-- advances the iterator to the following item (++current)
and returns a reference to *this.
· operator--(int) advances the iterator to the following item
(++current) and returns the old value of *this.
· operator== is a non-member operator that returns true if the iter‐
ators x and y point to the same item.
· operator!= is a non-member operator that returns !(x==y).
· operator< is a non-member operator that returns true if the itera‐
tor x precedes the iterator y.
· operator> is a non-member operator that returns y < x.
· operator<= is a non-member operator that returns !(y < x).
· operator>= is a non-member operator that returns !(x < y).
· The remaining operators (<, +, -, +=, -=) are redefined to behave
exactly as they would in a random_access_iterator, except with the
sense of direction reversed.
COMPLEXITY
All iterator operations are required to take at most amortized 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 OutputTraversing 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 parameters, 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
Rogue Wave Software 02 Apr 1998 __reverse_bi_iterator(3C++)