]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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@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&</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 <class Function, class State> | |
70 | class function_input_iterator; | |
71 | ||
72 | template <class Function, class State> | |
73 | typename function_input_iterator<Function, State> | |
74 | make_function_input_iterator(Function & 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<int>(cout, " ") | |
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<int>(count, " ") | |
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> |