ceph/src/boost/libs/iterator/doc/quickbook/function_output_iterator.qbk

   1
   2 [section:function_output Function Output Iterator]
   3
   4 The function output iterator adaptor makes it easier to create custom
   5 output iterators. The adaptor takes a unary function and creates a
   6 model of Output Iterator. Each item assigned to the output iterator is
   7 passed as an argument to the unary function.  The motivation for this
   8 iterator is that creating a conforming output iterator is non-trivial,
   9 particularly because the proper implementation usually requires a
  10 proxy object.
  11
  12 [h2 Example]
  13
  14     struct string_appender
  15     {
  16         string_appender(std::string& s)
  17             : m_str(&s)
  18         {}
  19
  20         void operator()(const std::string& x) const
  21         {
  22             *m_str += x;
  23         }
  24
  25         std::string* m_str;
  26     };
  27
  28     int main(int, char*[])
  29     {
  30       std::vector<std::string> x;
  31       x.push_back("hello");
  32       x.push_back(" ");
  33       x.push_back("world");
  34       x.push_back("!");
  35
  36       std::string s = "";
  37       std::copy(x.begin(), x.end(),
  38                 boost::make_function_output_iterator(string_appender(s)));
  39
  40       std::cout << s << std::endl;
  41
  42       return 0;
  43     }
  44
  45 [h2 Reference]
  46
  47 [h3 Synopsis]
  48
  49   template <class UnaryFunction>
  50   class function_output_iterator {
  51   public:
  52     typedef std::output_iterator_tag iterator_category;
  53     typedef void                     value_type;
  54     typedef void                     difference_type;
  55     typedef void                     pointer;
  56     typedef void                     reference;
  57
  58     explicit function_output_iterator();
  59
  60     explicit function_output_iterator(const UnaryFunction& f);
  61
  62     /* see below */ operator*();
  63     function_output_iterator& operator++();
  64     function_output_iterator& operator++(int);
  65   private:
  66     UnaryFunction m_f;     // exposition only
  67   };
  68
  69 [h3 Requirements]
  70
  71 `UnaryFunction` must be Assignable and Copy Constructible.
  72
  73 [h3 Concepts]
  74
  75 `function_output_iterator` is a model of the Writable and
  76 Incrementable Iterator concepts.
  77
  78 [h3 Operations]
  79
  80   explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
  81
  82 [*Effects: ] Constructs an instance of `function_output_iterator`
  83   with `m_f` constructed from `f`.
  84
  85   unspecified_type operator*();
  86
  87 [*Returns: ] An object `r` of unspecified type such that `r = t`
  88   is equivalent to `m_f(t)` for all `t`.
  89
  90
  91   function_output_iterator& operator++();
  92
  93 [*Returns: ] `*this`.
  94
  95
  96   function_output_iterator& operator++(int);
  97
  98 [*Returns: ] `*this`.
  99
 100 [endsect]