From c8fbca2d44b893f4b853e38f2d4d24875fe43527 Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Fri, 24 Nov 2000 21:31:43 +0000 Subject: [PATCH] added docs for projection iterator [SVN r8322] --- iterator_adaptors.htm | 152 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 144 insertions(+), 8 deletions(-) diff --git a/iterator_adaptors.htm b/iterator_adaptors.htm index 8f6323c..dcfa62e 100644 --- a/iterator_adaptors.htm +++ b/iterator_adaptors.htm @@ -13,7 +13,9 @@ align="center" width="277" height="86">

Header -boost/iterator_adaptors.hpp

+boost/iterator_adaptors.hpp +and +boost/integer_range.hpp

The file boost/iterator_adaptors.hpp includes the main iterator_adaptors class and several other classes @@ -26,6 +28,13 @@ for constructing commonly used iterator adaptors.

  • Indirect Iterator Adaptors
  • Projection Iterator Adaptors
  • reverse_iterators + + +

    The file boost/integer_range.hpp includes a class that + uses iterator adaptors to create an iterator that increments over a + range of integers. The file also includes a "container" type + that creates a container-interface for the range of integers. +

    @@ -168,12 +177,11 @@ constructors. This is the class used inside of the iterator_adaptors type generator. Use this class directly (instead of using -iterator_adaptors) when there is no difference between the -const and non-const versions of the iterator type. Often this is -because there is only a const (read-only) version of the iterator, as -is the case for std::set's iterators. Use the same type for -the Iterator and NonconstIterator template -arguments. +iterator_adaptors) when you are interested in creating only +one of the iterator types (either const or non-const) or when there is +no difference between the const and non-const versions of the iterator +type (often this is because there is only a const (read-only) version +of the iterator, as is the case for std::set's iterators).

    @@ -223,6 +231,7 @@ href="#2">[2]. template <class AdaptableUnaryFunction> struct transform_iterator_policies : public default_iterator_policies { + transform_iterator_policies() { } transform_iterator_policies(const AdaptableUnaryFunction& f) : m_f(f) { } template <class Reference, class Iterator> @@ -422,6 +431,133 @@ struct indirect_iterators

    The Projection Iterator Adaptors

    +The projection iterator adaptor is very similar to the transform +iterator, except for a subtle difference in the return type: the +tranform iterator returns the result of the unary function by value, +whereas the projection iterator returns the result by reference. +Therefore, these two adaptors cater to different kinds of unary +functions. Transform iterator caters to functions that create new +objects, whereas projection iterator caters to a function that somehow +obtains a reference to an object that already exists. An example of a +unary function that is suitable for use with the projection adaptor is +select1st_: + +

    +

    +
    +
    +template <class Pair>
+struct select1st_ 
+  : public std::unary_function<Pair, typename Pair::first_type>
+{
+  const typename Pair::first_type& operator()(const Pair& x) const {
+    return x.first;
+  }
+  typename Pair::first_type& operator()(Pair& x) const {
+    return x.first;
+  }
+};
+
    + +The implementation of projection iterator is as follows. First, the +policies class is the same as the transform iterator's policies class. + +

    + +
    +
    +template <class AdaptableUnaryFunction>
+struct projection_iterator_policies : public default_iterator_policies
+{
+    projection_iterator_policies() { }
+    projection_iterator_policies(const AdaptableUnaryFunction& f) : m_f(f) { }
+
+    template <class Reference, class Iterator>
+    Reference dereference (type<Reference>, Iterator const& iter) const {
+        return m_f(*iter);
+    }
+
+    AdaptableUnaryFunction m_f;    
+};
+
    + +Next we have two traits classes. We use value_type& for the +reference type of the mutable projection iterator, and const +value_type& for the immutable projection iterator. + +

    + +
    +
    +template <class AdaptableUnaryFunction, class Traits>
+struct projection_iterator_traits {
+    typedef typename AdaptableUnaryFunction::result_type value_type;
+    typedef value_type& reference;
+    typedef value_type* pointer;
+    typedef typename Traits::difference_type difference_type;
+    typedef typename Traits::iterator_category iterator_category;
+};
+
+template <class AdaptableUnaryFunction, class Traits>
+struct const_projection_iterator_traits {
+    typedef typename AdaptableUnaryFunction::result_type value_type;
+    typedef value_type const& reference;
+    typedef value_type const* pointer;
+    typedef typename Traits::difference_type difference_type;
+    typedef typename Traits::iterator_category iterator_category;
+};
+
    + +And to finish up, we create three generator classes that +use iterator_adaptor to create the projection iterator +types. The class projection_iterator creates a mutable +projection iterator type. The class const_projection_iterator +creates an immutable projection iterator type, and +projection_iterators creates both mutable and immutable +projection iterator types. + +

    + +
    +
    +template <class AdaptableUnaryFunction, class Iterator,
+          class Traits = std::iterator_traits<Iterator>
+         >
+struct projection_iterator {
+    typedef projection_iterator_traits<AdaptableUnaryFunction, Traits>
+            Projection_Traits;
+    typedef iterator_adaptor<Iterator,
+            projection_iterator_policies<AdaptableUnaryFunction>,
+            Projection_Traits> type;
+};
+
+template <class AdaptableUnaryFunction, class Iterator,
+          class Traits = std::iterator_traits<Iterator>
+         >
+struct const_projection_iterator {
+    typedef const_projection_iterator_traits<AdaptableUnaryFunction,
+            Traits> Projection_Traits;
+    typedef iterator_adaptor<Iterator,
+            projection_iterator_policies<AdaptableUnaryFunction>,
+            Projection_Traits> type;
+};
+
+template <class AdaptableUnaryFunction, class Iterator, class ConstIterator,
+          class Traits = std::iterator_traits<Iterator>,
+          class ConstTraits = std::iterator_traits<ConstIterator>
+         >
+struct projection_iterators {
+    typedef projection_iterator_traits<AdaptableUnaryFunction, Traits>
+            Projection_Traits;
+    typedef const_projection_iterator_traits<AdaptableUnaryFunction,
+            ConstTraits> Const_Projection_Traits;
+    typedef iterator_adaptors<Iterator, ConstIterator,
+            Projection_Traits, Const_Projection_Traits,
+            projection_iterator_policies<AdaptableUnaryFunction> > Adaptors;
+    typedef typename Adaptors::iterator iterator;
+    typedef typename Adaptors::const_iterator const_iterator;
+};
+

    The Reverse Iterators Class

    @@ -538,9 +674,9 @@ iterator. 
    +template <class IntegerType>
 struct counting_iterator_policies : public default_iterator_policies
 {
-  template <class IntegerType>
   IntegerType dereference(type<IntegerType>, const IntegerType& i) const
     { return i; }
 };