add generator iterator adaptor

[SVN r11736]
2025-05-08 18:34:02 +00:00 · 2001-11-19 22:11:51 +00:00 · 2001-11-19 22:11:51 +00:00 · 3e9d0f80c2
commit 3e9d0f80c2
parent a2c4d1990a
3 changed files with 177 additions and 1 deletions
--- a/generator_iterator.htm
+++ b/generator_iterator.htm
@ -0,0 +1,150 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
+
+<html>
+<head>
+<title>Generator Iterator Adaptor Documentation</title>
+</head>
+
+<body bgcolor="#FFFFFF" text="#000000">
+        
+<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86"> 
+
+<h1>Generator Iterator Adaptor</h1>
+Defined in header <a href="../../boost/generator_iterator.hpp">boost/generator_iterator.hpp</a> 
+<p>
+The generator iterator adaptor makes it easier to create custom input
+iterators from 0-ary functions and function objects.  The adaptor
+takes a
+<a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a>
+and creates a model of
+<a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>.
+Each increment retrieves an item from the generator and makes it
+available to be retrieved by dereferencing.  The motivation for this
+iterator is that some concepts can be more naturally expressed as a
+generator, while most STL algorithms expect an iterator.  An example
+is the <a href="../random/index.html">Random Number</a> library.
+
+<h2>Synopsis</h2>
+
+<blockquote>
+<pre>
+namespace boost {
+  template &lt;class Generator&gt;
+  class generator_iterator_policies;
+
+  template &lt;class Generator&gt;
+  class generator_iterator_generator;
+
+  template &lt;class Generator&gt;
+  typename generator_iterator_generator&lt;Generator&gt;::type
+  make_generator_iterator(Generator &amp; gen);
+}
+</pre>
+</blockquote>
+
+<hr>
+
+<h2>The Generator Iterator Generator Class</h2>
+
+The class generator_iterator_generator is a helper class whose purpose
+is to construct a generator iterator type. The template parameter for
+this class is the Generator function object type that is being
+wrapped.  The generator iterator adaptor only holds a reference (or
+pointer) to the function object, therefore the function object must
+outlive the generator iterator adaptor constructed from it.
+
+<pre>
+template &lt;class Generator>
+class generator_iterator_generator
+{
+public:
+  typedef <a href="iterator_adaptors.htm#iterator_adaptor">iterator_adaptor</a>&lt...&gt; type; // the resulting generator iterator type 
+}
+</pre>
+
+
+<h3>Template Parameters</h3>
+
+<table border>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+
+<tr>
+<td><tt><a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a></tt> 
+<td>The generator (0-ary function object) type being
+wrapped.  The return type of the function must be defined as
+<tt>Generator::result_type</tt>.  The function object must be a model
+of
+<a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a>.
+</td>
+</table>
+
+<h3>Concept Model</h3>
+The generator iterator class is a model of
+<a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>.
+
+<h3>Members</h3>
+The generator iterator implements the member functions
+and operators required of the
+<a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>
+concept.
+
+<br>
+
+<hr>
+<h2><a name="make_generator_iterator">The Generator Iterator Object Generator</a></h2>
+
+The <tt>make_generator_iterator()</tt> function provides a
+convenient way to create generator iterator objects. The function
+saves the user the trouble of explicitly writing out the iterator
+types.
+
+<blockquote>
+<pre>
+template &lt;class Generator&gt;
+typename generator_iterator_generator&lt;Generator&gt;::type
+make_function_output_iterator(Generator &amp; gen);
+</pre>
+</blockquote>
+
+<hr>
+
+
+<h3>Example</h3>
+
+The following program shows how <code>generator_iterator</code>
+transforms a generator into an input iterator.
+
+<blockquote>
+<pre>
+#include &lt;iostream>
+#include &lt;boost/generator_iterator.hpp>
+
+class my_generator
+{
+public:
+  typedef int result_type;
+  my_generator() : state(0) { }
+  int operator()() { return ++state; }
+private:
+  int state;
+};
+
+int main()
+{
+  my_generator gen;
+  boost::generator_iterator&lt;my_generator> it(gen);
+  for(int i = 0; i &lt; 10; ++i, ++it)
+    std::cout &lt;&lt; *it &lt;&lt; std::endl;
+}
+</pre>
+</blockquote>
+
+<hr>
+
+Written by Jens Maurer.
+
+</body>
+</html>
--- a/iterator_adaptor_test.cpp
+++ b/iterator_adaptor_test.cpp
@ -9,6 +9,7 @@
 //  See http://www.boost.org for most recent version including documentation.

 //  Revision History
+//  19 Nov 01 Added generator_iterator.  (Jens Maurer)
 //  04 Nov 01 Updated with respect to change in named parameters.
 //            (Jeremy Siek)
 //  08 Mar 01 Moved indirect and transform tests to separate files.
@ -51,6 +52,7 @@
 #include <functional>

 #include <boost/iterator_adaptors.hpp>
+#include <boost/generator_iterator.hpp>
 #include <boost/pending/iterator_tests.hpp>
 #include <boost/pending/integer_range.hpp>
 #include <boost/concept_archetype.hpp>
@ -105,6 +107,14 @@ template <class T> struct foo;

 void blah(int) { }

+struct my_gen
+{
+  typedef int result_type;
+  my_gen() : n(0) { }
+  int operator()() { return ++n; }
+  int n;
+};
+
 int
 main()
 {
@ -382,6 +392,18 @@ main()
    if (zero) // don't do this, just make sure it compiles
      assert((*i).m_x == i->foo());      
  }
+
+  {
+    // check generator_iterator
+    my_gen g1;
+    boost::generator_iterator_generator<my_gen>::type gen =
+      boost::make_generator_iterator(g1);
+    assert(*gen == 1);
+    ++gen;
+    gen++;
+    assert(*gen == 3);
+  }
+
  std::cout << "test successful " << std::endl;
  return 0;
 }
--- a/iterator_adaptors.htm
+++ b/iterator_adaptors.htm
@ -122,6 +122,8 @@
      "../../boost/function_output_iterator.hpp">boost/function_output_iterator.hpp</a></tt><br>

       <a href="function_output_iterator.htm">Function Output Iterator Adaptor</a>
+      <li>Header <tt><a href="../../boost/generator_iterator.hpp">boost/generator_iterator.hpp</a></tt><br>
+       <a href="generator_iterator.htm">Generator Iterator Adaptor</a>
    </ul>

    <p><b><a href="../../people/dave_abrahams.htm">Dave
@ -145,7 +147,9 @@
    "filter_iterator.htm">filter_</a></tt> iterator generators and made some
    simplifications to the main <tt><a href=
    "#iterator_adaptor">iterator_adaptor</a></tt> template.<br>
-
+    <b><a href="../../people/jens_maurer.htm">Jens Maurer</a></b>
+    contributed the <a href="generator_iterator.htm">generator iterator</a>
+    adaptor.<br>

    <h2><a name="iterator_adaptor">Class template</a>
    <tt>iterator_adaptor</tt></h2>