some progress on transform_iterator

[SVN r21612]

doc/filter_iterator_ref.rst

@@ -151,4 +151,4 @@ operations.
 :Effects: Increments ``*this`` and then continues to
   increment ``*this`` until either ``this->base() == this->end()``
   or ``f(**this) == true``.
-  
+:Returns: ``*this``  

doc/transform_iterator.html

@@ -49,8 +49,9 @@ then returns the result.</p>
 <p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
 <ul class="simple">
 <li><a class="reference" href="#transform-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">transform_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#transform-iterator-public-operations" id="id2" name="id2"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></li>
+<li><a class="reference" href="#transform-iterator-models" id="id2" name="id2"><tt class="literal"><span class="pre">transform_iterator</span></tt> models</a></li>
-<li><a class="reference" href="#transform-iterator-private-operations" id="id3" name="id3"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></li>
+<li><a class="reference" href="#transform-iterator-operations" id="id3" name="id3"><tt class="literal"><span class="pre">transform_iterator</span></tt> operations</a></li>
+<li><a class="reference" href="#example" id="id4" name="id4">Example</a></li>
 </ul>
 </div>
 <!-- Version 1.3 of this document was accepted for TR1 -->
@@ -60,9 +61,7 @@ template &lt;class UnaryFunction,
           class Reference = use_default, 
           class Value = use_default&gt;
 class transform_iterator
-  : public iterator_adaptor&lt;/* see discussion */&gt;
 {
-  friend class iterator_core_access;
 public:
   transform_iterator();
   transform_iterator(Iterator const&amp; x, UnaryFunction f);
@@ -74,10 +73,13 @@ public:
       , typename enable_if_convertible&lt;F2, UnaryFunction&gt;::type* = 0 // exposition
   );
 
+  reference operator*() const;
+  transform_iterator&amp; operator++();
+  Iterator base() const;
   UnaryFunction functor() const;
 private:
-  typename transform_iterator::value_type dereference() const;
+  Iterator m_iterator; // exposition
-  UnaryFunction m_f;
+  UnaryFunction m_f;   // exposition
 };
 </pre>
 <div class="section" id="transform-iterator-requirements">
@@ -87,8 +89,11 @@ the expression <tt class="literal"><span class="pre">f(*i)</span></tt> must be v
 type <tt class="literal"><span class="pre">UnaryFunction</span></tt>, <tt class="literal"><span class="pre">i</span></tt> is an object of type <tt class="literal"><span class="pre">Iterator</span></tt>, and
 where the type of <tt class="literal"><span class="pre">f(*i)</span></tt> must be
 <tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.</p>
-<p>The type <tt class="literal"><span class="pre">Iterator</span></tt> must at least model Readable Iterator.  The
+<p>The type <tt class="literal"><span class="pre">Iterator</span></tt> must at least model Readable Iterator.</p>
-resulting <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
+</div>
+<div class="section" id="transform-iterator-models">
+<h1><a class="toc-backref" href="#id2" name="transform-iterator-models"><tt class="literal"><span class="pre">transform_iterator</span></tt> models</a></h1>
+<p>The resulting <tt class="literal"><span class="pre">transform_iterator</span></tt> models the most refined of the
 following options that is also modeled by <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
 <blockquote>
 <ul class="simple">
@@ -104,8 +109,8 @@ concept that is modeled by <tt class="literal"><span class="pre">Iterator</span>
 <tt class="literal"><span class="pre">result_of&lt;UnaryFunction(iterator_traits&lt;Iterator&gt;::reference)&gt;::type</span></tt>.
 The <tt class="literal"><span class="pre">value_type</span></tt> is <tt class="literal"><span class="pre">remove_cv&lt;remove_reference&lt;reference&gt;</span> <span class="pre">&gt;::type</span></tt>.</p>
 </div>
-<div class="section" id="transform-iterator-public-operations">
+<div class="section" id="transform-iterator-operations">
-<h1><a class="toc-backref" href="#id2" name="transform-iterator-public-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> public operations</a></h1>
+<h1><a class="toc-backref" href="#id3" name="transform-iterator-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> operations</a></h1>
 <p><tt class="literal"><span class="pre">transform_iterator();</span></tt></p>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
