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/17_gotchas.qbk b/doc/17_gotchas.qbk
new file mode 100644
index 0000000..5cfa36b
--- /dev/null
+++ b/doc/17_gotchas.qbk
@@ -0,0 +1,111 @@
+[section Gotchas]
+
+[section A note about optional<bool>]
+
+`optional<bool>` should be used with special caution and consideration.
+
+First, it is functionally similar to a tristate boolean (false, maybe, true)
+—such as __BOOST_TRIBOOL__— except that in a tristate boolean, the maybe state
+[_represents a valid value], unlike the corresponding state of an uninitialized
+`optional<bool>`.
+It should be carefully considered if an `optional<bool>` instead of a `tribool`
+is really needed.
+
+Second, although `optional<>` provides a contextual conversion to `bool` in C++11,
+ this falls back to an implicit conversion on older compilers. This conversion refers
+ to the initialization state and not to the contained value. Using `optional<bool>`
+ can lead to subtle errors due to the implicit `bool` conversion:
+
+ void foo ( bool v ) ;
+ void bar()
+ {
+ optional<bool> v = try();
+
+ // The following intended to pass the value of 'v' to foo():
+ foo(v);
+ // But instead, the initialization state is passed
+ // due to a typo: it should have been foo(*v).
+ }
+
+The only implicit conversion is to `bool`, and it is safe in the sense that
+typical integral promotions don't apply (i.e. if `foo()` takes an `int`
+instead, it won't compile).
+
+Third, mixed comparisons with `bool` work differently than similar mixed comparisons between pointers and `bool`, so the results might surprise you:
+
+ optional<bool> oEmpty(none), oTrue(true), oFalse(false);
+
+ if (oEmpty == none); // renders true
+ if (oEmpty == false); // renders false!
+ if (oEmpty == true); // renders false!
+
+ if (oFalse == none); // renders false
+ if (oFalse == false); // renders true!
+ if (oFalse == true); // renders false
+
+ if (oTrue == none); // renders false
+ if (oTrue == false); // renders false
+ if (oTrue == true); // renders true
+
+In other words, for `optional<>`, the following assertion does not hold:
+
+ assert((opt == false) == (!opt));
+[endsect]
+
+[section Moved-from `optional`]
+
+When an optional object that contains a value is moved from (is a source of move constructor or assignment) it still contains a value and its contained value is left in a moved-from state. This can be illustrated with the following example.
+
+ optional<std::unique_ptr<int>> opi {std::make_unique<int>(1)};
+ optional<std::unique_ptr<int>> opj = std::move(opi);
+ assert (opi);
+ assert (*opi == nullptr);
+
+Quite a lot of people expect that when an object that contains a value is moved from, its contained value should be destroyed. This is not so, for performance reasons. Current semantics allow the implementation of `boost::opiotnal<T>` to be trivially copyable when `T` is trivial.
+[endsect]
+
+[section Mixed relational comparisons]
+
+Because `T` is convertible to `optional<T>` and because `opiotnal<T>` is __SGI_LESS_THAN_COMPARABLE__ when `T` is __SGI_LESS_THAN_COMPARABLE__,
+you can sometimes get an unexpected runtime result where you would rather expect a compiler error:
+
+ optional<double> Flight_plan::weight(); // sometimes no weight can be returned
+
+ bool is_aircraft_too_heavy(Flight_plan const& p)
+ {
+ return p.weight() > p.aircraft().max_weight(); // compiles!
+ } // returns false when the optional contains no value
+
+[endsect]
+
+[section False positive with -Wmaybe-uninitialized]
+
+Sometimes on GCC compilers below version 5.1 you may get an -Wmaybe-uninitialized warning when copiling with option -02 on a perfectly valid `boost::optional` usage. For instance in this program:
+
+ #include <boost/optional.hpp>
+
+ boost::optional<int> getitem();
+
+ int main(int argc, const char *[])
+ {
+ boost::optional<int> a = getitem();
+ boost::optional<int> b;
+
+ if (argc > 0)
+ b = argc;
+
+ if (a != b)
+ return 1;
+
+ return 0;
+ }
+
+This is a bug in the compiler. As a workaround (provided in [@http://stackoverflow.com/questions/21755206/how-to-get-around-gcc-void-b-4-may-be-used-uninitialized-in-this-funct this Stack Overflow question]) use the following way of initializing an optional containing no value:
+
+ boost::optional<int> b = boost::make_optional(false, int());
+
+This is obviously redundant, but makes the warning disappear.
+
+[endsect]
+
+[endsect]
\ No newline at end of file