diff --git a/doc/function_input_iterator.html b/doc/function_input_iterator.html new file mode 100644 index 0000000..e097a46 --- /dev/null +++ b/doc/function_input_iterator.html @@ -0,0 +1,142 @@ + + + + + + + + + + + +
+ + +++ + + + + + +
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
++iPre-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.

+
+
+
+
+
+View document source. +Generated by Docutils from reStructuredText source. + +
+ + diff --git a/doc/function_input_iterator.rst b/doc/function_input_iterator.rst new file mode 100644 index 0000000..d073fa0 --- /dev/null +++ b/doc/function_input_iterator.rst @@ -0,0 +1,126 @@ +: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. + +.. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html + +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. + +.. _Generator: http://www.sgi.com/tech/stl/Generator.html + +The Function Input Iterator encapsulates a state object which models the +`Incrementable Concept`_ and the EqualityComparable_ Concept. These concepts are +described below as: + +.. _EqualityComparable: http://www.sgi.com/tech/stl/EqualityComparable.html + +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_. + +.. _DefaultConstructible: http://www.sgi.com/tech/stl/DefaultConstructible.html + +Synopsis +-------- + +:: + + namespace { + template + class function_input_iterator; + + template + typename function_input_iterator + 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(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(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. + + diff --git a/doc/index.html b/doc/index.html old mode 100755 new mode 100644 index afde947..7e7dd9a --- a/doc/index.html +++ b/doc/index.html @@ -3,7 +3,7 @@ - + The Boost.Iterator Library Boost @@ -11,9 +11,6 @@