Squashed 'third_party/boostorg/optional/' content from commit 155ad59
Change-Id: I4ad7a1e7b295a6136c5a0d7b6c11700e76b939b5
git-subtree-dir: third_party/boostorg/optional
git-subtree-split: 155ad5911e5683cc87d34363f8304b60a30a8345
diff --git a/doc/14_io.qbk b/doc/14_io.qbk
new file mode 100644
index 0000000..0fb4e89
--- /dev/null
+++ b/doc/14_io.qbk
@@ -0,0 +1,37 @@
+
+[section IO operators]
+
+It is possible to use `optional<T>` with IO streams, provided that `T` can be used with streams. IOStream operators are defined in a separate header.
+
+``
+#include <iostream>
+#include <boost/optional/optional_io.hpp>
+
+int main()
+{
+ boost::optional<int> o1 = 1, oN = boost::none;
+ std::cout << o1;
+ std::cin >> oN;
+}
+``
+
+The current implementation does not guarantee any particular output. What it guarantees is that if streaming out and then back in `T` gives the same value, then streaming out and then back in `optional<T>` will also give back the same result:
+
+``
+#include <cassert>
+#include <sstream>
+#include <boost/optional/optional_io.hpp>
+
+int main()
+{
+ boost::optional<int> o1 = 1, oN = boost::none;
+ boost::optional<int> x1, x2;
+ std::stringstream s;
+ s << o1 << oN;
+ s >> x1 >> x2;
+ assert (o1 == x1);
+ assert (oN == x2);
+}
+``
+
+[endsect]