# reverse_iterator<RandomAccessIterator, T, Reference, Distance>

Categories: iterators, adaptors | Component type: type

### Description

`Reverse_iterator` is an iterator adaptor that enables backwards traversal of a range. `Operator++` applied to an object of class `reverse_iterator<RandomAccessIterator>` means the same thing as `operator--` applied to an object of class `RandomAccessIterator`. There are two different reverse iterator adaptors: the class `reverse_iterator` has a template argument that is a Random Access Iterator, and the class `reverse_bidirectional_iterator` has a template argument that is a Bidirectional Iterator. [1]

### Example

    template <class T>
    void forw(const vector<T>& V)
    {
       vector<T>::iterator first = V.begin();
       vector<T>::iterator last = V.end();
       while (first != last)
          cout << *first++ << endl;
    }

    template <class T>
    void rev(const vector<T>& V)
    {
       typedef reverse_iterator<vector<T>::iterator,
                                T,
                                vector<T>::reference_type,
                                vector<T>::difference_type>
               reverse_iterator; [2]
       reverse_iterator rfirst(V.end());
       reverse_iterator rlast(V.begin());

       while (rfirst != rlast)
          cout << *rfirst++ << endl;
    }

In the function `forw`, the elements are printed in the order `*first`, `*(first+1)`, ..., `*(last-1)`. In the function `rev`, they are printed in the order `*(last - 1)`, `*(last-2)`, ..., `*first`. [3]

### Definition

Defined in the standard header iterator, and in the nonstandard backward-compatibility header iterator.h.

### Template parameters

Parameter | Description | Default
--- | --- | ---
`RandomAccessIterator` | The base iterator class. Incrementing an object of class `reverse_iterator<Iterator>` corresponds to decrementing an object of class `Iterator`. |
`T` | The reverse iterator's value type. This should always be the same as the base iterator's value type. |
`Reference` | The reverse iterator's reference type. This should always be the same as the base iterator's reference type. | `T&`
`Distance` | The reverse iterator's distance type. This should always be the same as the base iterator's distance type. | `ptrdiff_t`

### Model of

Random Access Iterator

### Type requirements

The base iterator type (that is, the template parameter `RandomAccessIterator`) must be a `Random Access Iterator`. The `reverse_iterator`'s value type, reference type, and distance type (that is, the template parameters `T`, `Reference`, and `Distance`, respectively) must be the same as the base iterator's value type, reference type, and distance type.

### Public base classes

None.

### Members

Member | Where defined | Description
--- | --- | ---
`self` | `reverse_iterator` | See below
`reverse_iterator()` | Trivial Iterator | The default constructor
`reverse_iterator(const reverse_iterator& x)` | Trivial Iterator | The copy constructor
`reverse_iterator& operator=(const reverse_iterator& x)` | Trivial Iterator | The assignment operator
`reverse_iterator(RandomAccessIterator x)` | `reverse_iterator` | See below.
`RandomAccessIterator base()` | `reverse_iterator` | See below.
`Reference operator*() const` | Trivial Iterator | The dereference operator
`reverse_iterator& operator++()` | Forward Iterator | Preincrement
`reverse_iterator operator++(int)` | Forward Iterator | Postincrement
`reverse_iterator& operator--()` | Bidirectional Iterator | Predecrement
`reverse_iterator operator--(int)` | Bidirectional Iterator | Postdecrement
`reverse_iterator operator+(Distance)` | Random Access Iterator | Iterator addition
`reverse_iterator& operator+=(Distance)` | Random Access Iterator | Iterator addition
`reverse_iterator operator-(Distance)` | Random Access Iterator | Iterator subtraction
`reverse_iterator& operator-=(Distance)` | Random Access Iterator | Iterator subtraction
`Reference operator[](Distance)` | Random Access Iterator | Random access to an element.
`reverse_iterator operator+(Distance, reverse_iterator)` | Random Access Iterator | Iterator addition. This is a global function, not a member function.
`Distance operator-(const reverse_iterator&, const reverse_iterator&)` | Random Access Iterator | Finds the distance between two iterators. This is a global function, not a member function.
`bool operator==(const reverse_iterator&, const reverse_iterator&)` | Trivial Iterator | Compares two iterators for equality. This is a global function, not a member function.
`bool operator<(const reverse_iterator&, const reverse_iterator&)` | Random Access Iterator | Determines whether the first argument precedes the second. This is a global function, not a member function.
`random_access_iterator_tag iterator_category(const reverse_iterator&)` | Iterator tags | Returns the iterator's category. This is a global function, not a member function.
`T* value_type(const reverse_iterator&)` | Iterator tags | Returns the iterator's value type. This is a global function, not a member function.
`Distance* distance_type(const reverse_iterator&)` | Iterator tags | Returns the iterator's distance type. This is a global function, not a member function.

### New members

These members are not defined in the Random Access Iterator requirements, but are specific to `reverse_iterator`.

Member | Description
--- | ---
`self` | A typedef for `reverse_iterator<RandomAccessIterator, T, Reference, Distance>`.
`RandomAccessIterator base()` | Returns the current value of the `reverse_iterator`'s base iterator. If `ri` is a reverse iterator and `i` is any iterator, the two fundamental identities of reverse iterators can be written as `reverse_iterator(i).base() == i` and `&*ri == &*(ri.base() - 1)`.
`reverse_iterator(RandomAccessIterator i)` | Constructs a `reverse_iterator` whose base iterator is `i`.

### Notes

[1] There isn't really any good reason to have two separate classes: this separation is purely because of a technical limitation in some of today's C++ compilers. If the two classes were combined into one, then there would be no way to declare the return types of the iterator tag functions `iterator_category`, `distance_type` and `value_type` correctly. The iterator traits class solves this problem: it addresses the same issues as the iterator tag functions, but in a cleaner and more flexible manner. Iterator traits, however, rely on partial specialization, and many C++ compilers do not yet implement partial specialization. Once compilers that support partial specialization become more common, these two different reverse iterator classes will be combined into a single class.

[2] The declarations for `rfirst` and `rlast` are written in this clumsy form simply as an illustration of how to declare a `reverse_iterator`. `Vector` is a Reversible Container, so it provides a typedef for the appropriate instantiation of `reverse_iterator`. The usual way of declaring these variables is much simpler:

        vector<T>::reverse_iterator rfirst = rbegin();
        vector<T>::reverse_iterator rlast = rend();

[3] Note the implications of this remark. The variable `rfirst` is initialized as `reverse_iterator<...> rfirst(V.end());`. The value obtained when it is dereferenced, however, is `*(V.end() - 1)`. This is a general property: the fundamental identity of reverse iterators is `&*(reverse_iterator(i)) == &*(i - 1)`. This code sample shows why this identity is important: if `[f, l)` is a valid range, then it allows `[reverse_iterator(l), reverse_iterator(f))` to be a valid range as well. Note that the iterator `l` is not part of the range, but it is required to be dereferenceable or past-the-end. There is no requirement that any such iterator precedes `f`.

### See also

Reversible Container, reverse_bidirectional_iterator, Random Access Iterator, iterator tags, Iterator Overview

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation