Reverse Iterator Adaptor

Defined in header boost/iterator_adaptors.hpp

The reverse iterator adaptor flips the direction of an iterators motion. Invoking operator++() moves the reverse iterator backwards and calling operator--() moves the reverse iterator forwards. 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 (such as 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 class reverse_iterator_generator is a helper class whose purpose is to construct a reverse iterator type. The main template parameter for this class is the BidirectionalIterator type that is being wrapped. 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 iterators associates 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 corresponding reference type for the `value_type`. Default:`std::iterator_traits<BidirectionalIterator>::reference`
`Pointer`	The pointer type for the `value_type`. Default:`std::iterator_traits<BidirectionalIterator>::pointer`
`Category`	The iterator category. Default:`std::iterator_traits<BidirectionalIterator>::iterator_category`
`Distance`	The corresponding pointer type for the `Value`. Default:`std::iterator_traits<BidirectionalIterator>::difference_type`

Model of

If the base iterator is a model of Random Access Iterator then so is the resulting reverse iterator. If the base iterator supports less functionality than this the resulting reverse iterator will also support less functionality. 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(std::cout));
  std::cout << std::endl;

  return 0;
}

The output is:

letters in ascending order:	 !dehllloorw

Revised 10 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.