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/13_relational_operators.qbk b/doc/13_relational_operators.qbk
new file mode 100644
index 0000000..861a4e8
--- /dev/null
+++ b/doc/13_relational_operators.qbk
@@ -0,0 +1,37 @@
+
+[section Relational operators]
+
+Type `optional<T>` is __SGI_EQUALITY_COMPARABLE__ whenever `T` is __SGI_EQUALITY_COMPARABLE__. Two optional objects containing a value compare in the same way as their contained values. The uninitialized state of `optional<T>` is treated as a distinct value, equal to itself, and unequal to any value of type `T`:
+
+ boost::optional<int> oN = boost::none;
+ boost::optional<int> o0 = 0;
+ boost::optional<int> o1 = 1;
+
+ assert(oN != o0);
+ assert(o1 != oN);
+ assert(o0 != o1);
+ assert(oN == oN);
+ assert(o0 == o0);
+
+The converting constructor from `T` as well as from `boost::none` implies the existence and semantics of the mixed comparison between `T` and `optional<T>` as well as between `none_t` and `optionl<T>`:
+
+ assert(oN != 0);
+ assert(o1 != boost::none);
+ assert(o0 != 1);
+ assert(oN == boost::none);
+ assert(o0 == 0);
+
+This mixed comparison has a practical interpretation, which is occasionally useful:
+
+ boost::optional<int> choice = ask_user();
+ if (choice == 2)
+ start_procedure_2();
+
+In the above example, the meaning of the comparison is 'user chose number 2'. If user chose nothing, he didn't choose number 2.
+
+In case where `optional<T>` is compared to `none`, it is not required that `T` be __SGI_EQUALITY_COMPARABLE__.
+
+In a similar manner, type `optional<T>` is __SGI_LESS_THAN_COMPARABLE__ whenever `T` is __SGI_LESS_THAN_COMPARABLE__. The optional object containing no value is compared less than any value of `T`. To illustrate this, if the default ordering of `size_t` is {`0`, `1`, `2`, ...}, the default ordering of `optional<size_t>` is {`boost::none`, `0`, `1`, `2`, ...}. This order does not have a practical interpretation. The goal is to have any semantically correct default ordering in order for `optional<T>` to be usable in ordered associative containers (wherever `T` is usable).
+
+Mixed relational operators are the only case where the contained value of an optional object can be inspected without the usage of value accessing function (`operator*`, `value`, `value_or`).
+[endsect]