## __reverse_bi_iterator, reverse_iterator

    Iterator

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Complexity
- Interface
- Example
- Warnings
- See Also

### Summary

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).

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

None

### 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==
            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 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

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998