ceph/src/boost/libs/iterator/doc/function_input_iterator.rst

   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
  11 Function Input Iterator
  12 =======================
  13
  14 The Function Input Iterator allows for creating iterators that encapsulate
  15 a nullary function object and a state object which tracks the number of times
  16 the 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
  21 The 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
  23 of the iterator at a given position invokes the generator function and stores
  24 and returns the result; subsequent dereferences at the same position simply
  25 return the same stored result. Incrementing the iterator places it at a new
  26 position, hence a subsequent dereference will generate a new value via another
  27 invokation of the generator function. This ensures the generator function is
  28 invoked precisely when the iterator is requested to return a (new) value.
  29
  30 .. _Generator: http://www.sgi.com/tech/stl/Generator.html
  31
  32 The Function Input Iterator encapsulates a state object which models the
  33 `Incrementable Concept`_ and the EqualityComparable_ Concept. These concepts are
  34 described below as:
  35
  36 .. _EqualityComparable: http://www.sgi.com/tech/stl/EqualityComparable.html
  37
  38 Incrementable Concept
  39 ---------------------
  40
  41 A type models the Incrementable Concept when it supports the pre- and post-
  42 increment operators. For a given object ``i`` with type ``I``, the following
  43 constructs should be valid:
  44
  45 =========  =================  ===========
  46 Construct  Description        Return Type
  47 -----------------------------------------
  48 i++        Post-increment i.  I
  49 ++i        Pre-increment i.   I&
  50 =========  =================  ===========
  51
  52 NOTE: An Incrementable type should also be DefaultConstructible_.
  53
  54 .. _DefaultConstructible: http://www.sgi.com/tech/stl/DefaultConstructible.html
  55
  56 Synopsis
  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
  72 Function Input Iterator Class
  73 -----------------------------
  74
  75 The class Function Input Iterator class takes two template parameters
  76 ``Function`` and ``State``. These two template parameters tell the
  77 Function Input Iterator the type of the function to encapsulate and
  78 the type of the internal state value to hold.
  79
  80 The ``State`` parameter is important in cases where you want to
  81 control the type of the counter which determines whether two iterators
  82 are at the same state. This allows for creating a pair of iterators which
  83 bound the range of the invocations of the encapsulated functions.
  84
  85 Examples
  86 --------
  87
  88 The following example shows how we use the function input iterator class
  89 in 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
 111 Here we can see that we've bounded the number of invocations using an ``int``
 112 that counts from ``0`` to ``10``. Say we want to create an endless stream
 113 of random numbers and encapsulate that in a pair of integers, we can do
 114 it 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
 124 Above, instead of creating a huge vector we rely on the STL copy algorithm
 125 to traverse the function input iterator and call the function object f
 126 as it increments the iterator. The special property of ``boost::infinite``
 127 is that equating two instances always yield false -- and that incrementing
 128 an instance of ``boost::infinite`` doesn't do anything. This is an efficient
 129 way of stating that the iterator range provided by two iterators with an
 130 encapsulated infinite state will definitely be infinite.
 131
 132