ceph/src/boost/libs/iterator/doc/function_input_iterator.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
   7 <title></title>
   8 <meta name="author" content="Dean Michael Berris" />
   9 <link rel="stylesheet" href="../../../rst.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document">
  13
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td><a class="first reference external" href="mailto:mikhailberis&#64;gmail.com">Dean Michael Berris</a></td></tr>
  20 <tr class="field"><th class="docinfo-name">License:</th><td class="field-body">Distributed under the Boost Software License, Version 1.0
  21 (See accompanying file LICENSE_1_0.txt or copy at <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
  22 </tr>
  23 </tbody>
  24 </table>
  25 <div class="section" id="function-input-iterator">
  26 <h1>Function Input Iterator</h1>
  27 <p>The Function Input Iterator allows for creating iterators that encapsulate
  28 a nullary function object and a state object which tracks the number of times
  29 the iterator has been incremented. A Function Input Iterator models the
  30 <a class="reference external" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> concept and is useful for creating bounded input iterators.</p>
  31 <p>Like the Generator Iterator, the Function Input Iterator takes a function
  32 that models the <a class="reference external" href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> concept (which is basically a nullary or 0-arity
  33 function object). Each increment of the function Function Input Iterator
  34 invokes the generator function and stores the value in the iterator. When
  35 the iterator is dereferenced the stored value is returned.</p>
  36 <p>The Function Input Iterator encapsulates a state object which models the
  37 <a class="reference internal" href="#incrementable-concept">Incrementable Concept</a> and the <a class="reference external" href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> Concept. These concepts are
  38 described below as:</p>
  39 <div class="section" id="incrementable-concept">
  40 <h2>Incrementable Concept</h2>
  41 <p>A type models the Incrementable Concept when it supports the pre- and post-
  42 increment operators. For a given object <tt class="docutils literal"><span class="pre">i</span></tt> with type <tt class="docutils literal"><span class="pre">I</span></tt>, the following
  43 constructs should be valid:</p>
  44 <table border="1" class="docutils">
  45 <colgroup>
  46 <col width="24%" />
  47 <col width="46%" />
  48 <col width="30%" />
  49 </colgroup>
  50 <tbody valign="top">
  51 <tr><td colspan="3">Construct  Description        Return Type</td>
  52 </tr>
  53 <tr><td>i++</td>
  54 <td>Post-increment i.</td>
  55 <td>I</td>
  56 </tr>
  57 <tr><td>++i</td>
  58 <td>Pre-increment i.</td>
  59 <td>I&amp;</td>
  60 </tr>
  61 </tbody>
  62 </table>
  63 <p>NOTE: An Incrementable type should also be <a class="reference external" href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>.</p>
  64 </div>
  65 <div class="section" id="synopsis">
  66 <h2>Synopsis</h2>
  67 <pre class="literal-block">
  68 namespace {
  69     template &lt;class Function, class State&gt;
  70     class function_input_iterator;
  71
  72     template &lt;class Function, class State&gt;
  73     typename function_input_iterator&lt;Function, State&gt;
  74     make_function_input_iterator(Function &amp; f);
  75
  76     struct infinite;
  77 }
  78 </pre>
  79 </div>
  80 <div class="section" id="function-input-iterator-class">
  81 <h2>Function Input Iterator Class</h2>
  82 <p>The class Function Input Iterator class takes two template parameters
  83 <tt class="docutils literal"><span class="pre">Function</span></tt> and <tt class="docutils literal"><span class="pre">State</span></tt>. These two template parameters tell the
  84 Function Input Iterator the type of the function to encapsulate and
  85 the type of the internal state value to hold.</p>
  86 <p>The <tt class="docutils literal"><span class="pre">State</span></tt> parameter is important in cases where you want to
  87 control the type of the counter which determines whether two iterators
  88 are at the same state. This allows for creating a pair of iterators which
  89 bound the range of the invocations of the encapsulated functions.</p>
  90 </div>
  91 <div class="section" id="examples">
  92 <h2>Examples</h2>
  93 <p>The following example shows how we use the function input iterator class
  94 in cases where we want to create bounded (lazy) generated ranges.</p>
  95 <pre class="literal-block">
  96 struct generator {
  97     typedef int result_type;
  98     generator() { srand(time(0)); }
  99     result_type operator() () const {
 100         return rand();
 101     }
 102 };
 103
 104 int main(int argc, char * argv[]) {
 105     generator f;
 106     copy(
 107             make_function_input_iterator(f, 0),
 108             make_function_input_iterator(f, 10),
 109             ostream_iterator&lt;int&gt;(cout, &quot; &quot;)
 110         );
 111     return 0;
 112 }
 113 </pre>
 114 <p>Here we can see that we've bounded the number of invocations using an <tt class="docutils literal"><span class="pre">int</span></tt>
 115 that counts from <tt class="docutils literal"><span class="pre">0</span></tt> to <tt class="docutils literal"><span class="pre">10</span></tt>. Say we want to create an endless stream
 116 of random numbers and encapsulate that in a pair of integers, we can do
 117 it with the <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> helper class.</p>
 118 <pre class="literal-block">
 119 copy(
 120         make_function_input_iterator(f,infinite()),
 121         make_function_input_iterator(f,infinite()),
 122         ostream_iterator&lt;int&gt;(count, &quot; &quot;)
 123     );
 124 </pre>
 125 <p>Above, instead of creating a huge vector we rely on the STL copy algorithm
 126 to traverse the function input iterator and call the function object f
 127 as it increments the iterator. The special property of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt>
 128 is that equating two instances always yield false -- and that incrementing
 129 an instance of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> doesn't do anything. This is an efficient
 130 way of stating that the iterator range provided by two iterators with an
 131 encapsulated infinite state will definitely be infinite.</p>
 132 </div>
 133 </div>
 134 </div>
 135 <div class="footer">
 136 <hr class="footer" />
 137 <a class="reference external" href="function_input_iterator.rst">View document source</a>.
 138 Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 139
 140 </div>
 141 </body>
 142 </html>