docs: updated gotchas section

Fix emplace Signature

doc/00_optional.qbk

@@ -83,7 +83,7 @@ This is how you solve it with `boost::optional`:
 [include 14_io.qbk]
 [include 15_optional_references.qbk]
 [include 16_in_place_factories.qbk]
-[include 17_optional_bool.qbk]
+[include 17_gotchas.qbk]
 [include 18_exception_safety.qbk]
 [include 19_type_requirements.qbk]
 [include 1A_on_performance.qbk]

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 = std::make_optional(false, int());
+
+This is obviously redundant, but makes the warning disappear.
+
+[endsect]
+
+[endsect]

doc/17_optional_bool.qbk

@@ -1,52 +0,0 @@
-
-[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]

doc/1A_on_performance.qbk

@@ -23,7 +23,7 @@ Given type `optional<int>`, and assuming that `sizeof(int) == 4`, we will get `s
 
 [$images/opt_align1.png]
 
-This means you can fit twice as many `int`s as `optional<int>`s into the same space of memory. Therefore, if the size of the objects is critical for your application (e.g., because you want to utilize your CPU cache in order to gain performance) and you have determined you are willing to trade the code clarity, it is recommended that you simply go with type `int` and use some 'magic value' to represent ['not-an-int].
+This means you can fit twice as many `int`s as `optional<int>`s into the same space of memory. Therefore, if the size of the objects is critical for your application (e.g., because you want to utilize your CPU cache in order to gain performance) and you have determined you are willing to trade the code clarity, it is recommended that you simply go with type `int` and use some 'magic value' to represent ['not-an-int], or use something like [@https://github.com/akrzemi1/markable `markable`] library.
 
 Even if you cannot spare any value of `int` to represent ['not-an-int] (e.g., because every value is useful, or you do want to signal ['not-an-int] explicitly), at least for `Trivial` types you should consider storing the value and the `bool` flag representing the ['null-state] separately. Consider the following class:
 

doc/27_ref_optional_synopsis.qbk

@@ -120,7 +120,7 @@
         
         template<class U> optional& operator = ( optional<U>&& rhs ) ; ``[link reference_optional_operator_move_equal_other_optional __GO_TO__]``
         
-        template<class... Args> void emplace ( Args...&& args ) ; ``[link reference_optional_emplace __GO_TO__]``
+        template<class... Args> void emplace ( Args&&... args ) ; ``[link reference_optional_emplace __GO_TO__]``
 
         template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[link reference_optional_operator_equal_factory __GO_TO__]``
 

doc/28_ref_optional_semantics.qbk

@@ -446,7 +446,7 @@ __SPACE__
 
 [#reference_optional_emplace]
 
-[: `template<class... Args> void optional<T>::emplace( Args...&& args );`]
+[: `template<class... Args> void optional<T>::emplace( Args&&... args );`]
 
 * [*Requires:] The compiler supports rvalue references and variadic templates.
 * [*Effect:] If `*this` is initialized calls `*this = none`.
@@ -770,6 +770,7 @@ __SPACE__
 [: `template<class R> optional<T&>::optional(R&& r) noexcept;`]
 * [*Postconditions:] `bool(*this) == true`; `addressof(**this) == addressof(r)`.
 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
+* [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here]. 
 * [*Example:]
 ``
 T v;
@@ -1181,7 +1182,7 @@ __SPACE__
 [: `bool operator != ( optional<T> const& x, none_t ) noexcept;`]
 [: `bool operator != ( none_t, optional<T> const& x ) noexcept;`]
 
-* [*Returns: ] `!( x == y );`
+* [*Returns: ] `bool(x);`
 
 
 __SPACE__
@@ -1268,4 +1269,4 @@ assert ( !optX );
 assert (addressof(*opt0) == addressof(y));
 ``
 
-[endsect]
+[endsect]

doc/90_dependencies.qbk

@@ -28,7 +28,7 @@ The implementation uses the following other Boost modules:
 [endsect]
 
 
-[section Optional Reference Binding]
+[section Optional Reference Binding][#optional_reference_binding]
 
 A number of compilers incorrectly treat const lvalues of integral type as rvalues, and create an illegal temporary when binding to an lvalue reference to const in some expressions. This could result in creating an optional lvalue reference that is in fact bound to an unexpected temporary rather than to the intended object. In order to prevent hard to find run-time bugs, this library performs compile-time checks to prevent expressions that would otherwise bind an optional reference to an unexpected temporary. As a consequence, on certain compilers certain pieces of functionality in optional references are missing. In order to maintain a portability of your code across diferent compilers, it is recommended that you only stick to the minimum portable interface of optional references: prefer direct-initialization and copy assignment of optional references to copy-initialization and assignment from `T&`:
 

doc/91_relnotes.qbk

@@ -12,6 +12,11 @@
 [section:relnotes Release Notes]
 
 
+[heading Boost Release 1.62]
+
+* Fixed [@https://svn.boost.org/trac/boost/ticket/12179 Trac #12179].
+
+
 [heading Boost Release 1.61]
 
 * Now `boost::optional` is specialized for reference parameters. This addresses a couple of issues:

doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html

@@ -28,18 +28,19 @@
       Reference Binding</a>
 </h3></div></div></div>
 <p>
-        A number of compilers incorrectly treat const lvalues of integral type as
-        rvalues, and create an illegal temporary when binding to an lvalue reference
-        to const in some expressions. This could result in creating an optional lvalue
-        reference that is in fact bound to an unexpected temporary rather than to
-        the intended object. In order to prevent hard to find run-time bugs, this
-        library performs compile-time checks to prevent expressions that would otherwise
-        bind an optional reference to an unexpected temporary. As a consequence,
-        on certain compilers certain pieces of functionality in optional references
-        are missing. In order to maintain a portability of your code across diferent
-        compilers, it is recommended that you only stick to the minimum portable
-        interface of optional references: prefer direct-initialization and copy assignment
-        of optional references to copy-initialization and assignment from <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>:
+        <a name="optional_reference_binding"></a>A number of compilers incorrectly
+        treat const lvalues of integral type as rvalues, and create an illegal temporary
+        when binding to an lvalue reference to const in some expressions. This could
+        result in creating an optional lvalue reference that is in fact bound to
+        an unexpected temporary rather than to the intended object. In order to prevent
+        hard to find run-time bugs, this library performs compile-time checks to
+        prevent expressions that would otherwise bind an optional reference to an
+        unexpected temporary. As a consequence, on certain compilers certain pieces
+        of functionality in optional references are missing. In order to maintain
+        a portability of your code across diferent compilers, it is recommended that
+        you only stick to the minimum portable interface of optional references:
+        prefer direct-initialization and copy assignment of optional references to
+        copy-initialization and assignment from <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>:
       </p>
 <pre class="programlisting"><span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">or1</span><span class="special">;</span>

doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___free_functions.html

@@ -268,9 +268,7 @@
             <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span></code>
           </p></blockquote></div>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
-              <span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="special">!(</span>
-              <span class="identifier">x</span> <span class="special">==</span>
-              <span class="identifier">y</span> <span class="special">);</span></code>
+              <span class="bold"><strong>Returns: </strong></span> <code class="computeroutput"><span class="keyword">bool</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span></code>
             </li></ul></div>
 <p>
           <span class="inlinemediaobject"><img src="../../../images/space.png" alt="space"></span>

doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html

@@ -55,6 +55,12 @@
               is an lvalue reference, the program is ill-formed. This constructor
               does not participate in overload resolution if <code class="computeroutput"><span class="identifier">decay</span><span class="special">&lt;</span><span class="identifier">R</span><span class="special">&gt;</span></code> is an instance of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>.
             </li>
+<li class="listitem">
+              <span class="bold"><strong>Notes:</strong></span> This constructor is declared
+              <code class="computeroutput"><span class="keyword">explicit</span></code> on compilers
+              that do not correctly suport binding to const lvalues of integral types.
+              For more details <a class="link" href="../../dependencies_and_portability/optional_reference_binding.html#optional_reference_binding">see here</a>.
+            </li>
 <li class="listitem">
               <span class="bold"><strong>Example:</strong></span>
 <pre class="programlisting"><span class="identifier">T</span> <span class="identifier">v</span><span class="special">;</span>

doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html

@@ -1007,7 +1007,7 @@
         </p>
 <a name="reference_optional_emplace"></a><div class="blockquote"><blockquote class="blockquote"><p>
             <code class="computeroutput"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span><span class="special">...</span> <span class="identifier">Args</span><span class="special">&gt;</span>
-            <span class="keyword">void</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">emplace</span><span class="special">(</span> <span class="identifier">Args</span><span class="special">...&amp;&amp;</span> <span class="identifier">args</span>
+            <span class="keyword">void</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">emplace</span><span class="special">(</span> <span class="identifier">Args</span><span class="special">&amp;&amp;...</span> <span class="identifier">args</span>
             <span class="special">);</span></code>
           </p></blockquote></div>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">

doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html

@@ -76,7 +76,7 @@
 
     <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">&gt;</span> <span class="identifier">optional</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;&amp;&amp;</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a class="link" href="detailed_semantics___optional_values.html#reference_optional_operator_move_equal_other_optional"><span class="inlinemediaobject"><img src="../../../images/callouts/R.png" alt="R"></span></a>
 
-    <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span><span class="special">...</span> <span class="identifier">Args</span><span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">emplace</span> <span class="special">(</span> <span class="identifier">Args</span><span class="special">...&amp;&amp;</span> <span class="identifier">args</span> <span class="special">)</span> <span class="special">;</span> <a class="link" href="detailed_semantics___optional_values.html#reference_optional_emplace"><span class="inlinemediaobject"><img src="../../../images/callouts/R.png" alt="R"></span></a>
+    <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span><span class="special">...</span> <span class="identifier">Args</span><span class="special">&gt;</span> <span class="keyword">void</span> <span class="identifier">emplace</span> <span class="special">(</span> <span class="identifier">Args</span><span class="special">&amp;&amp;...</span> <span class="identifier">args</span> <span class="special">)</span> <span class="special">;</span> <a class="link" href="detailed_semantics___optional_values.html#reference_optional_emplace"><span class="inlinemediaobject"><img src="../../../images/callouts/R.png" alt="R"></span></a>
 
     <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">InPlaceFactory</span><span class="special">&gt;</span> <span class="identifier">optional</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span> <a class="link" href="detailed_semantics___optional_values.html#reference_optional_operator_equal_factory"><span class="inlinemediaobject"><img src="../../../images/callouts/R.png" alt="R"></span></a>
 

doc/html/boost_optional/relnotes.html

@@ -28,6 +28,14 @@
 </h2></div></div></div>
 <h4>
 <a name="boost_optional.relnotes.h0"></a>
+      <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_62"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_62">Boost
+      Release 1.62</a>
+    </h4>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+          Fixed <a href="https://svn.boost.org/trac/boost/ticket/12179" target="_top">Trac #12179</a>.
+        </li></ul></div>
+<h4>
+<a name="boost_optional.relnotes.h1"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_61"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_61">Boost
       Release 1.61</a>
     </h4>
@@ -70,7 +78,7 @@
         </li>
 </ul></div>
 <h4>
-<a name="boost_optional.relnotes.h1"></a>
+<a name="boost_optional.relnotes.h2"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_60"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_60">Boost
       Release 1.60</a>
     </h4>
@@ -81,7 +89,7 @@
           #11203</a>.
         </li></ul></div>
 <h4>
-<a name="boost_optional.relnotes.h2"></a>
+<a name="boost_optional.relnotes.h3"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_59"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_59">Boost
       Release 1.59</a>
     </h4>
@@ -95,7 +103,7 @@
         </li>
 </ul></div>
 <h4>
-<a name="boost_optional.relnotes.h3"></a>
+<a name="boost_optional.relnotes.h4"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_58"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_58">Boost
       Release 1.58</a>
     </h4>
@@ -131,7 +139,7 @@
         </li>
 </ul></div>
 <h4>
-<a name="boost_optional.relnotes.h4"></a>
+<a name="boost_optional.relnotes.h5"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_57"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_57">Boost
       Release 1.57</a>
     </h4>
@@ -141,7 +149,7 @@
           to fix C++03 compile error on <code class="computeroutput"><span class="identifier">logic_error</span><span class="special">(</span><span class="string">"..."</span><span class="special">)</span></code>"</em></span>.
         </li></ul></div>
 <h4>
-<a name="boost_optional.relnotes.h5"></a>
+<a name="boost_optional.relnotes.h6"></a>
       <span class="phrase"><a name="boost_optional.relnotes.boost_release_1_56"></a></span><a class="link" href="relnotes.html#boost_optional.relnotes.boost_release_1_56">Boost
       Release 1.56</a>
     </h4>

doc/html/boost_optional/tutorial/exception_safety_guarantees.html

@@ -6,7 +6,7 @@
 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
 <link rel="home" href="../../index.html" title="Boost.Optional">
 <link rel="up" href="../../optional/tutorial.html" title="Tutorial">
-<link rel="prev" href="a_note_about_optional_bool_.html" title="A note about optional&lt;bool&gt;">
+<link rel="prev" href="gotchas/false_positive_with__wmaybe_uninitialized.html" title="False positive with -Wmaybe-uninitialized">
 <link rel="next" href="type_requirements.html" title="Type requirements">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="gotchas/false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">
@@ -169,7 +169,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="gotchas/false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 </body>
 </html>

doc/html/boost_optional/tutorial/gotchas.html

@@ -0,0 +1,112 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Gotchas</title>
+<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../../index.html" title="Boost.Optional">
+<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
+<link rel="prev" href="in_place_factories.html" title="In-Place Factories">
+<link rel="next" href="gotchas/moved_from__optional_.html" title="Moved-from optional">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center"><a href="../../../../../../index.html">Home</a></td>
+<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
+<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
+<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="in_place_factories.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gotchas/moved_from__optional_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.tutorial.gotchas"></a><a class="link" href="gotchas.html" title="Gotchas">Gotchas</a>
+</h3></div></div></div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_optional.tutorial.gotchas.a_note_about_optional_bool_"></a><a class="link" href="gotchas.html#boost_optional.tutorial.gotchas.a_note_about_optional_bool_" title="A note about optional&lt;bool&gt;">A
+        note about optional&lt;bool&gt;</a>
+</h4></div></div></div>
+<p>
+          <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code>
+          should be used with special caution and consideration.
+        </p>
+<p>
+          First, it is functionally similar to a tristate boolean (false, maybe,
+          true) &#8212;such as <a href="../../../../../../doc/html/tribool.html" target="_top">boost::tribool</a>&#8212;
+          except that in a tristate boolean, the maybe state <span class="underline">represents
+          a valid value</span>, unlike the corresponding state of an uninitialized
+          <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code>.
+          It should be carefully considered if an <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code> instead of a <code class="computeroutput"><span class="identifier">tribool</span></code>
+          is really needed.
+        </p>
+<p>
+          Second, although <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> provides a contextual conversion
+          to <code class="computeroutput"><span class="keyword">bool</span></code> 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 <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span></code>
+          can lead to subtle errors due to the implicit <code class="computeroutput"><span class="keyword">bool</span></code>
+          conversion:
+        </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span>
+<span class="keyword">void</span> <span class="identifier">bar</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">v</span> <span class="special">=</span> <span class="keyword">try</span><span class="special">();</span>
+
+    <span class="comment">// The following intended to pass the value of 'v' to foo():</span>
+    <span class="identifier">foo</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
+    <span class="comment">// But instead, the initialization state is passed</span>
+    <span class="comment">// due to a typo: it should have been foo(*v).</span>
+<span class="special">}</span>
+</pre>
+<p>
+          The only implicit conversion is to <code class="computeroutput"><span class="keyword">bool</span></code>,
+          and it is safe in the sense that typical integral promotions don't apply
+          (i.e. if <code class="computeroutput"><span class="identifier">foo</span><span class="special">()</span></code>
+          takes an <code class="computeroutput"><span class="keyword">int</span></code> instead, it won't
+          compile).
+        </p>
+<p>
+          Third, mixed comparisons with <code class="computeroutput"><span class="keyword">bool</span></code>
+          work differently than similar mixed comparisons between pointers and <code class="computeroutput"><span class="keyword">bool</span></code>, so the results might surprise you:
+        </p>
+<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">oEmpty</span><span class="special">(</span><span class="identifier">none</span><span class="special">),</span> <span class="identifier">oTrue</span><span class="special">(</span><span class="keyword">true</span><span class="special">),</span> <span class="identifier">oFalse</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
+
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span>  <span class="comment">// renders true</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// renders false!</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oEmpty</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span>  <span class="comment">// renders false!</span>
+
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span>  <span class="comment">// renders false</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// renders true!</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oFalse</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span>  <span class="comment">// renders false</span>
+
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="identifier">none</span><span class="special">);</span>   <span class="comment">// renders false</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">);</span>  <span class="comment">// renders false</span>
+<span class="keyword">if</span> <span class="special">(</span><span class="identifier">oTrue</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span>   <span class="comment">// renders true</span>
+</pre>
+<p>
+          In other words, for <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>, the following assertion does not
+          hold:
+        </p>
+<pre class="programlisting"><span class="identifier">assert</span><span class="special">((</span><span class="identifier">opt</span> <span class="special">==</span> <span class="keyword">false</span><span class="special">)</span> <span class="special">==</span> <span class="special">(!</span><span class="identifier">opt</span><span class="special">));</span>
+</pre>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;ski<p>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
+      </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="in_place_factories.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gotchas/moved_from__optional_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/tutorial/gotchas/false_positive_with__wmaybe_uninitialized.html

@@ -0,0 +1,77 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>False positive with -Wmaybe-uninitialized</title>
+<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../../../index.html" title="Boost.Optional">
+<link rel="up" href="../gotchas.html" title="Gotchas">
+<link rel="prev" href="mixed_relational_comparisons.html" title="Mixed relational comparisons">
+<link rel="next" href="../exception_safety_guarantees.html" title="Exception Safety Guarantees">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center"><a href="../../../../../../../index.html">Home</a></td>
+<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
+<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
+<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="mixed_relational_comparisons.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../exception_safety_guarantees.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_optional.tutorial.gotchas.false_positive_with__wmaybe_uninitialized"></a><a class="link" href="false_positive_with__wmaybe_uninitialized.html" title="False positive with -Wmaybe-uninitialized">False
+        positive with -Wmaybe-uninitialized</a>
+</h4></div></div></div>
+<p>
+          Sometimes on GCC compilers below version 5.1 you may get an -Wmaybe-uninitialized
+          warning when copiling with option -02 on a perfectly valid <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code> usage. For instance in this
+          program:
+        </p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">optional</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+
+<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">getitem</span><span class="special">();</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*[])</span>
+<span class="special">{</span>
+  <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">getitem</span><span class="special">();</span>
+  <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">;</span>
+
+  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">argc</span> <span class="special">&gt;</span> <span class="number">0</span><span class="special">)</span>
+    <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">argc</span><span class="special">;</span>
+
+  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">)</span>
+    <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
+
+  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+          This is a bug in the compiler. As a workaround (provided in <a href="http://stackoverflow.com/questions/21755206/how-to-get-around-gcc-void-b-4-may-be-used-uninitialized-in-this-funct" target="_top">this
+          Stack Overflow question</a>) use the following way of initializing
+          an optional containing no value:
+        </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_optional</span><span class="special">(</span><span class="keyword">false</span><span class="special">,</span> <span class="keyword">int</span><span class="special">());</span>
+</pre>
+<p>
+          This is obviously redundant, but makes the warning disappear.
+        </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;ski<p>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
+      </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="mixed_relational_comparisons.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../exception_safety_guarantees.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/tutorial/gotchas/mixed_relational_comparisons.html

@@ -0,0 +1,59 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Mixed relational comparisons</title>
+<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../../../index.html" title="Boost.Optional">
+<link rel="up" href="../gotchas.html" title="Gotchas">
+<link rel="prev" href="moved_from__optional_.html" title="Moved-from optional">
+<link rel="next" href="false_positive_with__wmaybe_uninitialized.html" title="False positive with -Wmaybe-uninitialized">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center"><a href="../../../../../../../index.html">Home</a></td>
+<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
+<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
+<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="moved_from__optional_.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_optional.tutorial.gotchas.mixed_relational_comparisons"></a><a class="link" href="mixed_relational_comparisons.html" title="Mixed relational comparisons">Mixed
+        relational comparisons</a>
+</h4></div></div></div>
+<p>
+          Because <code class="computeroutput"><span class="identifier">T</span></code> is convertible
+          to <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+          and because <code class="computeroutput"><span class="identifier">opiotnal</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+          is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a> when <code class="computeroutput"><span class="identifier">T</span></code> is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a>, you can sometimes
+          get an unexpected runtime result where you would rather expect a compiler
+          error:
+        </p>
+<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">Flight_plan</span><span class="special">::</span><span class="identifier">weight</span><span class="special">();</span> <span class="comment">// sometimes no weight can be returned</span>
+
+<span class="keyword">bool</span> <span class="identifier">is_aircraft_too_heavy</span><span class="special">(</span><span class="identifier">Flight_plan</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">p</span><span class="special">)</span>
+<span class="special">{</span>
+   <span class="keyword">return</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">weight</span><span class="special">()</span> <span class="special">&gt;</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">aircraft</span><span class="special">().</span><span class="identifier">max_weight</span><span class="special">();</span> <span class="comment">// compiles!</span>
+<span class="special">}</span>                                                 <span class="comment">// returns false when the optional contains no value </span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;ski<p>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
+      </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="moved_from__optional_.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/tutorial/gotchas/moved_from__optional_.html

@@ -0,0 +1,63 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Moved-from optional</title>
+<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../../../index.html" title="Boost.Optional">
+<link rel="up" href="../gotchas.html" title="Gotchas">
+<link rel="prev" href="../gotchas.html" title="Gotchas">
+<link rel="next" href="mixed_relational_comparisons.html" title="Mixed relational comparisons">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
+<td align="center"><a href="../../../../../../../index.html">Home</a></td>
+<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
+<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
+<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../gotchas.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="mixed_relational_comparisons.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="boost_optional.tutorial.gotchas.moved_from__optional_"></a><a class="link" href="moved_from__optional_.html" title="Moved-from optional">Moved-from
+        <code class="computeroutput"><span class="identifier">optional</span></code></a>
+</h4></div></div></div>
+<p>
+          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.
+        </p>
+<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">unique_ptr</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;&gt;</span> <span class="identifier">opi</span> <span class="special">{</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_unique</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="number">1</span><span class="special">)};</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">unique_ptr</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;&gt;</span> <span class="identifier">opj</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">opi</span><span class="special">);</span>
+<span class="identifier">assert</span> <span class="special">(</span><span class="identifier">opi</span><span class="special">);</span>
+<span class="identifier">assert</span> <span class="special">(*</span><span class="identifier">opi</span> <span class="special">==</span> <span class="keyword">nullptr</span><span class="special">);</span>
+</pre>
+<p>
+          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
+          <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">opiotnal</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+          to be trivially copyable when <code class="computeroutput"><span class="identifier">T</span></code>
+          is trivial.
+        </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;ski<p>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
+      </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../gotchas.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../gotchas.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="mixed_relational_comparisons.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/tutorial/in_place_factories.html

@@ -7,7 +7,7 @@
 <link rel="home" href="../../index.html" title="Boost.Optional">
 <link rel="up" href="../../optional/tutorial.html" title="Tutorial">
 <link rel="prev" href="optional_references/rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding semantics for assignment of optional references">
-<link rel="next" href="a_note_about_optional_bool_.html" title="A note about optional&lt;bool&gt;">
+<link rel="next" href="gotchas.html" title="Gotchas">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 <table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="optional_references/rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="optional_references/rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gotchas.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">
@@ -191,7 +191,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="optional_references/rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="optional_references/rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gotchas.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 </body>
 </html>

doc/html/boost_optional/tutorial/performance_considerations.html

@@ -67,7 +67,7 @@
         for your application (e.g., because you want to utilize your CPU cache in
         order to gain performance) and you have determined you are willing to trade
         the code clarity, it is recommended that you simply go with type <code class="computeroutput"><span class="keyword">int</span></code> and use some 'magic value' to represent
-        <span class="emphasis"><em>not-an-int</em></span>.
+        <span class="emphasis"><em>not-an-int</em></span>, or use something like <a href="https://github.com/akrzemi1/markable" target="_top"><code class="computeroutput"><span class="identifier">markable</span></code></a> library.
       </p>
 <p>
         Even if you cannot spare any value of <code class="computeroutput"><span class="keyword">int</span></code>

doc/html/index.html

@@ -64,8 +64,7 @@
       references</a></span></dt>
 <dt><span class="section"><a href="boost_optional/tutorial/in_place_factories.html">In-Place
       Factories</a></span></dt>
-<dt><span class="section"><a href="boost_optional/tutorial/a_note_about_optional_bool_.html">A
-      note about optional&lt;bool&gt;</a></span></dt>
+<dt><span class="section"><a href="boost_optional/tutorial/gotchas.html">Gotchas</a></span></dt>
 <dt><span class="section"><a href="boost_optional/tutorial/exception_safety_guarantees.html">Exception
       Safety Guarantees</a></span></dt>
 <dt><span class="section"><a href="boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>
@@ -144,7 +143,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: March 06, 2016 at 18:30:08 GMT</small></p></td>
+<td align="left"><p><small>Last revised: September 16, 2016 at 23:43:36 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

doc/html/optional/tutorial.html

@@ -38,8 +38,7 @@
       references</a></span></dt>
 <dt><span class="section"><a href="../boost_optional/tutorial/in_place_factories.html">In-Place
       Factories</a></span></dt>
-<dt><span class="section"><a href="../boost_optional/tutorial/a_note_about_optional_bool_.html">A
-      note about optional&lt;bool&gt;</a></span></dt>
+<dt><span class="section"><a href="../boost_optional/tutorial/gotchas.html">Gotchas</a></span></dt>
 <dt><span class="section"><a href="../boost_optional/tutorial/exception_safety_guarantees.html">Exception
       Safety Guarantees</a></span></dt>
 <dt><span class="section"><a href="../boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>

include/boost/optional/optional_fwd.hpp

@@ -16,7 +16,7 @@
 #ifndef BOOST_OPTIONAL_OPTIONAL_FWD_FLC_19NOV2002_HPP
 #define BOOST_OPTIONAL_OPTIONAL_FWD_FLC_19NOV2002_HPP
 
-#include <boost/config/suffix.hpp>
+#include <boost/config.hpp>
 
 namespace boost {