1:Author: 2 `Dean Michael Berris <mailto:me@deanberris.com>`_ 3 4:License: 5 Distributed under the Boost Software License, Version 1.0 6 (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7 8:Copyright: 9 Copyright 2012 Google, Inc. 10 11Function Input Iterator 12======================= 13 14The Function Input Iterator allows for creating iterators that encapsulate 15a nullary function object and a state object which tracks the number of times 16the iterator has been incremented. A Function Input Iterator models the 17`InputIterator`_ concept and is useful for creating bounded input iterators. 18 19.. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html 20 21The Function Input Iterator takes a function that models the Generator_ concept 22(which is basically a nullary or 0-arity function object). The first dereference 23of the iterator at a given position invokes the generator function and stores 24and returns the result; subsequent dereferences at the same position simply 25return the same stored result. Incrementing the iterator places it at a new 26position, hence a subsequent dereference will generate a new value via another 27invokation of the generator function. This ensures the generator function is 28invoked precisely when the iterator is requested to return a (new) value. 29 30.. _Generator: http://www.sgi.com/tech/stl/Generator.html 31 32The Function Input Iterator encapsulates a state object which models the 33`Incrementable Concept`_ and the EqualityComparable_ Concept. These concepts are 34described below as: 35 36.. _EqualityComparable: http://www.sgi.com/tech/stl/EqualityComparable.html 37 38Incrementable Concept 39--------------------- 40 41A type models the Incrementable Concept when it supports the pre- and post- 42increment operators. For a given object ``i`` with type ``I``, the following 43constructs should be valid: 44 45========= ================= =========== 46Construct Description Return Type 47----------------------------------------- 48i++ Post-increment i. I 49++i Pre-increment i. I& 50========= ================= =========== 51 52NOTE: An Incrementable type should also be DefaultConstructible_. 53 54.. _DefaultConstructible: http://www.sgi.com/tech/stl/DefaultConstructible.html 55 56Synopsis 57-------- 58 59:: 60 61 namespace { 62 template <class Function, class State> 63 class function_input_iterator; 64 65 template <class Function, class State> 66 typename function_input_iterator<Function, State> 67 make_function_input_iterator(Function & f, State s); 68 69 struct infinite; 70 } 71 72Function Input Iterator Class 73----------------------------- 74 75The class Function Input Iterator class takes two template parameters 76``Function`` and ``State``. These two template parameters tell the 77Function Input Iterator the type of the function to encapsulate and 78the type of the internal state value to hold. 79 80The ``State`` parameter is important in cases where you want to 81control the type of the counter which determines whether two iterators 82are at the same state. This allows for creating a pair of iterators which 83bound the range of the invocations of the encapsulated functions. 84 85Examples 86-------- 87 88The following example shows how we use the function input iterator class 89in cases where we want to create bounded (lazy) generated ranges. 90 91:: 92 93 struct generator { 94 typedef int result_type; 95 generator() { srand(time(0)); } 96 result_type operator() () const { 97 return rand(); 98 } 99 }; 100 101 int main(int argc, char * argv[]) { 102 generator f; 103 copy( 104 make_function_input_iterator(f, 0), 105 make_function_input_iterator(f, 10), 106 ostream_iterator<int>(cout, " ") 107 ); 108 return 0; 109 } 110 111Here we can see that we've bounded the number of invocations using an ``int`` 112that counts from ``0`` to ``10``. Say we want to create an endless stream 113of random numbers and encapsulate that in a pair of integers, we can do 114it with the ``boost::infinite`` helper class. 115 116:: 117 118 copy( 119 make_function_input_iterator(f,infinite()), 120 make_function_input_iterator(f,infinite()), 121 ostream_iterator<int>(cout, " ") 122 ); 123 124Above, instead of creating a huge vector we rely on the STL copy algorithm 125to traverse the function input iterator and call the function object f 126as it increments the iterator. The special property of ``boost::infinite`` 127is that equating two instances always yield false -- and that incrementing 128an instance of ``boost::infinite`` doesn't do anything. This is an efficient 129way of stating that the iterator range provided by two iterators with an 130encapsulated infinite state will definitely be infinite. 131 132 133