@@ -143,6 +148,15 @@ transform_iterator(
 </tr>
 </tbody>
 </table>
+<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span></tt></td>
+</tr>
+</tbody>
+</table>
 <p><tt class="literal"><span class="pre">UnaryFunction</span> <span class="pre">functor()</span> <span class="pre">const;</span></tt></p>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
@@ -152,19 +166,90 @@ transform_iterator(
 </tr>
 </tbody>
 </table>
-</div>
+<p><tt class="literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
-<div class="section" id="transform-iterator-private-operations">
-<h1><a class="toc-backref" href="#id3" name="transform-iterator-private-operations"><tt class="literal"><span class="pre">transform_iterator</span></tt> private operations</a></h1>
-<p><tt class="literal"><span class="pre">typename</span> <span class="pre">transform_iterator::value_type</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
 <table class="field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_f(transform_iterator::dereference());</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_f(*m_iterator)</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="literal"><span class="pre">transform_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">++m_iterator</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<pre class="literal-block">
+template &lt;class UnaryFunction, class Iterator&gt;
+transform_iterator&lt;UnaryFunction, Iterator&gt;
+make_transform_iterator(Iterator it, UnaryFunction fun);
+</pre>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">transform_iterator&lt;UnaryFunction,</span> <span class="pre">Iterator&gt;</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
+initialized to <tt class="literal"><span class="pre">f</span></tt> and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+<pre class="literal-block">
+template &lt;class UnaryFunction, class Iterator&gt;
+transform_iterator&lt;UnaryFunction, Iterator&gt;
+make_transform_iterator(Iterator it);
+</pre>
+<table class="field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">transform_iterator</span></tt> with <tt class="literal"><span class="pre">m_f</span></tt>
+default constructed and <tt class="literal"><span class="pre">m_iterator</span></tt> initialized to <tt class="literal"><span class="pre">x</span></tt>.</td>
 </tr>
 </tbody>
 </table>
 </div>
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id4" name="example">Example</a></h1>
+<p>This is a simple example of using the transform_iterators class to
+generate iterators that multiply (or add to) the value returned by
+dereferencing the iterator. It would be cooler to use lambda library
+in this example.</p>
+<pre class="literal-block">
+int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
+const int N = sizeof(x)/sizeof(int);
+
+typedef boost::binder1st&lt; std::multiplies&lt;int&gt; &gt; Function;
+typedef boost::transform_iterator&lt;Function, int*&gt; doubling_iterator;
+
+doubling_iterator i(x, boost::bind1st(std::multiplies&lt;int&gt;(), 2)),
+  i_end(x + N, boost::bind1st(std::multiplies&lt;int&gt;(), 2));
+
+std::cout &lt;&lt; &quot;multiplying the array by 2:&quot; &lt;&lt; std::endl;
+while (i != i_end)
+  std::cout &lt;&lt; *i++ &lt;&lt; &quot; &quot;;
+std::cout &lt;&lt; std::endl;
+
+std::cout &lt;&lt; &quot;adding 4 to each element in the array:&quot; &lt;&lt; std::endl;
+std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus&lt;int&gt;(), 4)),
+          boost::make_transform_iterator(x + N, boost::bind1st(std::plus&lt;int&gt;(), 4)),
+          std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
+std::cout &lt;&lt; std::endl;
+</pre>
+<p>The output is:</p>
+<pre class="literal-block">
+multiplying the array by 2:
+2 4 6 8 10 12 14 16 
+adding 4 to each element in the array:
+5 6 7 8 9 10 11 12
+</pre>
+</div>
 </div>
 </body>
 </html>

doc/transform_iterator.rst

@@ -21,3 +21,5 @@
 .. contents:: Table of Contents
 
 .. include:: transform_iterator_ref.rst
+.. include:: make_transform_iterator.rst
+.. include:: transform_iterator_eg.rst

doc/transform_iterator_ref.rst

@@ -7,9 +7,7 @@
             class Reference = use_default, 
             class Value = use_default>
   class transform_iterator
-    : public iterator_adaptor</* see discussion */>
   {
-    friend class iterator_core_access;
   public:
     transform_iterator();
     transform_iterator(Iterator const& x, UnaryFunction f);
@@ -21,15 +19,18 @@
         , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition
     );
 
+    reference operator*() const;
+    transform_iterator& operator++();
+    Iterator base() const;
     UnaryFunction functor() const;
   private:
-    typename transform_iterator::value_type dereference() const;
+    Iterator m_iterator; // exposition
-    UnaryFunction m_f;
+    UnaryFunction m_f;   // exposition
   };
 
 
 ``transform_iterator`` requirements
-...................................
+-----------------------------------
 
 The type ``UnaryFunction`` must be Assignable, Copy Constructible, and
 the expression ``f(*i)`` must be valid where ``f`` is an object of
@@ -37,8 +38,13 @@ type ``UnaryFunction``, ``i`` is an object of type ``Iterator``, and
 where the type of ``f(*i)`` must be
 ``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
 
-The type ``Iterator`` must at least model Readable Iterator.  The
+The type ``Iterator`` must at least model Readable Iterator.  
-resulting ``transform_iterator`` models the most refined of the
+
+
+``transform_iterator`` models
+-----------------------------
+
+The resulting ``transform_iterator`` models the most refined of the
 following options that is also modeled by ``Iterator``.
 
   * Writable Lvalue Iterator if ``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type`` is a non-const reference. 
@@ -56,9 +62,9 @@ The ``reference`` type of ``transform_iterator`` is
 ``result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
 The ``value_type`` is ``remove_cv<remove_reference<reference> >::type``.
 
-``transform_iterator`` public operations
-........................................
 
+``transform_iterator`` operations
+---------------------------------
 
 ``transform_iterator();``
 
@@ -83,14 +89,24 @@ The ``value_type`` is ``remove_cv<remove_reference<reference> >::type``.
 :Returns: An instance of ``transform_iterator`` that is a copy of ``t``.
 :Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
 
+
+``Iterator base() const;``
+
+:Returns: ``m_iterator``
+
+
 ``UnaryFunction functor() const;``
 
 :Returns: ``m_f``
 
-``transform_iterator`` private operations
-.........................................
 
-``typename transform_iterator::value_type dereference() const;``
+``reference operator*() const;``
 
-:Returns: ``m_f(transform_iterator::dereference());``
+:Returns: ``m_f(*m_iterator)``
+
+
+``transform_iterator& operator++();``
+
+:Effects: ``++m_iterator``
+:Returns: ``*this``