Ticket #2893: function_input_iterator.html

File function_input_iterator.html, 11.9 KB (added by Dean Michael Berris, 14 years ago)

Function iterator documentation (HTML)

Line 
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.4.1: http://docutils.sourceforge.net/" />
7<title></title>
8<meta name="author" content="Dean Michael Berris" />
9<style type="text/css">
10
11/*
12:Author: David Goodger
13:Contact: goodger@users.sourceforge.net
14:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
15:Revision: $Revision: 4224 $
16:Copyright: This stylesheet has been placed in the public domain.
17
18Default cascading style sheet for the HTML output of Docutils.
19
20See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
21customize this style sheet.
22*/
23
24/* used to remove borders from tables and images */
25.borderless, table.borderless td, table.borderless th {
26 border: 0 }
27
28table.borderless td, table.borderless th {
29 /* Override padding for "table.docutils td" with "! important".
30 The right padding separates the table cells. */
31 padding: 0 0.5em 0 0 ! important }
32
33.first {
34 /* Override more specific margin styles with "! important". */
35 margin-top: 0 ! important }
36
37.last, .with-subtitle {
38 margin-bottom: 0 ! important }
39
40.hidden {
41 display: none }
42
43a.toc-backref {
44 text-decoration: none ;
45 color: black }
46
47blockquote.epigraph {
48 margin: 2em 5em ; }
49
50dl.docutils dd {
51 margin-bottom: 0.5em }
52
53/* Uncomment (and remove this text!) to get bold-faced definition list terms
54dl.docutils dt {
55 font-weight: bold }
56*/
57
58div.abstract {
59 margin: 2em 5em }
60
61div.abstract p.topic-title {
62 font-weight: bold ;
63 text-align: center }
64
65div.admonition, div.attention, div.caution, div.danger, div.error,
66div.hint, div.important, div.note, div.tip, div.warning {
67 margin: 2em ;
68 border: medium outset ;
69 padding: 1em }
70
71div.admonition p.admonition-title, div.hint p.admonition-title,
72div.important p.admonition-title, div.note p.admonition-title,
73div.tip p.admonition-title {
74 font-weight: bold ;
75 font-family: sans-serif }
76
77div.attention p.admonition-title, div.caution p.admonition-title,
78div.danger p.admonition-title, div.error p.admonition-title,
79div.warning p.admonition-title {
80 color: red ;
81 font-weight: bold ;
82 font-family: sans-serif }
83
84/* Uncomment (and remove this text!) to get reduced vertical space in
85 compound paragraphs.
86div.compound .compound-first, div.compound .compound-middle {
87 margin-bottom: 0.5em }
88
89div.compound .compound-last, div.compound .compound-middle {
90 margin-top: 0.5em }
91*/
92
93div.dedication {
94 margin: 2em 5em ;
95 text-align: center ;
96 font-style: italic }
97
98div.dedication p.topic-title {
99 font-weight: bold ;
100 font-style: normal }
101
102div.figure {
103 margin-left: 2em ;
104 margin-right: 2em }
105
106div.footer, div.header {
107 clear: both;
108 font-size: smaller }
109
110div.line-block {
111 display: block ;
112 margin-top: 1em ;
113 margin-bottom: 1em }
114
115div.line-block div.line-block {
116 margin-top: 0 ;
117 margin-bottom: 0 ;
118 margin-left: 1.5em }
119
120div.sidebar {
121 margin-left: 1em ;
122 border: medium outset ;
123 padding: 1em ;
124 background-color: #ffffee ;
125 width: 40% ;
126 float: right ;
127 clear: right }
128
129div.sidebar p.rubric {
130 font-family: sans-serif ;
131 font-size: medium }
132
133div.system-messages {
134 margin: 5em }
135
136div.system-messages h1 {
137 color: red }
138
139div.system-message {
140 border: medium outset ;
141 padding: 1em }
142
143div.system-message p.system-message-title {
144 color: red ;
145 font-weight: bold }
146
147div.topic {
148 margin: 2em }
149
150h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
151h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
152 margin-top: 0.4em }
153
154h1.title {
155 text-align: center }
156
157h2.subtitle {
158 text-align: center }
159
160hr.docutils {
161 width: 75% }
162
163img.align-left {
164 clear: left }
165
166img.align-right {
167 clear: right }
168
169ol.simple, ul.simple {
170 margin-bottom: 1em }
171
172ol.arabic {
173 list-style: decimal }
174
175ol.loweralpha {
176 list-style: lower-alpha }
177
178ol.upperalpha {
179 list-style: upper-alpha }
180
181ol.lowerroman {
182 list-style: lower-roman }
183
184ol.upperroman {
185 list-style: upper-roman }
186
187p.attribution {
188 text-align: right ;
189 margin-left: 50% }
190
191p.caption {
192 font-style: italic }
193
194p.credits {
195 font-style: italic ;
196 font-size: smaller }
197
198p.label {
199 white-space: nowrap }
200
201p.rubric {
202 font-weight: bold ;
203 font-size: larger ;
204 color: maroon ;
205 text-align: center }
206
207p.sidebar-title {
208 font-family: sans-serif ;
209 font-weight: bold ;
210 font-size: larger }
211
212p.sidebar-subtitle {
213 font-family: sans-serif ;
214 font-weight: bold }
215
216p.topic-title {
217 font-weight: bold }
218
219pre.address {
220 margin-bottom: 0 ;
221 margin-top: 0 ;
222 font-family: serif ;
223 font-size: 100% }
224
225pre.literal-block, pre.doctest-block {
226 margin-left: 2em ;
227 margin-right: 2em ;
228 background-color: #eeeeee }
229
230span.classifier {
231 font-family: sans-serif ;
232 font-style: oblique }
233
234span.classifier-delimiter {
235 font-family: sans-serif ;
236 font-weight: bold }
237
238span.interpreted {
239 font-family: sans-serif }
240
241span.option {
242 white-space: nowrap }
243
244span.pre {
245 white-space: pre }
246
247span.problematic {
248 color: red }
249
250span.section-subtitle {
251 /* font-size relative to parent (h1..h6 element) */
252 font-size: 80% }
253
254table.citation {
255 border-left: solid 1px gray;
256 margin-left: 1px }
257
258table.docinfo {
259 margin: 2em 4em }
260
261table.docutils {
262 margin-top: 0.5em ;
263 margin-bottom: 0.5em }
264
265table.footnote {
266 border-left: solid 1px black;
267 margin-left: 1px }
268
269table.docutils td, table.docutils th,
270table.docinfo td, table.docinfo th {
271 padding-left: 0.5em ;
272 padding-right: 0.5em ;
273 vertical-align: top }
274
275table.docutils th.field-name, table.docinfo th.docinfo-name {
276 font-weight: bold ;
277 text-align: left ;
278 white-space: nowrap ;
279 padding-left: 0 }
280
281h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
282h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
283 font-size: 100% }
284
285tt.docutils {
286 background-color: #eeeeee }
287
288ul.auto-toc {
289 list-style-type: none }
290
291</style>
292</head>
293<body>
294<div class="document">
295<table class="docinfo" frame="void" rules="none">
296<col class="docinfo-name" />
297<col class="docinfo-content" />
298<tbody valign="top">
299<tr><th class="docinfo-name">Author:</th>
300<td><a class="first reference" href="mailto:mikhailberis&#64;gmail.com">Dean Michael Berris</a></td></tr>
301<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">Distributed under the Boost Software License, Version 1.0
302(See accompanying file LICENSE_1_0.txt or copy at <a class="reference" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
303</tr>
304</tbody>
305</table>
306<div class="section">
307<h1><a id="function-input-iterator" name="function-input-iterator">Function Input Iterator</a></h1>
308<p>The Function Input Iterator allows for creating iterators that encapsulate
309a nullary function object and a state object which tracks the number of times
310the iterator has been incremented. A Function Input Iterator models the
311<a class="reference" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> concept and is useful for creating bounded input iterators.</p>
312<p>Like the Generator Iterator, the Function Input Iterator takes a function
313that models the <a class="reference" href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> concept (which is basically a nullary or 0-arity
314function object). Each increment of the function Function Input Iterator
315invokes the generator function and stores the value in the iterator. When
316the iterator is dereferenced the stored value is returned.</p>
317<p>The Function Input Iterator encapsulates a state object which models the
318<a class="reference" href="#incrementable-concept">Incrementable Concept</a> and the <a class="reference" href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> Concept. These concepts are
319described below as:</p>
320<div class="section">
321<h2><a id="incrementable-concept" name="incrementable-concept">Incrementable Concept</a></h2>
322<p>A type models the Incrementable Concept when it supports the pre- and post-
323increment 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
324constructs should be valid:</p>
325<table border="1" class="docutils">
326<colgroup>
327<col width="24%" />
328<col width="46%" />
329<col width="30%" />
330</colgroup>
331<tbody valign="top">
332<tr><td colspan="3">Construct Description Return Type</td>
333</tr>
334<tr><td>i++</td>
335<td>Post-increment i.</td>
336<td>I</td>
337</tr>
338<tr><td>++i</td>
339<td>Pre-increment i.</td>
340<td>I&amp;</td>
341</tr>
342</tbody>
343</table>
344<p>NOTE: An Incrementable type should also be <a class="reference" href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>.</p>
345</div>
346<div class="section">
347<h2><a id="synopsis" name="synopsis">Synopsis</a></h2>
348<pre class="literal-block">
349namespace {
350 template &lt;class Function, class State&gt;
351 class function_input_iterator;
352
353 template &lt;class Function, class State&gt;
354 typename function_input_iterator&lt;Function, State&gt;
355 make_function_input_iterator(Function &amp; f);
356
357 struct infinite;
358}
359</pre>
360</div>
361<div class="section">
362<h2><a id="function-input-iterator-class" name="function-input-iterator-class">Function Input Iterator Class</a></h2>
363<p>The class Function Input Iterator class takes two template parameters
364<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
365Function Input Iterator the type of the function to encapsulate and
366the type of the internal state value to hold.</p>
367<p>The <tt class="docutils literal"><span class="pre">State</span></tt> parameter is important in cases where you want to
368control the type of the counter which determines whether two iterators
369are at the same state. This allows for creating a pair of iterators which
370bound the range of the invocations of the encapsulated functions.</p>
371</div>
372<div class="section">
373<h2><a id="examples" name="examples">Examples</a></h2>
374<p>The following example shows how we use the function input iterator class
375in cases where we want to create bounded (lazy) generated ranges.</p>
376<pre class="literal-block">
377struct generator {
378 typedef int result_type;
379 generator() { srand(time(0)); }
380 result_type operator() () const {
381 return rand();
382 }
383};
384
385int main(int argc, char * argv[]) {
386 generator f;
387 copy(
388 make_function_input_iterator(f, 0),
389 make_function_input_iterator(f, 10),
390 ostream_iterator&lt;int&gt;(cout, &quot; &quot;)
391 );
392 return 0;
393}
394</pre>
395<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>
396that 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
397of random numbers and encapsulate that in a pair of integers, we can do
398it with the <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> helper class.</p>
399<pre class="literal-block">
400copy(
401 make_function_input_iterator(f,infinite()),
402 make_function_input_iterator(f,infinite()),
403 ostream_iterator&lt;int&gt;(count, &quot; &quot;)
404 );
405</pre>
406<p>Above, instead of creating a huge vector we rely on the STL copy algorithm
407to traverse the function input iterator and call the function object f
408as it increments the iterator. The special property of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt>
409is that equating two instances always yield false -- and that incrementing
410an instance of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> doesn't do anything. This is an efficient
411way of stating that the iterator range provided by two iterators with an
412encapsulated infinite state will definitely be infinite.</p>
413</div>
414</div>
415</div>
416</body>
417</html>