| Home | Libraries | People | FAQ | More

### Reverse Iterator

The reverse iterator adaptor iterates through the adapted iterator range in the opposite direction.

### Example

The following example prints an array of characters in reverse order using `reverse_iterator`.

    char letters_[] = "hello world!";
    const int N = sizeof(letters_)/sizeof(char) - 1;
    typedef char* base_iterator;
    base_iterator letters(letters_);
    std::cout << "original sequence of letters:\t\t\t" << letters_ << std::endl;

    boost::reverse_iterator<base_iterator>
      reverse_letters_first(letters + N),
      reverse_letters_last(letters);

    std::cout << "sequence in reverse order:\t\t\t";
    std::copy(reverse_letters_first, reverse_letters_last,
              std::ostream_iterator<char>(std::cout));
    std::cout << std::endl;

    std::cout << "sequence in double-reversed (normal) order:\t";
    std::copy(boost::make_reverse_iterator(reverse_letters_last),
              boost::make_reverse_iterator(reverse_letters_first),
              std::ostream_iterator<char>(std::cout));
    std::cout << std::endl;

The output is:

    original sequence of letters:                   hello world!
    sequence in reverse order:                      !dlrow olleh
    sequence in double-reversed (normal) order:     hello world!

The source code for this example can be found here.

### Reference

#### Synopsis

    template <class Iterator>
    class reverse_iterator
    {
    public:
      typedef iterator_traits<Iterator>::value_type value_type;
      typedef iterator_traits<Iterator>::reference reference;
      typedef iterator_traits<Iterator>::pointer pointer;
      typedef iterator_traits<Iterator>::difference_type difference_type;
      typedef /* see below */ iterator_category;

      reverse_iterator() {}
      explicit reverse_iterator(Iterator x) ;

      template<class OtherIterator>
      reverse_iterator(
          reverse_iterator<OtherIterator> const& r
        , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
      );
      Iterator const& base() const;
      reference operator*() const;
      reverse_iterator& operator++();
      reverse_iterator& operator--();
    private:
      Iterator m_iterator; // exposition
    };

If `Iterator` models Random Access Traversal Iterator and Readable Lvalue Iterator, then `iterator_category` is convertible to `random_access_iterator_tag`. Otherwise, if `Iterator` models Bidirectional Traversal Iterator and Readable Lvalue Iterator, then `iterator_category` is convertible to `bidirectional_iterator_tag`. Otherwise, `iterator_category` is convertible to `input_iterator_tag`.

#### Requirements

`Iterator` must be a model of Bidirectional Traversal Iterator. The type `iterator_traits<Iterator>::reference` must be the type of `*i`, where `i` is an object of type `Iterator`.

#### Concepts

A specialization of `reverse_iterator` models the same iterator traversal and iterator access concepts modeled by its `Iterator` argument. In addition, it may model old iterator concepts specified in the following table:

Table 1.15. Categories

If `I` models | then `reverse_iterator<I>` models
--- | ---
Readable Lvalue Iterator, Bidirectional Traversal Iterator | Bidirectional Iterator
Writable Lvalue Iterator, Bidirectional Traversal Iterator | Mutable Bidirectional Iterator
Readable Lvalue Iterator, Random Access Traversal Iterator | Random Access Iterator
Writable Lvalue Iterator, Random Access Traversal Iterator | Mutable Random Access Iterator

`reverse_iterator<X>` is interoperable with `reverse_iterator<Y>` if and only if `X` is interoperable with `Y`.

#### Operations

In addition to the operations required by the concepts modeled by `reverse_iterator`, `reverse_iterator` provides the following operations.

    reverse_iterator();

Requires: `Iterator` must be Default Constructible.
Effects: Constructs an instance of `reverse_iterator` with `m_iterator` default constructed.

    explicit reverse_iterator(Iterator x);

Effects: Constructs an instance of `reverse_iterator` with `m_iterator` copy constructed from `x`.

    template<class OtherIterator>
    reverse_iterator(
        reverse_iterator<OtherIterator> const& r
      , typename enable_if_convertible<OtherIterator, Iterator>::type* = 0 // exposition
    );

Requires: `OtherIterator` is implicitly convertible to `Iterator`.
Effects: Constructs instance of `reverse_iterator` whose `m_iterator` subobject is constructed from `y.base()`.

    Iterator const& base() const;

Returns: `m_iterator`

    reference operator*() const;

Effects: Iterator tmp = m_iterator; return *--tmp;

    reverse_iterator& operator++();

Effects: `--m_iterator`
Returns: `*this`

    reverse_iterator& operator--();

Effects: `++m_iterator`
Returns: `*this`