__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 support partial specialization. The template signature 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 collections in the opposite direction. The fundamental relationship 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 (--current) 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 iterators 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 (--current) 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 iterators 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 iterator 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==