From 964d23f68c7e23c1ba48b283fdde684cd462bdbb Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Fri, 16 Feb 2001 05:51:37 +0000 Subject: [PATCH] Edits for clarity [SVN r9224] --- reverse_iterator.htm | 312 ++++++++++++++++++++++--------------------- 1 file changed, 163 insertions(+), 149 deletions(-) diff --git a/reverse_iterator.htm b/reverse_iterator.htm index ec3d263..f7ea319 100644 --- a/reverse_iterator.htm +++ b/reverse_iterator.htm @@ -1,74 +1,74 @@ - + - - - - -Reverse Iterator Adaptor Documentation - + + + + - + Reverse Iterator Adaptor Documentation -c++boost.gif (8819 bytes) + c++boost.gif (8819 bytes) -

Reverse Iterator Adaptor

+

Reverse Iterator Adaptor

+ Defined in header boost/iterator_adaptors.hpp -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

+

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,
+  template <class BidirectionalIterator,
             class Value, class Reference, class Pointer, class Category, class Distance>
   struct reverse_iterator_generator;
   
-  template <class BidirectionalIterator>
+  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. +

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,
+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 
+  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. +

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>
@@ -80,7 +80,7 @@ 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;
+      << letters << std::endl;
 
   std::sort(letters, letters + N);
 
@@ -93,153 +93,167 @@ int main(int, char*[])
 
   std::cout << "letters in descending order:\t";
   std::copy(reverse_letters_first, reverse_letters_last,
-	    std::ostream_iterator<char>(std::cout));
+      std::ostream_iterator<char>(std::cout));
   std::cout << std::endl;
 
   // to be continued...
-The output is: +
+ The output is: + + 
-original sequence of letters:	hello world!
-letters in descending order:	wroolllhed! 
+original sequence of letters: hello world!
+letters in descending order:  wroolllhed!
+
-

Template Parameters

+

Template Parameters

- - - - +
ParameterDescription
+ + - - - - + - + + + - + + + - + + - + + - - + - - + +
Parameter -
BidirectionalIteratorThe iterator type being wrapped.
Description -
Value
BidirectionalIterator + -The value-type of the base iterator and the resulting reverse -iterator.
-Default:std::iterator_traits<BidirectionalIterator>::value_type -		The iterator type being wrapped. -
Reference
Value -The reference type for the resulting iterator, -and in particular, the result type of operator*() -Typically the default for this parameter is the appropriate type.
-Default: If Value is supplied, Value& is -used. Otherwise -std::iterator_traits<BidirectionalIterator>::reference is used. -		The value-type of the base iterator and the resulting reverse + iterator.
+ Default:std::iterator_traits<BidirectionalIterator>::value_type + -
Pointer
Reference -The pointer type of the resulting iterator, and in - particular, the result type of operator->(). Typically the - default for this parameter is the appropriate type.
- Default: If Value was supplied, then Value*. - Otherwise - std::iterator_traits<BidirectionalIterator>::pointer is used.
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 -
CategoryThe iterator category.
-Default:std::iterator_traits<BidirectionalIterator>::iterator_category -		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. -
DistanceThe corresponding pointer type for the Value.
-Default:std::iterator_traits<BidirectionalIterator>::difference_type -
Category + The iterator_category type for the resulting iterator.
+ Default: + std::iterator_traits<BidirectionalIterator>::iterator_category + -
+ + Distance -

Model of

+ The difference_type for the resulting iterator.
+ Default: + std::iterator_traits<BidirectionalIterator&gt::difference_type + + -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 +

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: +

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. +

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)  
+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. -

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::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;
+      boost::make_reverse_iterator(reverse_letters_first),
+      std::ostream_iterator<char>(std::cout));
+  std::cout << std::endl;
 
   return 0;
 }
-The output is: +
+ The output is: + + 
-letters in ascending order:	 !dehllloorw
+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.

+

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. + + + + - - - - -