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 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&</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 <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 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<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> 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<int>(count, " ") 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> 143