diff --git a/reverse_iterator.htm b/reverse_iterator.htm new file mode 100644 index 0000000..50d41a7 --- /dev/null +++ b/reverse_iterator.htm @@ -0,0 +1,232 @@ + + + + + + +Reverse Iterator Adaptor Documentation + + + + +c++boost.gif (8819 bytes) + +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription
BidirectionalIteratorThe iterator type being wrapped.
ValueThe value-type of the base iterator and the resulting reverse iterator.
+Default:std::iterator_traits<BidirectionalIterator>::value_type +
ReferenceThe corresponding reference type for the value_type.
+Default:std::iterator_traits<BidirectionalIterator>::reference +
PointerThe pointer type for the value_type.
+Default:std::iterator_traits<BidirectionalIterator>::pointer +
CategoryThe iterator category.
+Default:std::iterator_traits<BidirectionalIterator>::iterator_category +
DistanceThe 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.

+ + + + + + + diff --git a/reverse_iterator_example.cpp b/reverse_iterator_example.cpp new file mode 100644 index 0000000..40c859f --- /dev/null +++ b/reverse_iterator_example.cpp @@ -0,0 +1,42 @@ +// (C) Copyright Jeremy Siek 2000. Permission to copy, use, modify, sell and +// distribute this software is granted provided this copyright notice appears +// in all copies. This software is provided "as is" without express or implied +// warranty, and with no claim as to its suitability for any purpose. + +#include +#include +#include +#include + +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::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(std::cout)); + std::cout << std::endl; + + // Use make_reverse_iterator() to print the sequence + // of letters in reverse-reverse order. + + 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; +}