Squashed 'third_party/boostorg/iterator/' content from commit b2adecb
Change-Id: I284a73816f9cc846742923879275b84c6e0c915c
git-subtree-dir: third_party/boostorg/iterator
git-subtree-split: b2adecb951af025698618f19a3c838bd314966dc
diff --git a/doc/quickbook/function_output_iterator.qbk b/doc/quickbook/function_output_iterator.qbk
new file mode 100644
index 0000000..838ebde
--- /dev/null
+++ b/doc/quickbook/function_output_iterator.qbk
@@ -0,0 +1,100 @@
+
+[section:function_output Function Output Iterator]
+
+The function output iterator adaptor makes it easier to create custom
+output iterators. The adaptor takes a unary function and creates a
+model of Output Iterator. Each item assigned to the output iterator is
+passed as an argument to the unary function. The motivation for this
+iterator is that creating a conforming output iterator is non-trivial,
+particularly because the proper implementation usually requires a
+proxy object.
+
+[h2 Example]
+
+ struct string_appender
+ {
+ string_appender(std::string& s)
+ : m_str(&s)
+ {}
+
+ void operator()(const std::string& x) const
+ {
+ *m_str += x;
+ }
+
+ std::string* m_str;
+ };
+
+ int main(int, char*[])
+ {
+ std::vector<std::string> x;
+ x.push_back("hello");
+ x.push_back(" ");
+ x.push_back("world");
+ x.push_back("!");
+
+ std::string s = "";
+ std::copy(x.begin(), x.end(),
+ boost::make_function_output_iterator(string_appender(s)));
+
+ std::cout << s << std::endl;
+
+ return 0;
+ }
+
+[h2 Reference]
+
+[h3 Synopsis]
+
+ template <class UnaryFunction>
+ class function_output_iterator {
+ public:
+ typedef std::output_iterator_tag iterator_category;
+ typedef void value_type;
+ typedef void difference_type;
+ typedef void pointer;
+ typedef void reference;
+
+ explicit function_output_iterator();
+
+ explicit function_output_iterator(const UnaryFunction& f);
+
+ /* see below */ operator*();
+ function_output_iterator& operator++();
+ function_output_iterator& operator++(int);
+ private:
+ UnaryFunction m_f; // exposition only
+ };
+
+[h3 Requirements]
+
+`UnaryFunction` must be Assignable and Copy Constructible.
+
+[h3 Concepts]
+
+`function_output_iterator` is a model of the Writable and
+Incrementable Iterator concepts.
+
+[h3 Operations]
+
+ explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
+
+[*Effects: ] Constructs an instance of `function_output_iterator`
+ with `m_f` constructed from `f`.
+
+ unspecified_type operator*();
+
+[*Returns: ] An object `r` of unspecified type such that `r = t`
+ is equivalent to `m_f(t)` for all `t`.
+
+
+ function_output_iterator& operator++();
+
+[*Returns: ] `*this`.
+
+
+ function_output_iterator& operator++(int);
+
+[*Returns: ] `*this`.
+
+[endsect]