Reverse Iterator Adaptor

Defined in header boost/iterator_adaptors.hpp

The reverse iterator adaptor flips the direction of a base iterator's motion. Invoking operator++() moves the base iterator backward and invoking operator--() moves the base iterator forward. The Boost reverse iterator adaptor is better to use than the std::reverse_iterator class in situations where pairs of mutable/const iterators are needed (e.g., in containers) because comparisons and conversions between the mutable and const versions are implemented correctly.

Synopsis

namespace boost {
  template <class BidirectionalIterator,
            class Value, class Reference, class Pointer, class Category, class Distance>
  struct reverse_iterator_generator;
  
  template <class BidirectionalIterator>
  typename reverse_iterator_generator<BidirectionalIterator>::type
  make_reverse_iterator(BidirectionalIterator base)  
}

The Reverse Iterator Type Generator

The reverse_iterator_generator template is a generator of reverse iterator types. The main template parameter for this class is the base BidirectionalIterator type that is being adapted. In most cases the associated types of the base iterator can be deduced using std::iterator_traits, but in some situations the user may want to override these types, so there are also template parameters for the base iterator's associated types.

template <class BidirectionalIterator,
          class Value, class Reference, class Pointer, class Category, class Distance>
class reverse_iterator_generator
{
public:
  typedef iterator_adaptor<...> type; // the resulting reverse iterator type 
};

Example

In this example we sort a sequence of letters and then output the sequence in descending order using reverse iterators.

#include <boost/config.hpp>
#include <iostream>
#include <algorithm>
#include <boost/iterator_adaptors.hpp>

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

  std::sort(letters, letters + N);

  // Use reverse_iterator_generator to print a sequence
  // of letters in reverse order.
  
  boost::reverse_iterator_generator<char*>::type
    reverse_letters_first(letters + N),
    reverse_letters_last(letters);

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

  // to be continued...

The output is:

original sequence of letters: hello world!
letters in descending order:  wroolllhed!

Template Parameters

Parameter	Description
`BidirectionalIterator`	The iterator type being wrapped.
`Value`	The value-type of the base iterator and the resulting reverse iterator. Default:`std::iterator_traits<BidirectionalIterator>::value_type`
`Reference`	The `reference` type of the resulting iterator, and in particular, the result type of `operator()`. Default:* If `Value` is supplied, `Value&` is used. Otherwise `std::iterator_traits<BidirectionalIterator>::reference` is used.
`Pointer`	The `pointer` type of the resulting iterator, and in particular, the result type of `operator->()`. Default: If `Value` was supplied, then `Value*`, otherwise `std::iterator_traits<BidirectionalIterator>::pointer`.
`Category`	The `iterator_category` type for the resulting iterator. Default: `std::iterator_traits<BidirectionalIterator>::iterator_category`
`Distance`	The `difference_type` for the resulting iterator. Default: `std::iterator_traits<BidirectionalIterator&gt::difference_type`

Concept Model

The indirect iterator will model whichever standard iterator concept category is modeled by the base iterator. Thus, if the base iterator is a model of Random Access Iterator then so is the resulting indirect iterator. If the base iterator models a more restrictive concept, the resulting indirect iterator will model the same concept. The base iterator must be at least a Bidirectional Iterator

Members

The reverse iterator type implements the member functions and operators required of the Random Access Iterator concept. In addition it has the following constructor:

reverse_iterator_generator::type(const BidirectionalIterator& it)

The Reverse Iterator Object Generator

The make_reverse_iterator() function provides a more convenient way to create reverse iterator objects. The function saves the user the trouble of explicitly writing out the iterator types.

template <class BidirectionalIterator>
typename reverse_iterator_generator<BidirectionalIterator>::type
make_reverse_iterator(BidirectionalIterator base);

Example

In this part of the example we use make_reverse_iterator() to print the sequence of letters in reverse-reverse order, which is the original order.

  // continuing from the previous example...

  std::cout << "letters in ascending 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;

  return 0;
}

The output is:

letters in ascending order:  !dehllloorw

Revised 15 Feb 2001

© Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.