Author:	Dean Michael Berris
License:	Distributed under the Boost Software License, Version 1.0 (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Function Input Iterator

The Function Input Iterator allows for creating iterators that encapsulate a nullary function object and a state object which tracks the number of times the iterator has been incremented. A Function Input Iterator models the InputIterator concept and is useful for creating bounded input iterators.

Like the Generator Iterator, the Function Input Iterator takes a function that models the Generator concept (which is basically a nullary or 0-arity function object). Each increment of the function Function Input Iterator invokes the generator function and stores the value in the iterator. When the iterator is dereferenced the stored value is returned.

The Function Input Iterator encapsulates a state object which models the Incrementable Concept and the EqualityComparable Concept. These concepts are described below as:

Incrementable Concept

A type models the Incrementable Concept when it supports the pre- and post- increment operators. For a given object i with type I, the following constructs should be valid:

Construct Description Return Type
i++	Post-increment i.	I
++i	Pre-increment i.	I&

NOTE: An Incrementable type should also be DefaultConstructible.

Synopsis

namespace {
    template <class Function, class State>
    class function_input_iterator;

    template <class Function, class State>
    typename function_input_iterator<Function, State>
    make_function_input_iterator(Function & f);

    struct infinite;
}

Function Input Iterator Class

The class Function Input Iterator class takes two template parameters Function and State. These two template parameters tell the Function Input Iterator the type of the function to encapsulate and the type of the internal state value to hold.

The State parameter is important in cases where you want to control the type of the counter which determines whether two iterators are at the same state. This allows for creating a pair of iterators which bound the range of the invocations of the encapsulated functions.

Examples

The following example shows how we use the function input iterator class in cases where we want to create bounded (lazy) generated ranges.

struct generator {
    typedef int result_type;
    generator() { srand(time(0)); }
    result_type operator() () const {
        return rand();
    }
};

int main(int argc, char * argv[]) {
    generator f;
    copy(
            make_function_input_iterator(f, 0),
            make_function_input_iterator(f, 10),
            ostream_iterator<int>(cout, " ")
        );
    return 0;
}

Here we can see that we've bounded the number of invocations using an int that counts from 0 to 10. Say we want to create an endless stream of random numbers and encapsulate that in a pair of integers, we can do it with the boost::infinite helper class.

copy(
        make_function_input_iterator(f,infinite()),
        make_function_input_iterator(f,infinite()),
        ostream_iterator<int>(count, " ")
    );

Above, instead of creating a huge vector we rely on the STL copy algorithm to traverse the function input iterator and call the function object f as it increments the iterator. The special property of boost::infinite is that equating two instances always yield false -- and that incrementing an instance of boost::infinite doesn't do anything. This is an efficient way of stating that the iterator range provided by two iterators with an encapsulated infinite state will definitely be infinite.