Gitiles
Code Review Sign In
realtimeroboticsgroup.org / RealtimeRoboticsGroup / test / 5962333b719c9a350394e8b3a2ddcc7c5d280c72 / . / doc / function_input_iterator.html
blob: e097a4671572136eeccf0d580ccc24d6b7e6cfef [file] [log] [blame]
Brian Silverman59623332018-08-04 23:36:56 -0700[diff] [blame^]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
28a nullary function object and a state object which tracks the number of times
29the 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
32that 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
33function object). Each increment of the function Function Input Iterator
34invokes the generator function and stores the value in the iterator. When
35the 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
38described 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-
42increment 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
43constructs 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">
68namespace {
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
84Function Input Iterator the type of the function to encapsulate and
85the 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
87control the type of the counter which determines whether two iterators
88are at the same state. This allows for creating a pair of iterators which
89bound 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
94in cases where we want to create bounded (lazy) generated ranges.</p>
95<pre class="literal-block">
96struct generator {
97 typedef int result_type;
98 generator() { srand(time(0)); }
99 result_type operator() () const {
100 return rand();
101 }
102};
103
104int 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>
115that 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
116of random numbers and encapsulate that in a pair of integers, we can do
117it with the <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> helper class.</p>
118<pre class="literal-block">
119copy(
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
126to traverse the function input iterator and call the function object f
127as it increments the iterator. The special property of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt>
128is that equating two instances always yield false -- and that incrementing
129an instance of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> doesn't do anything. This is an efficient
130way of stating that the iterator range provided by two iterators with an
131encapsulated 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>.
138Generated 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>