Create a development branch for the hash library.

[SVN r38869]

doc/Jamfile.v2

@@ -0,0 +1,28 @@
+# Boost.Optional
+#
+# Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+
+# Quickbook
+# -----------------------------------------------------------------------------
+
+import quickbook ;
+
+xml optional
+    :
+        optional.qbk
+    ;
+
+boostbook standalone
+    :
+        optional
+    :
+        <xsl:param>toc.max.depth=1
+        <xsl:param>toc.section.depth=1
+        <xsl:param>chunk.section.depth=1
+    ;
+

doc/acknowledgments.qbk

@@ -0,0 +1,60 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+[section Acknowledgments]
+
+[heading Pre-formal review]
+
+* Peter Dimov suggested the name 'optional', and was the first to point out
+the need for aligned storage.
+* Douglas Gregor developed 'type_with_alignment', and later Eric Friedman
+coded 'aligned_storage', which are the core of the optional class
+implementation.
+* Andrei Alexandrescu and Brian Parker also worked with aligned storage
+techniques and their work influenced the current implementation.
+* Gennadiy Rozental made extensive and important comments which shaped the
+design.
+* Vesa Karvonen and Douglas Gregor made quite useful comparisons between
+optional, variant and any; and made other relevant comments.
+* Douglas Gregor and Peter Dimov commented on comparisons and evaluation
+in boolean contexts.
+* Eric Friedman helped understand the issues involved with aligned storage,
+move/copy operations and exception safety.
+* Many others have participated with useful comments: Aleksey Gurotov,
+Kevlin Henney, David Abrahams, and others I can't recall.
+
+[heading Post-formal review]
+
+* William Kempf carefully considered the originally proposed interface
+and suggested the new interface which is currently used. He also started and
+fueled the discussion about the analogy optional<>/smart pointer and about
+relational operators.
+* Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson
+focused on the relational semantics of optional (originally undefined);
+concluding with the fact that the pointer-like interface doesn't make it a
+pointer so it shall have deep relational operators.
+* Augustus Saunders also explored the different relational semantics between
+optional<> and a pointer and developed the OptionalPointee concept as an aid
+against potential conflicts on generic code.
+* Joel de Guzman noticed that optional<> can be seen as an API on top of
+variant<T,nil_t>.
+* Dave Gomboc explained the meaning and usage of the Haskell analog to
+optional<>: the Maybe type constructor (analogy originally pointed out by
+David Sankel).
+* Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey,
+Rob Stewart, and others.
+* Joel de Guzman made the case for the support of references and helped
+with the proper semantics.
+* Mat Marcus shown the virtues of a value-oriented interface, influencing
+the current design, and contributed the idea of "none".
+
+[endsect]
+

doc/dependencies.qbk

@@ -0,0 +1,17 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+[section Dependencies and Portability]
+
+The implementation uses `type_traits/alignment_of.hpp` and
+`type_traits/type_with_alignment.hpp`
+
+[endsect]

doc/development.qbk

@@ -0,0 +1,251 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section Development]
+
+[section The models]
+
+In C++, we can ['declare] an object (a variable) of type `T`, and we can give this
+variable an ['initial value] (through an ['initializer]. (c.f. 8.5)).
+When a declaration includes a non-empty initializer (an initial value is given),
+it is said that the object has been initialized.
+If the declaration uses an empty initializer (no initial value is given), and
+neither default nor value initialization applies, it is said that the object is
+[*uninitialized]. Its actual value exist but has an ['indeterminate initial value]
+(c.f. 8.5.9).
+`optional<T>` intends to formalize the notion of initialization (or lack of it)
+allowing a program to test whether an object has been initialized and stating
+that access to the value of an uninitialized object is undefined behavior. That
+is, when a variable is declared as `optional<T>` and no initial value is given,
+the variable is ['formally] uninitialized. A formally uninitialized optional object
+has conceptually no value at all and this situation can be tested at runtime. It
+is formally ['undefined behavior] to try to access the value of an uninitialized
+optional. An uninitialized optional can be assigned a value, in which case its initialization state changes to initialized. Furthermore, given the formal
+treatment of initialization states in optional objects, it is even possible to
+reset an optional to ['uninitialized].
+
+In C++ there is no formal notion of uninitialized objects, which means that
+objects always have an initial value even if indeterminate.
+As discussed on the previous section, this has a drawback because you need
+additional information to tell if an object has been effectively initialized.
+One of the typical ways in which this has been historically dealt with is via
+a special value: `EOF`, `npos`, -1, etc... This is equivalent to adding the
+special value to the set of possible values of a given type. This super set of
+`T` plus some ['nil_t]—were `nil_t` is some stateless POD-can be modeled in modern
+languages as a [*discriminated union] of T and nil_t. Discriminated unions are
+often called ['variants]. A variant has a ['current type], which in our case is either
+`T` or `nil_t`.
+Using the __BOOST_VARIANT__ library, this model can be implemented in terms of `boost::variant<T,nil_t>`.
+There is precedent for a discriminated union as a model for an optional value:
+the __HASKELL__ [*Maybe] built-in type constructor. Thus, a discriminated union
+`T+nil_t` serves as a conceptual foundation.
+
+A `variant<T,nil_t>` follows naturally from the traditional idiom of extending
+the range of possible values adding an additional sentinel value with the
+special meaning of ['Nothing].  However, this additional ['Nothing] value is largely
+irrelevant for our purpose since our goal is to formalize the notion of
+uninitialized objects and, while a special extended value can be used to convey
+that meaning, it is not strictly necessary in order to do so.
+
+The observation made in the last paragraph about the irrelevant nature of the
+additional `nil_t` with respect to [_purpose] of `optional<T>` suggests an 
+alternative model: a ['container] that either has a value of `T` or nothing.
+
+As of this writing I don't know of any precedence for a variable-size
+fixed-capacity (of 1) stack-based container model for optional values, yet I
+believe this is the consequence of the lack of practical implementations of
+such a container rather than an inherent shortcoming of the container model.
+
+In any event, both the discriminated-union or the single-element container
+models serve as a conceptual ground for a class representing optional—i.e.
+possibly uninitialized—objects.
+For instance, these models show the ['exact] semantics required for a wrapper
+of optional values:
+
+Discriminated-union:
+
+* [*deep-copy] semantics: copies of the variant implies copies of the value.
+* [*deep-relational] semantics: comparisons between variants matches both
+current types and values
+* If the variant's current type is `T`, it is modeling an ['initialized] optional.
+* If the variant's current type is not `T`, it is modeling an ['uninitialized]
+optional.
+* Testing if the variant's current type is `T` models testing if the optional
+is initialized
+* Trying to extract a `T` from a variant when its current type is not `T`, models
+the undefined behavior of trying to access the value of an uninitialized optional
+
+Single-element container:
+
+* [*deep-copy] semantics: copies of the container implies copies of the value.
+* [*deep-relational] semantics: comparisons between containers compare container
+size and if match, contained value
+* If the container is not empty (contains an object of type `T`), it is modeling
+an ['initialized] optional.
+* If the container is empty, it is modeling an ['uninitialized] optional.
+* Testing if the container is empty models testing if the optional is
+initialized
+* Trying to extract a `T` from an empty container models the undefined behavior
+of trying to access the value of an uninitialized optional
+
+[endsect]
+
+[section The semantics]
+
+Objects of type `optional<T>` are intended to be used in places where objects of
+type `T` would but which might be uninitialized. Hence, `optional<T>`'s purpose is
+to formalize the additional possibly uninitialized state.
+From the perspective of this role, `optional<T>` can have the same operational
+semantics of `T` plus the additional semantics corresponding to this special
+state.
+As such, `optional<T>` could be thought of as a ['supertype] of `T`. Of course, we 
+can't do that in C++, so we need to compose the desired semantics using a
+different mechanism.
+Doing it the other way around, that is, making `optional<T>` a ['subtype] of `T`
+is not only conceptually wrong but also impractical: it is not allowed to
+derive from a non-class type, such as a built-in type.
+
+We can draw from the purpose of `optional<T>` the required basic semantics:
+
+* [*Default Construction:] To introduce a formally uninitialized wrapped
+object.
+* [*Direct Value Construction via copy:] To introduce a formally initialized
+wrapped object whose value is obtained as a copy of some object.
+* [*Deep Copy Construction:] To obtain a new yet equivalent wrapped object.
+* [*Direct Value Assignment (upon initialized):] To assign a value to the
+wrapped object.
+* [*Direct Value Assignment (upon uninitialized):] To initialize the wrapped
+object with a value obtained as a copy of some object.
+* [*Assignment (upon initialized):] To assign to the wrapped object the value
+of another wrapped object.
+* [*Assignment (upon uninitialized):] To initialize the wrapped object with
+value of another wrapped object.
+* [*Deep Relational Operations (when supported by the type T):] To compare
+wrapped object values taking into account the presence of uninitialized states.
+* [*Value access:] To unwrap the wrapped object.
+* [*Initialization state query:] To determine if the object is formally
+initialized or not.
+* [*Swap:] To exchange wrapped objects. (with whatever exception safety
+guarantees are provided by `T`'s swap).
+* [*De-initialization:] To release the wrapped object (if any) and leave the
+wrapper in the uninitialized state.
+
+Additional operations are useful, such as converting constructors and
+converting assignments, in-place construction and assignment, and safe
+value access via a pointer to the wrapped object or null.
+
+[endsect]
+
+[section The Interface]
+
+Since the purpose of optional is to allow us to use objects with a formal
+uninitialized additional state, the interface could try to follow the
+interface of the underlying `T` type as much as possible. In order to choose
+the proper degree of adoption of the native `T` interface, the following must
+be noted: Even if all the operations supported by an instance of type `T` are
+defined for the entire range of values for such a type, an `optional<T>`
+extends such a set of values with a new value for which most
+(otherwise valid) operations are not defined in terms of `T`.
+
+Furthermore, since `optional<T>` itself is merely a `T` wrapper (modeling a `T`
+supertype), any attempt to define such operations upon uninitialized optionals
+will be totally artificial w.r.t. `T`.
+
+This library chooses an interface which follows from `T`'s interface only for
+those operations which are well defined (w.r.t the type `T`) even if any of the
+operands are uninitialized. These operations include: construction,
+copy-construction, assignment, swap and relational operations.
+
+For the value access operations, which are undefined (w.r.t the type `T`) when
+the operand is uninitialized, a different interface is chosen (which will be
+explained next).
+
+Also, the presence of the possibly uninitialized state requires additional
+operations not provided by `T` itself which are supported by a special interface.
+
+[heading Lexically-hinted Value Access in the presence of possibly
+untitialized optional objects: The operators * and ->]
+
+A relevant feature of a pointer is that it can have a [*null pointer value].
+This is a ['special] value which is used to indicate that the pointer is not
+referring to any object at all. In other words, null pointer values convey
+the notion of inexistent objects.
+
+This meaning of the null pointer value allowed pointers to became a ['de
+facto] standard for handling optional objects because all you have to do
+to refer to a value which you don't really have is to use a null pointer
+value of the appropriate type. Pointers have been used for decades—from
+the days of C APIs to modern C++ libraries—to ['refer] to optional (that is,
+possibly inexistent) objects; particularly as optional arguments to a
+function, but also quite often as optional data members.
+
+The possible presence of a null pointer value makes the operations that
+access the pointee's value possibly undefined, therefore, expressions which
+use dereference and access operators, such as: `( *p = 2 )` and `( p->foo() )`,
+implicitly convey the notion of optionality, and this information is tied to
+the ['syntax] of the expressions. That is, the presence of operators `*` and `->`
+tell by themselves —without any additional context— that the expression will
+be undefined unless the implied pointee actually exist.
+
+Such a ['de facto] idiom for referring to optional objects can be formalized
+in the form of a concept: the __OPTIONAL_POINTEE__ concept.
+This concept captures the syntactic usage of operators `*`, `->` and
+conversion to `bool` to convey the notion of optionality.
+
+However, pointers are good to [_refer] to optional objects, but not particularly
+good to handle the optional objects in all other respects, such as initializing
+or moving/copying them. The problem resides in the shallow-copy of pointer
+semantics: if you need to effectively move or copy the object, pointers alone
+are not enough. The problem is that copies of pointers do not imply copies of
+pointees. For example, as was discussed in the motivation, pointers alone
+cannot be used to return optional objects from a function because the object
+must move outside from the function and into the caller's context.
+
+A solution to the shallow-copy problem that is often used is to resort to
+dynamic allocation and use a smart pointer to automatically handle the details
+of this. For example, if a function is to optionally return an object `X`, it can
+use `shared_ptr<X>` as the return value. However, this requires dynamic allocation
+of `X`. If `X` is a built-in or small POD, this technique is very poor in terms of
+required resources. Optional objects are essentially values so it is very
+convenient to be able to use automatic storage and deep-copy semantics to
+manipulate optional values just as we do with ordinary values. Pointers do
+not have this semantics, so are inappropriate for the initialization and
+transport of optional values, yet are quite convenient for handling the access
+to the possible undefined value because of the idiomatic aid present in the
+__OPTIONAL_POINTEE__ concept incarnated by pointers.
+
+
+[heading Optional<T> as a model of OptionalPointee]
+
+For value access operations `optional<>` uses operators `*` and `->` to
+lexically warn about the possibly uninitialized state appealing to the
+familiar pointer semantics w.r.t. to null pointers.
+
+[warning
+However, it is particularly important to note that `optional<>` objects
+are not pointers. [_`optional<>` is not, and does not model, a pointer].
+]
+
+For instance, `optional<>` does not have shallow-copy so does not alias:
+two different optionals never refer to the ['same] value unless `T` itself is
+a reference (but may have ['equivalent] values).
+The difference between an `optional<T>` and a pointer must be kept in mind,
+particularly because the semantics of relational operators are different:
+since `optional<T>` is a value-wrapper, relational operators are deep: they
+compare optional values; but relational operators for pointers are shallow:
+they do not compare pointee values.
+As a result, you might be able to replace `optional<T>` by `T*` on some
+situations but not always. Specifically, on generic code written for both,
+you cannot use relational operators directly, and must use the template
+functions __FUNCTION_EQUAL_POINTEES__ and __FUNCTION_LESS_POINTEES__ instead.
+
+[endsect]
+
+[endsect]

doc/examples.qbk

@@ -0,0 +1,102 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+[section Examples]
+
+[section Optional return values]
+
+    optional<char> get_async_input()
+    {
+        if ( !queue.empty() )
+            return optional<char>(queue.top());
+        else return optional<char>(); // uninitialized
+    }
+
+    void receive_async_message()
+    {
+        optional<char> rcv ;
+        // The safe boolean conversion from 'rcv' is used here.
+        while ( (rcv = get_async_input()) && !timeout() )
+            output(*rcv);
+    }
+
+[endsect]
+
+[section Optional local variables]
+
+    optional<string> name ;
+    if ( database.open() )
+    {
+        name.reset ( database.lookup(employer_name) ) ;
+    }
+    else
+    {
+        if ( can_ask_user )
+            name.reset ( user.ask(employer_name) ) ;
+    }
+
+    if ( name )
+        print(*name);
+    else print("employer's name not found!");
+
+[endsect]
+
+[section Optional data members]
+
+    class figure
+    {
+        public:
+
+        figure()
+        {
+            // data member 'm_clipping_rect' is uninitialized at this point.
+        }
+
+        void clip_in_rect ( rect const& rect )
+        {
+            ....
+            m_clipping_rect.reset ( rect ) ; // initialized here.
+        }
+
+        void draw ( canvas& cvs )
+        {
+            if ( m_clipping_rect )
+                do_clipping(*m_clipping_rect);
+
+            cvs.drawXXX(..);
+        }
+
+        // this can return NULL.
+        rect const* get_clipping_rect() { return get_pointer(m_clipping_rect); }
+
+        private :
+
+        optional<rect> m_clipping_rect ;
+
+    };
+
+[endsect]
+
+[section Bypassing expensive unnecessary default construction]
+
+    class ExpensiveCtor { ... } ;
+    class Fred
+    {
+        Fred() : mLargeVector(10000) {}
+
+        std::vector< optional<ExpensiveCtor> > mLargeVector ;
+    } ;
+
+[endsect]
+
+[endsect]
+
+ 

doc/html/HTML.manifest

@@ -0,0 +1,14 @@
+index.html
+boost_optional/development.html
+boost_optional/synopsis.html
+boost_optional/detailed_semantics.html
+boost_optional/examples.html
+boost_optional/optional_references.html
+boost_optional/rebinding_semantics_for_assignment_of_optional_references.html
+boost_optional/in_place_factories.html
+boost_optional/a_note_about_optional_bool_.html
+boost_optional/exception_safety_guarantees.html
+boost_optional/type_requirements.html
+boost_optional/implementation_notes.html
+boost_optional/dependencies_and_portability.html
+boost_optional/acknowledgments.html

doc/html/boost_optional/a_note_about_optional_bool_.html

@@ -0,0 +1,84 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>A note about
+    optional&lt;bool&gt;</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="in_place_factories.html" title="In-Place Factories">
+<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%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="in_place_factories.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="exception_safety_guarantees.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.a_note_about_optional_bool_"></a><a href="a_note_about_optional_bool_.html" title="A note about
+    optional&lt;bool&gt;">A note about
+    optional&lt;bool&gt;</a>
+</h2></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="../../../../tribool/index.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, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>
+      provides an implicit conversion to <code class="computeroutput"><span class="keyword">bool</span></code>.
+      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>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="in_place_factories.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="exception_safety_guarantees.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/acknowledgments.html

@@ -0,0 +1,122 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Acknowledgments</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="dependencies_and_portability.html" title="Dependencies
+    and Portability">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dependencies_and_portability.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.acknowledgments"></a><a href="acknowledgments.html" title="Acknowledgments">Acknowledgments</a>
+</h2></div></div></div>
+<a name="boost_optional.acknowledgments.pre_formal_review"></a><h4>
+<a name="id2644860"></a>
+      <a href="acknowledgments.html#boost_optional.acknowledgments.pre_formal_review">Pre-formal
+      review</a>
+    </h4>
+<div class="itemizedlist"><ul type="disc">
+<li>
+        Peter Dimov suggested the name 'optional', and was the first to point out
+        the need for aligned storage.
+      </li>
+<li>
+        Douglas Gregor developed 'type_with_alignment', and later Eric Friedman coded
+        'aligned_storage', which are the core of the optional class implementation.
+      </li>
+<li>
+        Andrei Alexandrescu and Brian Parker also worked with aligned storage techniques
+        and their work influenced the current implementation.
+      </li>
+<li>
+        Gennadiy Rozental made extensive and important comments which shaped the
+        design.
+      </li>
+<li>
+        Vesa Karvonen and Douglas Gregor made quite useful comparisons between optional,
+        variant and any; and made other relevant comments.
+      </li>
+<li>
+        Douglas Gregor and Peter Dimov commented on comparisons and evaluation in
+        boolean contexts.
+      </li>
+<li>
+        Eric Friedman helped understand the issues involved with aligned storage,
+        move/copy operations and exception safety.
+      </li>
+<li>
+        Many others have participated with useful comments: Aleksey Gurotov, Kevlin
+        Henney, David Abrahams, and others I can't recall.
+      </li>
+</ul></div>
+<a name="boost_optional.acknowledgments.post_formal_review"></a><h4>
+<a name="id2644931"></a>
+      <a href="acknowledgments.html#boost_optional.acknowledgments.post_formal_review">Post-formal
+      review</a>
+    </h4>
+<div class="itemizedlist"><ul type="disc">
+<li>
+        William Kempf carefully considered the originally proposed interface and
+        suggested the new interface which is currently used. He also started and
+        fueled the discussion about the analogy optional&lt;&gt;/smart pointer and
+        about relational operators.
+      </li>
+<li>
+        Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson
+        focused on the relational semantics of optional (originally undefined); concluding
+        with the fact that the pointer-like interface doesn't make it a pointer so
+        it shall have deep relational operators.
+      </li>
+<li>
+        Augustus Saunders also explored the different relational semantics between
+        optional&lt;&gt; and a pointer and developed the OptionalPointee concept
+        as an aid against potential conflicts on generic code.
+      </li>
+<li>
+        Joel de Guzman noticed that optional&lt;&gt; can be seen as an API on top
+        of variant&lt;T,nil_t&gt;.
+      </li>
+<li>
+        Dave Gomboc explained the meaning and usage of the Haskell analog to optional&lt;&gt;:
+        the Maybe type constructor (analogy originally pointed out by David Sankel).
+      </li>
+<li>
+        Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey, Rob
+        Stewart, and others.
+      </li>
+<li>
+        Joel de Guzman made the case for the support of references and helped with
+        the proper semantics.
+      </li>
+<li>
+        Mat Marcus shown the virtues of a value-oriented interface, influencing the
+        current design, and contributed the idea of "none".
+      </li>
+</ul></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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="dependencies_and_portability.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/dependencies_and_portability.html

@@ -0,0 +1,46 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Dependencies
+    and Portability</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="implementation_notes.html" title="Implementation Notes">
+<link rel="next" href="acknowledgments.html" title="Acknowledgments">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="implementation_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.dependencies_and_portability"></a><a href="dependencies_and_portability.html" title="Dependencies
+    and Portability">Dependencies
+    and Portability</a>
+</h2></div></div></div>
+<p>
+      The implementation uses <code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">alignment_of</span><span class="special">.</span><span class="identifier">hpp</span></code> and
+      <code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">type_with_alignment</span><span class="special">.</span><span class="identifier">hpp</span></code>
+    </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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="implementation_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/development.html

@@ -0,0 +1,415 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Development</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="next" href="synopsis.html" title="Synopsis">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="synopsis.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.development"></a><a href="development.html" title="Development">Development</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="development.html#boost_optional.development.the_models">The models</a></span></dt>
+<dt><span class="section"><a href="development.html#boost_optional.development.the_semantics">The semantics</a></span></dt>
+<dt><span class="section"><a href="development.html#boost_optional.development.the_interface">The Interface</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.development.the_models"></a><a href="development.html#boost_optional.development.the_models" title="The models">The models</a>
+</h3></div></div></div>
+<p>
+        In C++, we can <span class="emphasis"><em>declare</em></span> an object (a variable) of type
+        <code class="computeroutput"><span class="identifier">T</span></code>, and we can give this variable
+        an <span class="emphasis"><em>initial value</em></span> (through an <span class="emphasis"><em>initializer</em></span>.
+        (c.f. 8.5)). When a declaration includes a non-empty initializer (an initial
+        value is given), it is said that the object has been initialized. If the
+        declaration uses an empty initializer (no initial value is given), and neither
+        default nor value initialization applies, it is said that the object is
+        <span class="bold"><strong>uninitialized</strong></span>. Its actual value exist but
+        has an <span class="emphasis"><em>indeterminate initial value</em></span> (c.f. 8.5.9). <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> intends
+        to formalize the notion of initialization (or lack of it) allowing a program
+        to test whether an object has been initialized and stating that access to
+        the value of an uninitialized object is undefined behavior. That is, when
+        a variable is declared as <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 no initial value is given, the variable is <span class="emphasis"><em>formally</em></span>
+        uninitialized. A formally uninitialized optional object has conceptually
+        no value at all and this situation can be tested at runtime. It is formally
+        <span class="emphasis"><em>undefined behavior</em></span> to try to access the value of an
+        uninitialized optional. An uninitialized optional can be assigned a value,
+        in which case its initialization state changes to initialized. Furthermore,
+        given the formal treatment of initialization states in optional objects,
+        it is even possible to reset an optional to <span class="emphasis"><em>uninitialized</em></span>.
+      </p>
+<p>
+        In C++ there is no formal notion of uninitialized objects, which means that
+        objects always have an initial value even if indeterminate. As discussed
+        on the previous section, this has a drawback because you need additional
+        information to tell if an object has been effectively initialized. One of
+        the typical ways in which this has been historically dealt with is via a
+        special value: <code class="computeroutput"><span class="identifier">EOF</span></code>, <code class="computeroutput"><span class="identifier">npos</span></code>, -1, etc... This is equivalent to
+        adding the special value to the set of possible values of a given type. This
+        super set of <code class="computeroutput"><span class="identifier">T</span></code> plus some
+        <span class="emphasis"><em>nil_t</em></span>&#8212;were <code class="computeroutput"><span class="identifier">nil_t</span></code>
+        is some stateless POD-can be modeled in modern languages as a <span class="bold"><strong>discriminated
+        union</strong></span> of T and nil_t. Discriminated unions are often called <span class="emphasis"><em>variants</em></span>.
+        A variant has a <span class="emphasis"><em>current type</em></span>, which in our case is either
+        <code class="computeroutput"><span class="identifier">T</span></code> or <code class="computeroutput"><span class="identifier">nil_t</span></code>.
+        Using the <a href="../../../../variant/index.html" target="_top">Boost.Variant</a>
+        library, this model can be implemented in terms of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">&gt;</span></code>.
+        There is precedent for a discriminated union as a model for an optional value:
+        the <a href="http://www.haskell.org/" target="_top">Haskell</a> <span class="bold"><strong>Maybe</strong></span>
+        built-in type constructor. Thus, a discriminated union <code class="computeroutput"><span class="identifier">T</span><span class="special">+</span><span class="identifier">nil_t</span></code>
+        serves as a conceptual foundation.
+      </p>
+<p>
+        A <code class="computeroutput"><span class="identifier">variant</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">&gt;</span></code> follows naturally from the traditional
+        idiom of extending the range of possible values adding an additional sentinel
+        value with the special meaning of <span class="emphasis"><em>Nothing</em></span>. However,
+        this additional <span class="emphasis"><em>Nothing</em></span> value is largely irrelevant
+        for our purpose since our goal is to formalize the notion of uninitialized
+        objects and, while a special extended value can be used to convey that meaning,
+        it is not strictly necessary in order to do so.
+      </p>
+<p>
+        The observation made in the last paragraph about the irrelevant nature of
+        the additional <code class="computeroutput"><span class="identifier">nil_t</span></code> with
+        respect to <span class="underline">purpose</span> of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> suggests
+        an alternative model: a <span class="emphasis"><em>container</em></span> that either has a
+        value of <code class="computeroutput"><span class="identifier">T</span></code> or nothing.
+      </p>
+<p>
+        As of this writing I don't know of any precedence for a variable-size fixed-capacity
+        (of 1) stack-based container model for optional values, yet I believe this
+        is the consequence of the lack of practical implementations of such a container
+        rather than an inherent shortcoming of the container model.
+      </p>
+<p>
+        In any event, both the discriminated-union or the single-element container
+        models serve as a conceptual ground for a class representing optional&#8212;i.e.
+        possibly uninitialized&#8212;objects. For instance, these models show the <span class="emphasis"><em>exact</em></span>
+        semantics required for a wrapper of optional values:
+      </p>
+<p>
+        Discriminated-union:
+      </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the variant
+          implies copies of the value.
+        </li>
+<li>
+<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
+          between variants matches both current types and values
+        </li>
+<li>
+          If the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>,
+          it is modeling an <span class="emphasis"><em>initialized</em></span> optional.
+        </li>
+<li>
+          If the variant's current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
+          it is modeling an <span class="emphasis"><em>uninitialized</em></span> optional.
+        </li>
+<li>
+          Testing if the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>
+          models testing if the optional is initialized
+        </li>
+<li>
+          Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code> from
+          a variant when its current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
+          models the undefined behavior of trying to access the value of an uninitialized
+          optional
+        </li>
+</ul></div>
+<p>
+        Single-element container:
+      </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the container
+          implies copies of the value.
+        </li>
+<li>
+<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
+          between containers compare container size and if match, contained value
+        </li>
+<li>
+          If the container is not empty (contains an object of type <code class="computeroutput"><span class="identifier">T</span></code>), it is modeling an <span class="emphasis"><em>initialized</em></span>
+          optional.
+        </li>
+<li>
+          If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
+          optional.
+        </li>
+<li>
+          Testing if the container is empty models testing if the optional is initialized
+        </li>
+<li>
+          Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code> from
+          an empty container models the undefined behavior of trying to access the
+          value of an uninitialized optional
+        </li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.development.the_semantics"></a><a href="development.html#boost_optional.development.the_semantics" title="The semantics">The semantics</a>
+</h3></div></div></div>
+<p>
+        Objects of type <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        are intended to be used in places where objects of type <code class="computeroutput"><span class="identifier">T</span></code>
+        would but which might be uninitialized. Hence, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>'s
+        purpose is to formalize the additional possibly uninitialized state. From
+        the perspective of this role, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        can have the same operational semantics of <code class="computeroutput"><span class="identifier">T</span></code>
+        plus the additional semantics corresponding to this special state. As such,
+        <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> could
+        be thought of as a <span class="emphasis"><em>supertype</em></span> of <code class="computeroutput"><span class="identifier">T</span></code>.
+        Of course, we can't do that in C++, so we need to compose the desired semantics
+        using a different mechanism. Doing it the other way around, that is, making
+        <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> a
+        <span class="emphasis"><em>subtype</em></span> of <code class="computeroutput"><span class="identifier">T</span></code>
+        is not only conceptually wrong but also impractical: it is not allowed to
+        derive from a non-class type, such as a built-in type.
+      </p>
+<p>
+        We can draw from the purpose of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        the required basic semantics:
+      </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<span class="bold"><strong>Default Construction:</strong></span> To introduce a formally
+          uninitialized wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Direct Value Construction via copy:</strong></span> To
+          introduce a formally initialized wrapped object whose value is obtained
+          as a copy of some object.
+        </li>
+<li>
+<span class="bold"><strong>Deep Copy Construction:</strong></span> To obtain a new
+          yet equivalent wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Direct Value Assignment (upon initialized):</strong></span>
+          To assign a value to the wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Direct Value Assignment (upon uninitialized):</strong></span>
+          To initialize the wrapped object with a value obtained as a copy of some
+          object.
+        </li>
+<li>
+<span class="bold"><strong>Assignment (upon initialized):</strong></span> To assign
+          to the wrapped object the value of another wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Assignment (upon uninitialized):</strong></span> To initialize
+          the wrapped object with value of another wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Deep Relational Operations (when supported by the
+          type T):</strong></span> To compare wrapped object values taking into account
+          the presence of uninitialized states.
+        </li>
+<li>
+<span class="bold"><strong>Value access:</strong></span> To unwrap the wrapped object.
+        </li>
+<li>
+<span class="bold"><strong>Initialization state query:</strong></span> To determine
+          if the object is formally initialized or not.
+        </li>
+<li>
+<span class="bold"><strong>Swap:</strong></span> To exchange wrapped objects. (with
+          whatever exception safety guarantees are provided by <code class="computeroutput"><span class="identifier">T</span></code>'s
+          swap).
+        </li>
+<li>
+<span class="bold"><strong>De-initialization:</strong></span> To release the wrapped
+          object (if any) and leave the wrapper in the uninitialized state.
+        </li>
+</ul></div>
+<p>
+        Additional operations are useful, such as converting constructors and converting
+        assignments, in-place construction and assignment, and safe value access
+        via a pointer to the wrapped object or null.
+      </p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.development.the_interface"></a><a href="development.html#boost_optional.development.the_interface" title="The Interface">The Interface</a>
+</h3></div></div></div>
+<p>
+        Since the purpose of optional is to allow us to use objects with a formal
+        uninitialized additional state, the interface could try to follow the interface
+        of the underlying <code class="computeroutput"><span class="identifier">T</span></code> type
+        as much as possible. In order to choose the proper degree of adoption of
+        the native <code class="computeroutput"><span class="identifier">T</span></code> interface, the
+        following must be noted: Even if all the operations supported by an instance
+        of type <code class="computeroutput"><span class="identifier">T</span></code> are defined for
+        the entire range of values for such a type, an <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        extends such a set of values with a new value for which most (otherwise valid)
+        operations are not defined in terms of <code class="computeroutput"><span class="identifier">T</span></code>.
+      </p>
+<p>
+        Furthermore, since <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        itself is merely a <code class="computeroutput"><span class="identifier">T</span></code> wrapper
+        (modeling a <code class="computeroutput"><span class="identifier">T</span></code> supertype),
+        any attempt to define such operations upon uninitialized optionals will be
+        totally artificial w.r.t. <code class="computeroutput"><span class="identifier">T</span></code>.
+      </p>
+<p>
+        This library chooses an interface which follows from <code class="computeroutput"><span class="identifier">T</span></code>'s
+        interface only for those operations which are well defined (w.r.t the type
+        <code class="computeroutput"><span class="identifier">T</span></code>) even if any of the operands
+        are uninitialized. These operations include: construction, copy-construction,
+        assignment, swap and relational operations.
+      </p>
+<p>
+        For the value access operations, which are undefined (w.r.t the type <code class="computeroutput"><span class="identifier">T</span></code>) when the operand is uninitialized, a
+        different interface is chosen (which will be explained next).
+      </p>
+<p>
+        Also, the presence of the possibly uninitialized state requires additional
+        operations not provided by <code class="computeroutput"><span class="identifier">T</span></code>
+        itself which are supported by a special interface.
+      </p>
+<a name="boost_optional.development.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_"></a><h5>
+<a name="id2615242"></a>
+        <a href="development.html#boost_optional.development.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_">Lexically-hinted
+        Value Access in the presence of possibly untitialized optional objects: The
+        operators * and -&gt;</a>
+      </h5>
+<p>
+        A relevant feature of a pointer is that it can have a <span class="bold"><strong>null
+        pointer value</strong></span>. This is a <span class="emphasis"><em>special</em></span> value which
+        is used to indicate that the pointer is not referring to any object at all.
+        In other words, null pointer values convey the notion of inexistent objects.
+      </p>
+<p>
+        This meaning of the null pointer value allowed pointers to became a <span class="emphasis"><em>de
+        facto</em></span> standard for handling optional objects because all you have
+        to do to refer to a value which you don't really have is to use a null pointer
+        value of the appropriate type. Pointers have been used for decades&#8212;from
+        the days of C APIs to modern C++ libraries&#8212;to <span class="emphasis"><em>refer</em></span>
+        to optional (that is, possibly inexistent) objects; particularly as optional
+        arguments to a function, but also quite often as optional data members.
+      </p>
+<p>
+        The possible presence of a null pointer value makes the operations that access
+        the pointee's value possibly undefined, therefore, expressions which use
+        dereference and access operators, such as: <code class="computeroutput"><span class="special">(</span>
+        <span class="special">*</span><span class="identifier">p</span> <span class="special">=</span> <span class="number">2</span> <span class="special">)</span></code>
+        and <code class="computeroutput"><span class="special">(</span> <span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">foo</span><span class="special">()</span> <span class="special">)</span></code>, implicitly
+        convey the notion of optionality, and this information is tied to the <span class="emphasis"><em>syntax</em></span>
+        of the expressions. That is, the presence of operators <code class="computeroutput"><span class="special">*</span></code>
+        and <code class="computeroutput"><span class="special">-&gt;</span></code> tell by themselves
+        &#8212;without any additional context&#8212; that the expression will be undefined
+        unless the implied pointee actually exist.
+      </p>
+<p>
+        Such a <span class="emphasis"><em>de facto</em></span> idiom for referring to optional objects
+        can be formalized in the form of a concept: the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>
+        concept. This concept captures the syntactic usage of operators <code class="computeroutput"><span class="special">*</span></code>, <code class="computeroutput"><span class="special">-&gt;</span></code>
+        and conversion to <code class="computeroutput"><span class="keyword">bool</span></code> to convey
+        the notion of optionality.
+      </p>
+<p>
+        However, pointers are good to <span class="underline">refer</span>
+        to optional objects, but not particularly good to handle the optional objects
+        in all other respects, such as initializing or moving/copying them. The problem
+        resides in the shallow-copy of pointer semantics: if you need to effectively
+        move or copy the object, pointers alone are not enough. The problem is that
+        copies of pointers do not imply copies of pointees. For example, as was discussed
+        in the motivation, pointers alone cannot be used to return optional objects
+        from a function because the object must move outside from the function and
+        into the caller's context.
+      </p>
+<p>
+        A solution to the shallow-copy problem that is often used is to resort to
+        dynamic allocation and use a smart pointer to automatically handle the details
+        of this. For example, if a function is to optionally return an object <code class="computeroutput"><span class="identifier">X</span></code>, it can use <code class="computeroutput"><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span></code>
+        as the return value. However, this requires dynamic allocation of <code class="computeroutput"><span class="identifier">X</span></code>. If <code class="computeroutput"><span class="identifier">X</span></code>
+        is a built-in or small POD, this technique is very poor in terms of required
+        resources. Optional objects are essentially values so it is very convenient
+        to be able to use automatic storage and deep-copy semantics to manipulate
+        optional values just as we do with ordinary values. Pointers do not have
+        this semantics, so are inappropriate for the initialization and transport
+        of optional values, yet are quite convenient for handling the access to the
+        possible undefined value because of the idiomatic aid present in the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a> concept
+        incarnated by pointers.
+      </p>
+<a name="boost_optional.development.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee"></a><h5>
+<a name="id2615580"></a>
+        <a href="development.html#boost_optional.development.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional&lt;T&gt;
+        as a model of OptionalPointee</a>
+      </h5>
+<p>
+        For value access operations <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> uses operators <code class="computeroutput"><span class="special">*</span></code>
+        and <code class="computeroutput"><span class="special">-&gt;</span></code> to lexically warn
+        about the possibly uninitialized state appealing to the familiar pointer
+        semantics w.r.t. to null pointers.
+      </p>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>
+          </p>
+<p>
+            However, it is particularly important to note that <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> objects are not pointers. <span class="underline"><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> is not, and does not model, a
+            pointer</span>.
+          </p>
+<p>
+        </p>
+</td></tr>
+</table></div>
+<p>
+        For instance, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>
+        does not have shallow-copy so does not alias: two different optionals never
+        refer to the <span class="emphasis"><em>same</em></span> value unless <code class="computeroutput"><span class="identifier">T</span></code>
+        itself is a reference (but may have <span class="emphasis"><em>equivalent</em></span> values).
+        The difference between an <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 a pointer must be kept in mind, particularly because the semantics of
+        relational operators are different: since <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        is a value-wrapper, relational operators are deep: they compare optional
+        values; but relational operators for pointers are shallow: they do not compare
+        pointee values. As a result, you might be able to replace <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        by <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code>
+        on some situations but not always. Specifically, on generic code written
+        for both, you cannot use relational operators directly, and must use the
+        template functions <a href="../../../../utility/OptionalPointee.html#equal" target="_top"><code class="computeroutput"><span class="identifier">equal_pointees</span><span class="special">()</span></code></a>
+        and <a href="../../../../utility/OptionalPointee.html#less" target="_top"><code class="computeroutput"><span class="identifier">less_pointees</span><span class="special">()</span></code></a>
+        instead.
+      </p>
+</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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="synopsis.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/examples.html

@@ -0,0 +1,151 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Examples</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="detailed_semantics.html" title="Detailed Semantics">
+<link rel="next" href="optional_references.html" title="Optional references">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="detailed_semantics.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.examples"></a><a href="examples.html" title="Examples">Examples</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_return_values">Optional
+      return values</a></span></dt>
+<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_local_variables">Optional
+      local variables</a></span></dt>
+<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_data_members">Optional
+      data members</a></span></dt>
+<dt><span class="section"><a href="examples.html#boost_optional.examples.bypassing_expensive_unnecessary_default_construction">Bypassing
+      expensive unnecessary default construction</a></span></dt>
+</dl></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.examples.optional_return_values"></a><a href="examples.html#boost_optional.examples.optional_return_values" title="Optional
+      return values">Optional
+      return values</a>
+</h3></div></div></div>
+<pre class="programlisting">
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span> <span class="identifier">get_async_input</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="keyword">if</span> <span class="special">(</span> <span class="special">!</span><span class="identifier">queue</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()</span> <span class="special">)</span>
+        <span class="keyword">return</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;(</span><span class="identifier">queue</span><span class="special">.</span><span class="identifier">top</span><span class="special">());</span>
+    <span class="keyword">else</span> <span class="keyword">return</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;();</span> <span class="comment">// uninitialized
+</span><span class="special">}</span>
+
+<span class="keyword">void</span> <span class="identifier">receive_async_message</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span> <span class="identifier">rcv</span> <span class="special">;</span>
+    <span class="comment">// The safe boolean conversion from 'rcv' is used here.
+</span>    <span class="keyword">while</span> <span class="special">(</span> <span class="special">(</span><span class="identifier">rcv</span> <span class="special">=</span> <span class="identifier">get_async_input</span><span class="special">())</span> <span class="special">&amp;&amp;</span> <span class="special">!</span><span class="identifier">timeout</span><span class="special">()</span> <span class="special">)</span>
+        <span class="identifier">output</span><span class="special">(*</span><span class="identifier">rcv</span><span class="special">);</span>
+<span class="special">}</span>
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.examples.optional_local_variables"></a><a href="examples.html#boost_optional.examples.optional_local_variables" title="Optional
+      local variables">Optional
+      local variables</a>
+</h3></div></div></div>
+<pre class="programlisting">
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">name</span> <span class="special">;</span>
+<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">database</span><span class="special">.</span><span class="identifier">open</span><span class="special">()</span> <span class="special">)</span>
+<span class="special">{</span>
+    <span class="identifier">name</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">database</span><span class="special">.</span><span class="identifier">lookup</span><span class="special">(</span><span class="identifier">employer_name</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+<span class="keyword">else</span>
+<span class="special">{</span>
+    <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">can_ask_user</span> <span class="special">)</span>
+        <span class="identifier">name</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">user</span><span class="special">.</span><span class="identifier">ask</span><span class="special">(</span><span class="identifier">employer_name</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+
+<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">name</span> <span class="special">)</span>
+    <span class="identifier">print</span><span class="special">(*</span><span class="identifier">name</span><span class="special">);</span>
+<span class="keyword">else</span> <span class="identifier">print</span><span class="special">(</span><span class="string">"employer's name not found!"</span><span class="special">);</span>
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.examples.optional_data_members"></a><a href="examples.html#boost_optional.examples.optional_data_members" title="Optional
+      data members">Optional
+      data members</a>
+</h3></div></div></div>
+<pre class="programlisting">
+<span class="keyword">class</span> <span class="identifier">figure</span>
+<span class="special">{</span>
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">figure</span><span class="special">()</span>
+    <span class="special">{</span>
+        <span class="comment">// data member 'm_clipping_rect' is uninitialized at this point.
+</span>    <span class="special">}</span>
+
+    <span class="keyword">void</span> <span class="identifier">clip_in_rect</span> <span class="special">(</span> <span class="identifier">rect</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rect</span> <span class="special">)</span>
+    <span class="special">{</span>
+        <span class="special">....</span>
+        <span class="identifier">m_clipping_rect</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">rect</span> <span class="special">)</span> <span class="special">;</span> <span class="comment">// initialized here.
+</span>    <span class="special">}</span>
+
+    <span class="keyword">void</span> <span class="identifier">draw</span> <span class="special">(</span> <span class="identifier">canvas</span><span class="special">&amp;</span> <span class="identifier">cvs</span> <span class="special">)</span>
+    <span class="special">{</span>
+        <span class="keyword">if</span> <span class="special">(</span> <span class="identifier">m_clipping_rect</span> <span class="special">)</span>
+            <span class="identifier">do_clipping</span><span class="special">(*</span><span class="identifier">m_clipping_rect</span><span class="special">);</span>
+
+        <span class="identifier">cvs</span><span class="special">.</span><span class="identifier">drawXXX</span><span class="special">(..);</span>
+    <span class="special">}</span>
+
+    <span class="comment">// this can return NULL.
+</span>    <span class="identifier">rect</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_clipping_rect</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">m_clipping_rect</span><span class="special">);</span> <span class="special">}</span>
+
+    <span class="keyword">private</span> <span class="special">:</span>
+
+    <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">rect</span><span class="special">&gt;</span> <span class="identifier">m_clipping_rect</span> <span class="special">;</span>
+
+<span class="special">};</span>
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.examples.bypassing_expensive_unnecessary_default_construction"></a><a href="examples.html#boost_optional.examples.bypassing_expensive_unnecessary_default_construction" title="Bypassing
+      expensive unnecessary default construction">Bypassing
+      expensive unnecessary default construction</a>
+</h3></div></div></div>
+<pre class="programlisting">
+<span class="keyword">class</span> <span class="identifier">ExpensiveCtor</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> <span class="special">;</span>
+<span class="keyword">class</span> <span class="identifier">Fred</span>
+<span class="special">{</span>
+    <span class="identifier">Fred</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">mLargeVector</span><span class="special">(</span><span class="number">10000</span><span class="special">)</span> <span class="special">{}</span>
+
+    <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">ExpensiveCtor</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">mLargeVector</span> <span class="special">;</span>
+<span class="special">}</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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="detailed_semantics.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/exception_safety_guarantees.html

@@ -0,0 +1,140 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Exception Safety
+    Guarantees</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="a_note_about_optional_bool_.html" title="A note about
+    optional&lt;bool&gt;">
+<link rel="next" href="type_requirements.html" title="Type requirements">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.exception_safety_guarantees"></a><a href="exception_safety_guarantees.html" title="Exception Safety
+    Guarantees">Exception Safety
+    Guarantees</a>
+</h2></div></div></div>
+<p>
+      Because of the current implementation (see <a href="../index.html#optional_implementation_notes">Implementation
+      Notes</a>), all of the assignment methods:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</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">T</span><span class="special">&gt;</span>
+        <span class="keyword">const</span><span class="special">&amp;</span>
+        <span class="special">)</span></code></li>
+<li><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="special">)</span></code></li>
+<li><code class="computeroutput"><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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</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;</span>
+        <span class="keyword">const</span><span class="special">&amp;</span>
+        <span class="special">)</span></code></li>
+<li><code class="computeroutput"><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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</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="special">)</span></code></li>
+<li><code class="computeroutput"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</span><span class="special">&gt;</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</span>
+        <span class="keyword">const</span><span class="special">&amp;</span>
+        <span class="special">)</span> </code></li>
+<li><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;:::</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;)</span></code></li>
+</ul></div>
+<p>
+      Can only <span class="emphasis"><em>guarantee</em></span> the <span class="underline">basic
+      exception safety</span>: The lvalue optional is left <span class="underline">uninitialized</span>
+      if an exception is thrown (any previous value is <span class="emphasis"><em>first</em></span>
+      destroyed using <code class="computeroutput"><span class="identifier">T</span><span class="special">::~</span><span class="identifier">T</span><span class="special">()</span></code>)
+    </p>
+<p>
+      On the other hand, the <span class="emphasis"><em>uninitializing</em></span> methods:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">none_t</span> <span class="special">)</span></code></li>
+<li><code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">reset</span><span class="special">()</span></code></li>
+</ul></div>
+<p>
+      Provide the no-throw guarantee (assuming a no-throw <code class="computeroutput"><span class="identifier">T</span><span class="special">::~</span><span class="identifier">T</span><span class="special">()</span></code>)
+    </p>
+<p>
+      However, since <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>
+      itself doesn't throw any exceptions, the only source for exceptions here are
+      <code class="computeroutput"><span class="identifier">T</span></code>'s constructor, so if you
+      know the exception guarantees for <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">T</span> <span class="special">(</span>
+      <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="special">)</span></code>, you
+      know that <code class="computeroutput"><span class="identifier">optional</span></code>'s assignment
+      and reset has the same guarantees.
+    </p>
+<pre class="programlisting">
+<span class="comment">//
+</span><span class="comment">// Case 1: Exception thrown during assignment.
+</span><span class="comment">//
+</span><span class="identifier">T</span> <span class="identifier">v0</span><span class="special">(</span><span class="number">123</span><span class="special">);</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">opt0</span><span class="special">(</span><span class="identifier">v0</span><span class="special">);</span>
+<span class="keyword">try</span>
+<span class="special">{</span>
+    <span class="identifier">T</span> <span class="identifier">v1</span><span class="special">(</span><span class="number">456</span><span class="special">);</span>
+    <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">opt1</span><span class="special">(</span><span class="identifier">v1</span><span class="special">);</span>
+    <span class="identifier">opt0</span> <span class="special">=</span> <span class="identifier">opt1</span> <span class="special">;</span>
+
+    <span class="comment">// If no exception was thrown, assignment succeeded.
+</span>    <span class="identifier">assert</span><span class="special">(</span> <span class="special">*</span><span class="identifier">opt0</span> <span class="special">==</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+<span class="keyword">catch</span><span class="special">(...)</span>
+<span class="special">{</span>
+    <span class="comment">// If any exception was thrown, 'opt0' is reset to uninitialized.
+</span>    <span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span><span class="identifier">opt0</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+
+<span class="comment">//
+</span><span class="comment">// Case 2: Exception thrown during reset(v)
+</span><span class="comment">//
+</span><span class="identifier">T</span> <span class="identifier">v0</span><span class="special">(</span><span class="number">123</span><span class="special">);</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">opt</span><span class="special">(</span><span class="identifier">v0</span><span class="special">);</span>
+<span class="keyword">try</span>
+<span class="special">{</span>
+    <span class="identifier">T</span> <span class="identifier">v1</span><span class="special">(</span><span class="number">456</span><span class="special">);</span>
+    <span class="identifier">opt</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
+
+    <span class="comment">// If no exception was thrown, reset succeeded.
+</span>    <span class="identifier">assert</span><span class="special">(</span> <span class="special">*</span><span class="identifier">opt</span> <span class="special">==</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+<span class="keyword">catch</span><span class="special">(...)</span>
+<span class="special">{</span>
+    <span class="comment">// If any exception was thrown, 'opt' is reset to uninitialized.
+</span>    <span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span><span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<a name="boost_optional.exception_safety_guarantees.swap"></a><h4>
+<a name="id2644335"></a>
+      <a href="exception_safety_guarantees.html#boost_optional.exception_safety_guarantees.swap">Swap</a>
+    </h4>
+<p>
+      <code class="computeroutput"><span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;,</span>
+      <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="special">)</span></code> has the same exception guarantee as <code class="computeroutput"><span class="identifier">swap</span><span class="special">(</span><span class="identifier">T</span><span class="special">&amp;,</span><span class="identifier">T</span><span class="special">&amp;)</span></code>
+      when both optionals are initialized. If only one of the optionals is initialized,
+      it gives the same <span class="emphasis"><em>basic</em></span> exception guarantee as <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">reset</span><span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="special">)</span></code> (since
+      <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">reset</span><span class="special">()</span></code> doesn't throw). If none of the optionals
+      is initialized, it has no-throw guarantee since it is a no-op.
+    </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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/implementation_notes.html

@@ -0,0 +1,52 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Implementation Notes</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="type_requirements.html" title="Type requirements">
+<link rel="next" href="dependencies_and_portability.html" title="Dependencies
+    and Portability">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="type_requirements.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dependencies_and_portability.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.implementation_notes"></a><a href="implementation_notes.html" title="Implementation Notes">Implementation Notes</a>
+</h2></div></div></div>
+<p>
+      <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> is
+      currently implemented using a custom aligned storage facility built from <code class="computeroutput"><span class="identifier">alignment_of</span></code> and <code class="computeroutput"><span class="identifier">type_with_alignment</span></code>
+      (both from Type Traits). It uses a separate boolean flag to indicate the initialization
+      state. Placement new with <code class="computeroutput"><span class="identifier">T</span></code>'s
+      copy constructor and <code class="computeroutput"><span class="identifier">T</span></code>'s destructor
+      are explicitly used to initialize,copy and destroy optional values. As a result,
+      <code class="computeroutput"><span class="identifier">T</span></code>'s default constructor is
+      effectively by-passed, but the exception guarantees are basic. It is planned
+      to replace the current implementation with another with stronger exception
+      safety, such as a future <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span></code>.
+    </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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="type_requirements.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dependencies_and_portability.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/in_place_factories.html

@@ -0,0 +1,200 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>In-Place Factories</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="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;">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.in_place_factories"></a><a href="in_place_factories.html" title="In-Place Factories">In-Place Factories</a>
+</h2></div></div></div>
+<p>
+      One of the typical problems with wrappers and containers is that their interfaces
+      usually provide an operation to initialize or assign the contained object as
+      a copy of some other object. This not only requires the underlying type to
+      be <a href="../../../../utility/CopyConstructible.html" target="_top">Copy Constructible</a>,
+      but also requires the existence of a fully constructed object, often temporary,
+      just to follow the copy from:
+    </p>
+<pre class="programlisting">
+<span class="keyword">struct</span> <span class="identifier">X</span>
+<span class="special">{</span>
+    <span class="identifier">X</span> <span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">:::</span><span class="identifier">string</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span> <span class="special">;</span>
+
+<span class="keyword">class</span> <span class="identifier">W</span>
+<span class="special">{</span>
+    <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
+
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
+<span class="special">}</span> <span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="comment">// Temporary object created.
+</span>    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+      A solution to this problem is to support direct construction of the contained
+      object right in the container's storage. In this scheme, the user only needs
+      to supply the arguments to the constructor to use in the wrapped object construction.
+    </p>
+<pre class="programlisting">
+<span class="keyword">class</span> <span class="identifier">W</span>
+<span class="special">{</span>
+    <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
+
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
+    <span class="identifier">W</span> <span class="special">(</span> <span class="keyword">int</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">a1</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">a0</span><span class="special">,</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
+<span class="special">}</span> <span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="comment">// Wrapped object constructed in-place
+</span>    <span class="comment">// No temporary created.
+</span>    <span class="identifier">W</span> <span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+      A limitation of this method is that it doesn't scale well to wrapped objects
+      with multiple constructors nor to generic code were the constructor overloads
+      are unknown.
+    </p>
+<p>
+      The solution presented in this library is the family of <span class="bold"><strong>InPlaceFactories</strong></span>
+      and <span class="bold"><strong>TypedInPlaceFactories</strong></span>. These factories
+      are a family of classes which encapsulate an increasing number of arbitrary
+      constructor parameters and supply a method to construct an object of a given
+      type using those parameters at an address specified by the user via placement
+      new.
+    </p>
+<p>
+      For example, one member of this family looks like:
+    </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory2</span>
+<span class="special">{</span>
+    <span class="identifier">A0</span> <span class="identifier">m_a0</span> <span class="special">;</span> <span class="identifier">A1</span> <span class="identifier">m_a1</span> <span class="special">;</span>
+
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">TypedInPlaceFactory2</span><span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a1</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">m_a0</span><span class="special">(</span><span class="identifier">a0</span><span class="special">),</span> <span class="identifier">m_a1</span><span class="special">(</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
+
+    <span class="keyword">void</span> <span class="identifier">construct</span> <span class="special">(</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="identifier">T</span><span class="special">(</span><span class="identifier">m_a0</span><span class="special">,</span><span class="identifier">m_a1</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
+ <span class="special">}</span> <span class="special">;</span>
+</pre>
+<p>
+      A wrapper class aware of this can use it as:
+    </p>
+<pre class="programlisting">
+<span class="keyword">class</span> <span class="identifier">W</span>
+<span class="special">{</span>
+    <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
+
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
+    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="identifier">construct</span><span class="special">(&amp;</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
+<span class="special">}</span> <span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="comment">// Wrapped object constructed in-place via a TypedInPlaceFactory.
+</span>    <span class="comment">// No temporary created.
+</span>    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span><span class="special">&lt;</span><span class="identifier">X</span><span class="special">,</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span><span class="identifier">rt</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">))</span> <span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+      The factories are divided in two groups:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<span class="underline">TypedInPlaceFactories</span>: those which
+        take the target type as a primary template parameter.
+      </li>
+<li>
+<span class="underline">InPlaceFactories</span>: those with a template
+        <code class="computeroutput"><span class="identifier">construct</span><span class="special">(</span><span class="keyword">void</span><span class="special">*)</span></code> member
+        function taking the target type.
+      </li>
+</ul></div>
+<p>
+      Within each group, all the family members differ only in the number of parameters
+      allowed.
+    </p>
+<p>
+      This library provides an overloaded set of helper template functions to construct
+      these factories without requiring unnecessary template parameters:
+    </p>
+<pre class="programlisting">
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">&gt;</span>
+<span class="identifier">InPlaceFactoryN</span> <span class="special">&lt;</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">&gt;</span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">&gt;</span>
+<span class="identifier">TypedInPlaceFactoryN</span> <span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">&gt;</span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
+</pre>
+<p>
+      In-place factories can be used generically by the wrapper and user as follows:
+    </p>
+<pre class="programlisting">
+<span class="keyword">class</span> <span class="identifier">W</span>
+<span class="special">{</span>
+    <span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
+
+    <span class="keyword">public</span><span class="special">:</span>
+
+    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
+
+    <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">W</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">X</span><span class="special">&gt;</span><span class="identifier">construct</span><span class="special">(&amp;</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
+
+<span class="special">}</span> <span class="special">;</span>
+
+<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
+<span class="special">{</span>
+    <span class="comment">// Wrapped object constructed in-place via a InPlaceFactory.
+</span>    <span class="comment">// No temporary created.
+</span>    <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">in_place</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+      The factories are implemented in the headers: <a href="../../../../../boost/utility/in_place_factory.hpp" target="_top">in_place_factory.hpp</a>
+      and <a href="../../../../../boost/utility/typed_in_place_factory.hpp" target="_top">typed_in_place_factory.hpp</a>
+    </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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/optional_references.html

@@ -0,0 +1,82 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Optional references</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="examples.html" title="Examples">
+<link rel="next" href="rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding
+    semantics for assignment of optional references">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="examples.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.optional_references"></a><a href="optional_references.html" title="Optional references">Optional references</a>
+</h2></div></div></div>
+<p>
+      This library allows the template parameter <code class="computeroutput"><span class="identifier">T</span></code>
+      to be of reference type: <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>, and to some extent, <code class="computeroutput"><span class="identifier">T</span>
+      <span class="keyword">const</span><span class="special">&amp;</span></code>.
+    </p>
+<p>
+      However, since references are not real objects some restrictions apply and
+      some operations are not available in this case:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+        Converting constructors
+      </li>
+<li>
+        Converting assignment
+      </li>
+<li>
+        InPlace construction
+      </li>
+<li>
+        InPlace assignment
+      </li>
+<li>
+        Value-access via pointer
+      </li>
+</ul></div>
+<p>
+      Also, even though <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+      treats it wrapped pseudo-object much as a real value, a true real reference
+      is stored so aliasing will ocurr:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+        Copies of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+        will copy the references but all these references will nonetheless reefer
+        to the same object.
+      </li>
+<li>
+        Value-access will actually provide access to the referenced object rather
+        than the reference itself.
+      </li>
+</ul></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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="examples.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/rebinding_semantics_for_assignment_of_optional_references.html

@@ -0,0 +1,151 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Rebinding
+    semantics for assignment of optional references</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="optional_references.html" title="Optional references">
+<link rel="next" href="in_place_factories.html" title="In-Place Factories">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.rebinding_semantics_for_assignment_of_optional_references"></a><a href="rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding
+    semantics for assignment of optional references">Rebinding
+    semantics for assignment of optional references</a>
+</h2></div></div></div>
+<p>
+      If you assign to an <span class="emphasis"><em>uninitialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+      the effect is to bind (for the first time) to the object. Clearly, there is
+      no other choice.
+    </p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">rx</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">;</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">ora</span> <span class="special">;</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">orb</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">;</span>
+<span class="identifier">ora</span> <span class="special">=</span> <span class="identifier">orb</span> <span class="special">;</span> <span class="comment">// now 'ora' is bound to 'x' through 'rx'
+</span><span class="special">*</span><span class="identifier">ora</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span> <span class="comment">// Changes value of 'x' through 'ora'
+</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">x</span><span class="special">==</span><span class="number">2</span><span class="special">);</span> 
+</pre>
+<p>
+      If you assign to a bare C++ reference, the assignment is forwarded to the referenced
+      object; it's value changes but the reference is never rebound.
+    </p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">;</span>
+<span class="keyword">int</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">rb</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
+<span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">rb</span> <span class="special">;</span> <span class="comment">// Changes the value of 'a' to 'b'
+</span><span class="identifier">assert</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="identifier">b</span> <span class="special">=</span> <span class="number">3</span> <span class="special">;</span>
+<span class="identifier">assert</span><span class="special">(</span><span class="identifier">ra</span><span class="special">!=</span><span class="identifier">b</span><span class="special">);</span> <span class="comment">// 'ra' is not rebound to 'b'
+</span></pre>
+<p>
+      Now, if you assign to an <span class="emphasis"><em>initialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>,
+      the effect is to <span class="bold"><strong>rebind</strong></span> to the new object
+      instead of assigning the referee. This is unlike bare C++ references.
+    </p>
+<pre class="programlisting">
+<span class="keyword">int</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
+<span class="keyword">int</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">rb</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">ora</span><span class="special">(</span><span class="identifier">ra</span><span class="special">)</span> <span class="special">;</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">orb</span><span class="special">(</span><span class="identifier">rb</span><span class="special">)</span> <span class="special">;</span>
+<span class="identifier">ora</span> <span class="special">=</span> <span class="identifier">orb</span> <span class="special">;</span> <span class="comment">// 'ora' is rebound to 'b'
+</span><span class="special">*</span><span class="identifier">ora</span> <span class="special">=</span> <span class="number">3</span> <span class="special">;</span> <span class="comment">// Changes value of 'b' (not 'a')
+</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">a</span><span class="special">==</span><span class="number">1</span><span class="special">);</span> 
+<span class="identifier">assert</span><span class="special">(</span><span class="identifier">b</span><span class="special">==</span><span class="number">3</span><span class="special">);</span> 
+</pre>
+<a name="boost_optional.rebinding_semantics_for_assignment_of_optional_references.rationale"></a><h4>
+<a name="id2639932"></a>
+      <a href="rebinding_semantics_for_assignment_of_optional_references.html#boost_optional.rebinding_semantics_for_assignment_of_optional_references.rationale">Rationale</a>
+    </h4>
+<p>
+      Rebinding semantics for the assignment of <span class="emphasis"><em>initialized </em></span>
+      <code class="computeroutput"><span class="identifier">optional</span></code> references has been
+      chosen to provide <span class="bold"><strong>consistency among initialization states</strong></span>
+      even at the expense of lack of consistency with the semantics of bare C++ references.
+      It is true that <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;</span></code> strives
+      to behave as much as possible as <code class="computeroutput"><span class="identifier">U</span></code>
+      does whenever it is initialized; but in the case when <code class="computeroutput"><span class="identifier">U</span></code>
+      is <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>,
+      doing so would result in inconsistent behavior w.r.t to the lvalue initialization
+      state.
+    </p>
+<p>
+      Imagine <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+      forwarding assignment to the referenced object (thus changing the referenced
+      object value but not rebinding), and consider the following code:
+    </p>
+<pre class="programlisting">
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">get</span><span class="special">();</span>
+<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
+<span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">rx</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">;</span>
+<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">rx</span><span class="special">);</span>
+<span class="identifier">a</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
+</pre>
+<p>
+      What does the assignment do?
+    </p>
+<p>
+      If <code class="computeroutput"><span class="identifier">a</span></code> is <span class="emphasis"><em>uninitialized</em></span>,
+      the answer is clear: it binds to <code class="computeroutput"><span class="identifier">x</span></code>
+      (we now have another reference to <code class="computeroutput"><span class="identifier">x</span></code>).
+      But what if <code class="computeroutput"><span class="identifier">a</span></code> is already <span class="emphasis"><em>initialized</em></span>?
+      it would change the value of the referenced object (whatever that is); which
+      is inconsistent with the other possible case.
+    </p>
+<p>
+      If <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+      would assign just like <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>
+      does, you would never be able to use Optional's assignment without explicitly
+      handling the previous initialization state unless your code is capable of functioning
+      whether after the assignment, <code class="computeroutput"><span class="identifier">a</span></code>
+      aliases the same object as <code class="computeroutput"><span class="identifier">b</span></code>
+      or not.
+    </p>
+<p>
+      That is, you would have to discriminate in order to be consistency.
+    </p>
+<p>
+      If in your code rebinding to another object is not an option, then is very
+      likely that binding for the fist time isn't either. In such case, assignment
+      to an <span class="emphasis"><em>uninitialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&amp;&gt;</span></code>
+      shall be prohibited. It is quite possible that in such scenario the precondition
+      that the lvalue must be already initialized exist. If it doesn't, then binding
+      for the first time is OK while rebinding is not which is IMO very unlikely.
+      In such scenario, you can assign the value itself directly, as in:
+    </p>
+<pre class="programlisting">
+<span class="identifier">assert</span><span class="special">(!!</span><span class="identifier">opt</span><span class="special">);</span>
+<span class="special">*</span><span class="identifier">opt</span><span class="special">=</span><span class="identifier">value</span><span class="special">;</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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/synopsis.html

@@ -0,0 +1,147 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Synopsis</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="development.html" title="Development">
+<link rel="next" href="detailed_semantics.html" title="Detailed Semantics">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="development.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="detailed_semantics.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.synopsis"></a><a href="synopsis.html" title="Synopsis">Synopsis</a>
+</h2></div></div></div>
+<pre class="programlisting">
+<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">optional</span>
+<span class="special">{</span>
+    <span class="keyword">public</span> <span class="special">:</span>
+
+    <span class="comment">// (If T is of reference type, the parameters and results by reference are by value)
+</span>
+    <span class="identifier">optional</span> <span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">none_t</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_none_t"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="comment">// [new in 1.34]
+</span>    <span class="identifier">optional</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">condition</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_bool_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a> 
+
+    <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">optional</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_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="identifier">U</span><span class="special">&gt;</span> <span class="keyword">explicit</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">U</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_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="identifier">InPlaceFactory</span><span class="special">&gt;</span> <span class="keyword">explicit</span> <span class="identifier">optional</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 href="detailed_semantics.html#reference_optional_constructor_factory"><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">TypedInPlaceFactory</span><span class="special">&gt;</span> <span class="keyword">explicit</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</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 href="detailed_semantics.html#reference_optional_constructor_factory"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <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">none_t</span> <span class="special">)</span> <span class="special">;</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">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_equal_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <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="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_equal_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="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;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_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="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> 
+
+    <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</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">TypedInPlaceFactory</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span> 
+
+    <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+    <span class="identifier">T</span><span class="special">&amp;</span>       <span class="identifier">get</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="comment">// [new in 1.34]
+</span>    <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get_value_or</span><span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="keyword">default</span> <span class="special">)</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_value_or_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a> 
+
+    <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="keyword">operator</span> <span class="special">-&gt;()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_arrow"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+    <span class="identifier">T</span><span class="special">*</span>       <span class="keyword">operator</span> <span class="special">-&gt;()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_arrow"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="keyword">operator</span> <span class="special">*()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+    <span class="identifier">T</span><span class="special">&amp;</span>       <span class="keyword">operator</span> <span class="special">*()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_ptr</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+    <span class="identifier">T</span><span class="special">*</span>       <span class="identifier">get_ptr</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="keyword">operator</span> <span class="identifier">unspecified</span><span class="special">-</span><span class="keyword">bool</span><span class="special">-</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_bool"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_not"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="comment">// deprecated methods
+</span>
+    <span class="comment">// (deprecated)
+</span>    <span class="keyword">void</span> <span class="identifier">reset</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_reset"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="comment">// (deprecated)
+</span>    <span class="keyword">void</span> <span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_reset_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+    <span class="comment">// (deprecated)
+</span>    <span class="keyword">bool</span> <span class="identifier">is_initialized</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_is_initialized"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+<span class="special">};</span>
+
+<span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</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">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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_equal_optional_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="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</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">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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_not_equal_optional_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="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&lt;</span>  <span class="special">(</span> <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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_less_optional_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="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&gt;</span>  <span class="special">(</span> <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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_greater_optional_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="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&lt;=</span> <span class="special">(</span> <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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_less_or_equal_optional_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="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">&gt;=</span> <span class="special">(</span> <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="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">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_greater_or_equal_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+<span class="comment">// [new in 1.34]
+</span><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_optional</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_make_optional_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+<span class="comment">// [new in 1.34]
+</span><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="identifier">make_optional</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">condition</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_make_optional_bool_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+<span class="comment">// [new in 1.34]
+</span><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get_optional_value_or</span> <span class="special">(</span> <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">opt</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="keyword">default</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_value_or_value"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get</span> <span class="special">(</span> <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">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">&amp;</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="special">&amp;</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get</span> <span class="special">(</span> <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">*</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;*</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_pointer</span> <span class="special">(</span> <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">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">get_pointer</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span> <span class="special">&amp;</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><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">T</span><span class="special">&gt;</span> <span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_swap_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
+
+<span class="special">}</span> <span class="comment">// namespace boost
+</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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="development.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="detailed_semantics.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/type_requirements.html

@@ -0,0 +1,50 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Type requirements</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="prev" href="exception_safety_guarantees.html" title="Exception Safety
+    Guarantees">
+<link rel="next" href="implementation_notes.html" title="Implementation Notes">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center"><a href="../../../index.htm">Home</a></td>
+<td align="center"><a href="../libraries.html">Libraries</a></td>
+<td align="center"><a href="../../../people/people.htm">People</a></td>
+<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="exception_safety_guarantees.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="implementation_notes.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_optional.type_requirements"></a><a href="type_requirements.html" title="Type requirements">Type requirements</a>
+</h2></div></div></div>
+<p>
+      In general, <code class="computeroutput"><span class="identifier">T</span></code> must be <a href="../../../../utility/CopyConstructible.html" target="_top">Copy Constructible</a> and
+      have a no-throw destructor. The copy-constructible requirement is not needed
+      if <span class="bold"><strong>InPlaceFactories</strong></span> are used.
+    </p>
+<p>
+      <code class="computeroutput"><span class="identifier">T</span></code> <span class="underline">is
+      not</span> required to be <a href="http://www.sgi.com/tech/stl/DefaultConstructible.html" target="_top">Default
+      Constructible</a>.
+    </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"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="exception_safety_guarantees.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="implementation_notes.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boostbook.css

@@ -0,0 +1,582 @@
+/*=============================================================================
+    Copyright (c) 2004 Joel de Guzman
+    http://spirit.sourceforge.net/
+
+    Use, modification and distribution is subject to the Boost Software
+    License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+=============================================================================*/
+
+/*=============================================================================
+    Body defaults
+=============================================================================*/
+
+    body 
+    {
+        margin: 1em;
+        font-family: sans-serif;
+    }
+
+/*=============================================================================
+    Paragraphs
+=============================================================================*/
+
+    p 
+    {
+        text-align: left;
+        font-size: 10pt; 
+        line-height: 1.15;
+    }
+
+/*=============================================================================
+    Program listings
+=============================================================================*/
+
+    /* Code on paragraphs */
+    p tt.computeroutput
+    {
+        font-size: 10pt;
+    }
+
+    pre.synopsis
+    {
+        font-size: 10pt;
+        margin: 1pc 4% 0pc 4%;
+        padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+    }
+
+    .programlisting, 
+    .screen
+    {
+        font-size: 10pt;
+        display: block;
+        margin: 1pc 4% 0pc 4%;
+        padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+    }
+
+    /* Program listings in tables don't get borders */
+    td .programlisting,
+    td .screen
+    {
+        margin: 0pc 0pc 0pc 0pc;
+        padding:  0pc 0pc 0pc 0pc;
+    }
+
+/*=============================================================================
+    Headings
+=============================================================================*/
+
+    h1, h2, h3, h4, h5, h6 
+    { 
+        text-align: left;
+        margin: 1em 0em 0.5em 0em;
+        font-weight: bold;
+    }
+
+    h1 { font: 140% }
+    h2 { font: bold 140% }
+    h3 { font: bold 130% }
+    h4 { font: bold 120% }
+    h5 { font: italic 110% }
+    h6 { font: italic 100% }
+
+    /* Top page titles */
+    title, 
+    h1.title, 
+    h2.title
+    h3.title, 
+    h4.title, 
+    h5.title, 
+    h6.title, 
+    .refentrytitle
+    {
+        font-weight: bold;
+        margin-bottom: 1pc;
+    }
+
+    h1.title { font-size: 140% }
+    h2.title { font-size: 140% }
+    h3.title { font-size: 130% }
+    h4.title { font-size: 120% }
+    h5.title { font-size: 110% }
+    h6.title { font-size: 100% }
+
+    .section h1 
+    {
+        margin: 0em 0em 0.5em 0em;
+        font-size: 140%;
+    }
+
+    .section h2 { font-size: 140% }
+    .section h3 { font-size: 130% }
+    .section h4 { font-size: 120% }
+    .section h5 { font-size: 110% }
+    .section h6 { font-size: 100% }
+
+    /* Code on titles */
+    h1 tt.computeroutput { font-size: 140% }
+    h2 tt.computeroutput { font-size: 140% }
+    h3 tt.computeroutput { font-size: 130% }
+    h4 tt.computeroutput { font-size: 120% }
+    h5 tt.computeroutput { font-size: 110% }
+    h6 tt.computeroutput { font-size: 100% }
+
+/*=============================================================================
+    Author
+=============================================================================*/
+
+    h3.author 
+    { 
+        font-size: 100% 
+    }
+
+/*=============================================================================
+    Lists
+=============================================================================*/
+
+    li
+    {
+        font-size: 10pt;
+        line-height: 1.3;
+    }
+
+    /* Unordered lists */
+    ul 
+    {
+        text-align: left;
+    }
+
+    /* Ordered lists */
+    ol 
+    {
+        text-align: left;
+    }
+
+/*=============================================================================
+    Links
+=============================================================================*/
+
+    a
+    {
+        text-decoration: none; /* no underline */
+    }
+
+    a:hover
+    {
+        text-decoration: underline;
+    }
+
+/*=============================================================================
+    Spirit style navigation
+=============================================================================*/
+
+    .spirit-nav
+    {
+        text-align: right;
+    }
+
+    .spirit-nav a
+    {
+        color: white;
+        padding-left: 0.5em;
+    }
+
+    .spirit-nav img
+    {
+        border-width: 0px;
+    }
+
+/*=============================================================================
+    Table of contents
+=============================================================================*/
+
+    .toc
+    {
+       margin: 1pc 4% 0pc 4%;
+       padding: 0.1pc 1pc 0.1pc 1pc;
+       font-size: 10pt;
+       line-height: 1.15;
+    }
+
+    .toc-main
+    {
+       text-align: center;
+       margin: 3pc 16% 3pc 16%;
+       padding: 3pc 1pc 3pc 1pc;
+       line-height: 0.1;
+    }
+
+    .boost-toc
+    {
+       float: right;
+       padding: 0.5pc;
+    }
+
+/*=============================================================================
+    Tables
+=============================================================================*/
+
+    .table-title, 
+    div.table p.title
+    {
+        margin-left: 4%;
+        padding-right: 0.5em; 
+        padding-left: 0.5em;
+    }
+
+    .informaltable table, 
+    .table table
+    {
+        width: 92%;
+        margin-left: 4%;
+        margin-right: 4%;
+    }
+
+    div.informaltable table, 
+    div.table table
+    {
+        padding: 4px;
+    }
+
+    /* Table Cells */
+    div.informaltable table tr td, 
+    div.table table tr td
+    {
+        padding: 0.5em;
+        text-align: left;
+    }
+
+    div.informaltable table tr th, 
+    div.table table tr th
+    {
+        padding: 0.5em 0.5em 0.5em 0.5em;
+        border: 1pt solid white;
+        font-size: 120%;
+    }
+
+/*=============================================================================
+    Blurbs
+=============================================================================*/
+
+    div.note,
+    div.tip,
+    div.important,
+    div.caution,
+    div.warning,
+    div.sidebar
+    {
+        font-size: 10pt;
+        line-height: 1.2;
+        display: block;
+        margin: 1pc 4% 0pc 4%;
+        padding: 0.5pc 0.5pc 0.5pc 0.5pc;
+    }
+
+    div.sidebar img
+    {
+        padding: 1pt;
+    }
+
+
+
+/*=============================================================================
+    Callouts
+=============================================================================*/
+    .line_callout_bug img
+    {
+        float: left;
+        position:relative;
+        left: 4px;
+        top: -12px;
+        clear: left;
+        margin-left:-22px;
+    }
+
+    .callout_bug img
+    {
+    }
+
+
+
+/*=============================================================================
+    Variable Lists
+=============================================================================*/
+
+    /* Make the terms in definition lists bold */
+    div.variablelist dl dt,
+    span.term
+    {
+        font-weight: bold;
+        font-size: 10pt;
+    }
+
+    div.variablelist table tbody tr td
+    {
+        text-align: left;
+        vertical-align: top;
+        padding: 0em 2em 0em 0em;
+        font-size: 10pt;
+        margin: 0em 0em 0.5em 0em;
+        line-height: 1;
+    }
+
+    /* Make the terms in definition lists bold */
+    div.variablelist dl dt
+    {
+        margin-bottom: 0.2em;
+    }
+
+    div.variablelist dl dd
+    {
+        margin: 0em 0em 0.5em 2em;
+        font-size: 10pt;
+    }
+
+    div.variablelist table tbody tr td p
+    div.variablelist dl dd p
+    {
+        margin: 0em 0em 0.5em 0em;
+        line-height: 1;
+    }
+
+/*=============================================================================
+    Misc
+=============================================================================*/
+
+    /* Title of books and articles in bibliographies */
+    span.title
+    {
+        font-style: italic;
+    }
+
+    span.underline
+    {
+        text-decoration: underline;
+    }
+
+    span.strikethrough
+    {
+        text-decoration: line-through;
+    }
+
+    /* Copyright, Legal Notice */
+    div div.legalnotice p
+    {
+        text-align: left
+    }
+
+/*=============================================================================
+    Colors
+=============================================================================*/
+
+    @media screen
+    {
+        /* Links */
+        a
+        {
+            color: #0C7445;
+        }
+
+        a:visited
+        {
+            color: #663974;
+        }
+
+        h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
+        h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover,
+        h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited
+        {
+            text-decoration: none; /* no underline */
+            color: #000000;
+        }
+
+        /* Syntax Highlighting */
+        .keyword        { color: #0000AA; }
+        .identifier     { color: #000000; }
+        .special        { color: #707070; }
+        .preprocessor   { color: #402080; }
+        .char           { color: teal; }
+        .comment        { color: #800000; }
+        .string         { color: teal; }
+        .number         { color: teal; }
+        .white_bkd      { background-color: #E8FBE9; }
+        .dk_grey_bkd    { background-color: #A0DAAC; }
+
+        /* Copyright, Legal Notice */
+        .copyright
+        { 
+            color: #666666; 
+            font-size: small; 
+        }
+
+        div div.legalnotice p
+        {
+            color: #666666;
+        }
+
+        /* Program listing */
+        pre.synopsis
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        .programlisting, 
+        .screen
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        td .programlisting,
+        td .screen
+        {
+            border: 0px solid #DCDCDC;
+        }
+
+        /* Blurbs */
+        div.note,
+        div.tip,
+        div.important,
+        div.caution,
+        div.warning,
+        div.sidebar
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        /* Table of contents */
+        .toc
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        /* Table of contents */
+        .toc-main
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+
+        /* Tables */
+        div.informaltable table tr td, 
+        div.table table tr td
+        {
+            border: 1px solid #DCDCDC;
+            background-color: #FAFFFB;
+        }
+
+        div.informaltable table tr th, 
+        div.table table tr th
+        {
+            background-color: #E3F9E4;
+            border: 1px solid #DCDCDC;
+        }
+
+        /* Misc */
+        span.highlight
+        {
+            color: #00A000;
+        }
+    }
+
+    @media print
+    {
+        /* Links */
+        a
+        {
+            color: black;
+        }
+
+        a:visited
+        {
+            color: black;
+        }
+
+        .spirit-nav
+        {
+            display: none;
+        }
+
+        /* Program listing */
+        pre.synopsis
+        {
+            border: 1px solid gray;
+            background-color: #FAFFFB;
+        }
+
+        .programlisting, 
+        .screen
+        {
+            border: 1px solid gray;
+            background-color: #FAFFFB;
+        }
+
+        td .programlisting,
+        td .screen
+        {
+            border: 0px solid #DCDCDC;
+        }
+
+        /* Table of contents */
+        .toc
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        /* Table of contents */
+        .toc-main
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            background-color: #FAFFFB;
+        }
+
+        .informaltable table, 
+        .table table
+        {
+            border: 1px solid #DCDCDC;
+            border-bottom: 3px solid #9D9D9D;
+            border-right: 3px solid #9D9D9D;
+            border-collapse: collapse;
+            background-color: #FAFFFB;
+        }
+
+        /* Tables */
+        div.informaltable table tr td, 
+        div.table table tr td
+        {
+            border: 1px solid #DCDCDC;
+            background-color: #FAFFFB;
+        }
+
+        div.informaltable table tr th, 
+        div.table table tr th
+        {
+            border: 1px solid #DCDCDC;
+            background-color: #FAFFFB;
+        }
+
+        /* Misc */
+        span.highlight
+        {
+            font-weight: bold;
+        }
+    }

doc/html/index.html

@@ -0,0 +1,168 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chapter<EFBFBD>1.<2E>Boost.Optional</title>
+<link rel="stylesheet" href="boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
+<link rel="start" href="index.html" title="Chapter<65>1.<2E>Boost.Optional">
+<link rel="next" href="boost_optional/development.html" title="Development">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
+<td align="center"><a href="../../index.htm">Home</a></td>
+<td align="center"><a href="libraries.html">Libraries</a></td>
+<td align="center"><a href="../../people/people.htm">People</a></td>
+<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
+<td align="center"><a href="../../more/index.htm">More</a></td>
+</table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="boost_optional/development.html"><img src="images/next.png" alt="Next"></a></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div>
+<div><h2 class="title">
+<a name="optional"></a>Chapter<EFBFBD>1.<2E>Boost.Optional</h2></div>
+<div><div class="author"><h3 class="author">
+<span class="firstname">Fernando Luis</span> <span class="surname">Cacciola Carballal</span>
+</h3></div></div>
+<div><p class="copyright">Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</p></div>
+<div><div class="legalnotice">
+<a name="id2604804"></a><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></div>
+</div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="index.html#optional.motivation">Motivation</a></span></dt>
+<dt><span class="section"><a href="boost_optional/development.html">Development</a></span></dt>
+<dt><span class="section"><a href="boost_optional/synopsis.html">Synopsis</a></span></dt>
+<dt><span class="section"><a href="boost_optional/detailed_semantics.html">Detailed Semantics</a></span></dt>
+<dt><span class="section"><a href="boost_optional/examples.html">Examples</a></span></dt>
+<dt><span class="section"><a href="boost_optional/optional_references.html">Optional references</a></span></dt>
+<dt><span class="section"><a href="boost_optional/rebinding_semantics_for_assignment_of_optional_references.html">Rebinding
+    semantics for assignment of optional references</a></span></dt>
+<dt><span class="section"><a href="boost_optional/in_place_factories.html">In-Place Factories</a></span></dt>
+<dt><span class="section"><a href="boost_optional/a_note_about_optional_bool_.html">A note about
+    optional&lt;bool&gt;</a></span></dt>
+<dt><span class="section"><a href="boost_optional/exception_safety_guarantees.html">Exception Safety
+    Guarantees</a></span></dt>
+<dt><span class="section"><a href="boost_optional/type_requirements.html">Type requirements</a></span></dt>
+<dt><span class="section"><a href="boost_optional/implementation_notes.html">Implementation Notes</a></span></dt>
+<dt><span class="section"><a href="boost_optional/dependencies_and_portability.html">Dependencies
+    and Portability</a></span></dt>
+<dt><span class="section"><a href="boost_optional/acknowledgments.html">Acknowledgments</a></span></dt>
+</dl>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="optional.motivation"></a><a href="index.html#optional.motivation" title="Motivation">Motivation</a>
+</h2></div></div></div>
+<p>
+      Consider these functions which should return a value but which might not have
+      a value to return:
+    </p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+        (A) <code class="computeroutput"><span class="keyword">double</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">n</span>
+        <span class="special">);</span></code>
+</li>
+<li>
+        (B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
+</li>
+<li>
+        (C) <code class="computeroutput"><span class="identifier">point</span> <span class="identifier">polygon</span><span class="special">::</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span></code>
+</li>
+</ul></div>
+<p>
+      There are different approaches to the issue of not having a value to return.
+    </p>
+<p>
+      A typical approach is to consider the existence of a valid return value as
+      a postcondition, so that if the function cannot compute the value to return,
+      it has either undefined behavior (and can use assert in a debug build) or uses
+      a runtime check and throws an exception if the postcondition is violated. This
+      is a reasonable choice for example, for function (A), because the lack of a
+      proper return value is directly related to an invalid parameter (out of domain
+      argument), so it is appropriate to require the callee to supply only parameters
+      in a valid domain for execution to continue normally.
+    </p>
+<p>
+      However, function (B), because of its asynchronous nature, does not fail just
+      because it can't find a value to return; so it is incorrect to consider such
+      a situation an error and assert or throw an exception. This function must return,
+      and somehow, must tell the callee that it is not returning a meaningful value.
+    </p>
+<p>
+      A similar situation occurs with function (C): it is conceptually an error to
+      ask a <span class="emphasis"><em>null-area</em></span> polygon to return a point inside itself,
+      but in many applications, it is just impractical for performance reasons to
+      treat this as an error (because detecting that the polygon has no area might
+      be too expensive to be required to be tested previously), and either an arbitrary
+      point (typically at infinity) is returned, or some efficient way to tell the
+      callee that there is no such point is used.
+    </p>
+<p>
+      There are various mechanisms to let functions communicate that the returned
+      value is not valid. One such mechanism, which is quite common since it has
+      zero or negligible overhead, is to use a special value which is reserved to
+      communicate this. Classical examples of such special values are <code class="computeroutput"><span class="identifier">EOF</span></code>, <code class="computeroutput"><span class="identifier">string</span><span class="special">::</span><span class="identifier">npos</span></code>, points
+      at infinity, etc...
+    </p>
+<p>
+      When those values exist, i.e. the return type can hold all meaningful values
+      <span class="emphasis"><em>plus</em></span> the <span class="emphasis"><em>signal</em></span> value, this mechanism
+      is quite appropriate and well known. Unfortunately, there are cases when such
+      values do not exist. In these cases, the usual alternative is either to use
+      a wider type, such as <code class="computeroutput"><span class="keyword">int</span></code> in place
+      of <code class="computeroutput"><span class="keyword">char</span></code>; or a compound type, such
+      as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;</span></code>.
+    </p>
+<p>
+      Returning a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;</span></code>, thus attaching a boolean flag to the result
+      which indicates if the result is meaningful, has the advantage that can be
+      turned into a consistent idiom since the first element of the pair can be whatever
+      the function would conceptually return. For example, the last two functions
+      could have the following interface:
+    </p>
+<pre class="programlisting">
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">get_async_input</span><span class="special">();</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">polygon</span><span class="special">::</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span>
+</pre>
+<p>
+      These functions use a consistent interface for dealing with possibly inexistent
+      results:
+    </p>
+<pre class="programlisting">
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">poly</span><span class="special">.</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span>
+<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">second</span> <span class="special">)</span>
+    <span class="identifier">flood_fill</span><span class="special">(</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">first</span><span class="special">);</span>
+</pre>
+<p>
+      However, not only is this quite a burden syntactically, it is also error prone
+      since the user can easily use the function result (first element of the pair)
+      without ever checking if it has a valid value.
+    </p>
+<p>
+      Clearly, we need a better idiom.
+    </p>
+</div>
+<p>
+  </p>
+<a name="optional_refassign"></a><p>
+  </p>
+<a name="optional_in_place_factories"></a><p>
+  </p>
+<a name="optional_implementation_notes"></a><p>
+  </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"><small><p>Last revised: May 29, 2007 at 06:31:03 GMT</p></small></td>
+<td align="right"><small></small></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="boost_optional/development.html"><img src="images/next.png" alt="Next"></a></div>
+</body>
+</html>

doc/implementation_notes.qbk

@@ -0,0 +1,28 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+
+[#optional_implementation_notes]
+
+[section Implementation Notes]
+
+`optional<T>` is currently implemented using a custom aligned storage facility
+built from `alignment_of` and `type_with_alignment` (both from Type Traits). It
+uses a separate boolean flag to indicate the initialization state.
+Placement new with `T`'s copy constructor and `T`'s destructor are explicitly used
+to initialize,copy and destroy optional values.
+As a result, `T`'s default constructor is effectively by-passed, but the exception
+guarantees are basic.
+It is planned to replace the current implementation with another with stronger
+exception safety, such as a future `boost::variant`.
+
+[endsect]
+ 

doc/optional.html

@@ -3,7 +3,6 @@
 <HTML>
 
 <HEAD>
-<meta http-equiv="Content-Language" content="en-us">
 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
 <meta name="ProgId" content="FrontPage.Editor.Document">
 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
@@ -127,7 +126,7 @@ undefined behavior</i>
   which in our case is either <code>T</code> or <code>nil_t</code>.<br>
   Using the <a href="../../../doc/html/variant.html">Boost.Variant</a> library, this model can be implemented
   in terms of <code>boost::variant&lt;T,nil_t&gt;</code>.<br>
-  There is precedence for a discriminated union as a model for an optional value: the
+  There is precedent for a discriminated union as a model for an optional value: the
   <a href="http://www.haskell.org/"><u>Haskell</u></a> <b>Maybe</b> built-in type constructor. 
 Thus, a discriminated union <code>T+nil_t</code> serves as a conceptual foundation.</p>
 <p>A <code>variant&lt;T,nil_t&gt;</code> follows naturally from the traditional idiom of extending
@@ -324,6 +323,8 @@ class optional
 
     optional ( T const&amp; v ) ;
 
+    optional ( bool condition, T const&amp; v ) ;  <u><i>[new in 1.34]</u></i>
+    
     optional ( optional const&amp; rhs ) ;
 
     template&lt;class U&gt; explicit optional ( optional&lt;U&gt; const&amp; rhs ) ;
@@ -347,6 +348,8 @@ class optional
     T const& get() const ;
     T&       get() ;
 
+    T<span lang="es"> const&amp;</span> get_value_or( T const&amp; default ) const ;  <u><i>[new in 1.34]</u></i>
+    
     T const* operator -&gt;() const ;
     T*       operator -&gt;() ;
 
@@ -380,6 +383,12 @@ template&lt;class T&gt; inline bool operator <= ( optional&lt;T&gt; const& x, op
 
 template&lt;class T&gt; inline bool operator >= ( optional&lt;T&gt; const& x, optional&lt;T&gt; const& y ) ;
 
+template&lt;class T&gt; inline optional&lt;T&gt; make_optional ( T const& v ) ;  <u><i>[new in 1.34]</u></i>
+
+template&lt;class T&gt; inline optional&lt;T&gt; make_optional ( bool condition, T const& v ) ;  <u><i>[new in 1.34]</u></i>
+
+template&lt;class T&gt; inline T <span lang="es">const&amp; </span>get_<span lang="es">optional_</span>value_or ( optional&lt;T&gt; const& opt, T const& default ) ;  <u><i>[new in 1.34]</u></i>
+
 template&lt;class T&gt; inline T const& get ( optional&lt;T&gt; const& opt ) ;
 
 template&lt;class T&gt; inline T& get ( optional&lt;T&gt; & opt ) ;
@@ -436,7 +445,7 @@ assert ( !def ) ;</pre>
 
 <pre>optional&lt;T&gt;::optional( none_t );</pre>
 <blockquote>
-<p><b>Effect:</b> Constructs an <b>optional </b>uninitialized.</p>
+<p><b>Effect:</b> Constructs an <b>optional</b> uninitialized.</p>
 <p><b>Postconditions:</b> <b>*this</b> is <u>uninitialized</u>.</p>
 <p><b>Throws:</b> Nothing.</p>
 <p><b>Notes:</b></p>
@@ -459,7 +468,6 @@ assert ( !n ) ;</pre>
 <pre>optional&lt;T <i>(not a ref)</i>&gt;::optional( T const&amp; v )</pre>
 <blockquote>
 <p><b>Effect:</b> Directly-Constructs an <b>optional</b>.</p>
-<!-- TemplateName: general/sy_footer_inc.isml -->
 <p><b>Postconditions:</b> <b>*this</b> is <u>initialized</u> and its value is a <i>copy</i> of 'v'.</p>
 <p><b>Throws:</b> Whatever T::T( T const&amp; ) throws.</p>
 <p><b>Notes: </b> T::T( T const&amp; ) is called.</p>
@@ -495,6 +503,23 @@ assert (*opt == v); </pre>
 
 <HR>
 
+<pre>optional&lt;T <i>(not a ref)</i>&gt;::optional( bool condition, T const&amp; v ) ;
+optional&lt;T&amp;&gt;    <span lang="es">       </span>::optional( bool condition, T&amp;     <span lang="es"> </span> v ) ;
+</pre>
+
+<blockquote>
+<p>If <i>condition</i> is <code>true</code>, same as:</p>
+<pre>optional&lt;T <i>(not a ref)</i>&gt;::optional( T const&amp; v )
+optional&lt;T&amp;&gt;<span lang="es">           </span>::optional( T&amp;<span lang="es">      </span> v )
+</pre>
+<p>otherwise, same as:</p>
+<pre>optional&lt;T <i>(not a ref)</i>&gt;::optional()
+optional&lt;T&amp;&gt;<span lang="es">           </span>::optional()
+</pre>
+</blockquote>
+
+<HR>
+
 <pre>optional&lt;T <i>(not a ref)</i>&gt;::optional( optional const&amp; rhs );</pre>
 <blockquote>
 <p><b>Effect:</b> Copy-Constructs an <b>optional</b>.</p>
@@ -797,7 +822,6 @@ assert ( *opt1 == static_cast&lt;U&gt;(v) ) ;
 
 <HR>
 
-
 <pre>T const&amp; optional&lt;T <i>(not a ref)</i>&gt;::operator*() const ;
 T&amp;       optional&lt;T<i> (not a ref)</i>&gt;::operator*();</pre>
 
@@ -828,6 +852,32 @@ assert ( *opt == w ) ;
 
 <HR>
 
+<pre>T const&amp; optional&lt;T <i>(not a ref)</i>&gt;::get_value_or( T const&amp; default) const ;
+T&amp;       optional&lt;T <i>(not a ref)</i>&gt;::get_value_or( T&amp;       default ) ;
+
+inline T const&amp; get_optional_value_or ( optional&lt;T<i> (not a ref)</i>&gt; const&amp; o, T const&amp; default ) ;
+inline T&amp;       get_optional_value_or ( optional&lt;T <i>(not a ref)</i>&gt;&amp;       o, T&amp;       default ) ;
+</pre>
+<blockquote>
+<p><b>Returns:</b> A reference to the contained value, if any, or <code>default</code></p>
+<p><b>Throws:</b> Nothing.</p>
+<p><b>Example:</b></p>
+<blockquote>
+    <pre>T v, z ;
+optional&lt;T&gt; def;
+T const&amp; y = def.get_value_or(z);
+assert ( y == z ) ;
+
+optional&lt;T&gt; opt ( v );
+T const&amp; u = get_optional_value_or(opt,z);
+assert ( u == v ) ;
+assert ( u != z ) ;
+</pre>
+  </blockquote>
+    <pre></pre>
+</blockquote>
+<HR>
+
 
 <pre>T const&amp; optional&lt;T&amp;&gt;::operator*() const ;
 T      &amp; optional&lt;T<i>&amp;</i>&gt;::operator*();</pre>
@@ -965,18 +1015,47 @@ assert ( opt.is_initialized() );</pre>
 
 <HR>
 
+<pre>optional&lt;T <i>(not a ref)</i>&gt; make_optional( T const&amp; v )</pre>
+<blockquote>
+<p><b>Returns:</b> optional&lt;T&gt;(v) for the <i>deduced</i> type <code>T</code> of <code>v</code>.</p>
+<p><b>Example:</b></p>
+<blockquote>
+<pre>template&lt;class T&gt; void foo ( optional&lt;T&gt; const& opt ) ;
+
+foo ( make_optional(1+1) ) ; // Creates an optional&lt;int&gt;
+</blockquote>
+</blockquote>
+<HR>
+
+<pre>optional&lt;T <i>(not a ref)</i>&gt; make_optional( bool condition, T const&amp; v )</pre>
+<blockquote>
+<p><b>Returns:</b> optional&lt;T&gt;(condition,v) for the <i>deduced</i> type <code>T</code> of <code>v</code>.</p>
+<p><b>Example:</b></p>
+<blockquote>
+<pre>optional&lt;double&gt; calculate_foo()
+{
+  double val = compute_foo();
+  return make_optional(is_not_nan_and_finite(val),val);
+}
+
+optional&lt;double&gt; v = calculate_foo();
+if ( !v )
+  error("foo wasn't computed");
+</blockquote>
+</blockquote>
+
+<HR>
+
 
 <pre>bool operator == ( optional&lt;T&gt; const&amp x, optional&lt;T&gt const&amp y );</pre>
 <blockquote>
 <p><b>Returns:</b> If both <b>x</b> and <b>y</b> are initialied, <code>(*x == *y)</code>.
-If only x or y is initialized, <code>false</code>. If both are uninitialized, <code>true</code>.
-</p>
+If only x or y is initialized, <code>false</code>. If both are uninitialized, <code>true</code>. </p>
 <p><b>Throws:</b> Nothing.</p>
 <p><b>Notes:</b> Pointers have shallow relational operators while <b>optional</b> has
 deep relational operators. Do not use operator == directly in generic code
 which expect to be given either an optional&lt;T&gt; or a pointer;
-use <a href="../../utility/OptionalPointee.html#equal">equal_pointees()</a> instead
-</p>
+use <a href="../../utility/OptionalPointee.html#equal">equal_pointees()</a> instead </p>
 <p><b>Example:</b></p>
 <blockquote>
     <pre>T x(12);
@@ -1012,14 +1091,12 @@ assert ( optX != optZ ) ;
 <blockquote>
 <p><b>Returns:</b> If <b>y</b> is not initialized, <code>false</code>.
 If <b>y</b> is initialized and <b>x</b> is not initialized, <code>true</code>.
-If both <b>x</b> and <b>y</b> are initialized, <code>(*x &lt; *y)</code>.
-</p>
+If both <b>x</b> and <b>y</b> are initialized, <code>(*x &lt; *y)</code>. </p>
 <p><b>Throws:</b> Nothing.</p>
 <p><b>Notes:</b> Pointers have shallow relational operators while <b>optional</b> has
 deep relational operators. Do not use operator &lt; directly in generic code
 which expect to be given either an optional&lt;T&gt; or a pointer;
-use <a href="../../utility/OptionalPointee.html#less">less_pointees()</a> instead
-</p>
+use <a href="../../utility/OptionalPointee.html#less">less_pointees()</a> instead </p>
 <p><b>Example:</b></p>
 <blockquote>
     <pre>T x(12);
@@ -1082,23 +1159,17 @@ assert ( optX != optZ ) ;
 <pre>void swap ( optional&lt;T&gt;&amp x, optional&lt;T&gt&amp y );</pre>
 
 <blockquote>
-<p><b>Effect:</b> If both <b>x</b> and <b>y</b> are initialized, calls <code>swap(*x,*y)</code>
-using std::swap.<br>
+<p><b>Effect:</b> If both <b>x</b> and <b>y</b> are initialized, calls <code>swap(*x,*y)</code> using std::swap.<br>
 If only one is initialized, say x, calls: <code>y.reset(*x); x.reset();</code><br>
-If none is initialized, does nothing.
-</p>
+If none is initialized, does nothing. </p>
 <p><b>Postconditions:</b> The states of x and y interchanged.</p>
 <p><b>Throws:</b> If both are initialized, whatever swap(T&amp;,T&amp;) throws.
-If only one is initialized, whatever T::T ( T const&amp; ) throws.
-</p>
-<p><b>Notes:</b> If both are initialized, swap(T&amp;,T&amp;) is used <i>unqualified</i>
-but with std::swap introduced in scope.<br>
-If only one is initialized, T::~T() and T::T( T const& ) is called.
-</p>
+If only one is initialized, whatever T::T ( T const&amp; ) throws. </p>
+<p><b>Notes:</b> If both are initialized, swap(T&amp;,T&amp;) is used <i>unqualified</i> but with std::swap introduced in scope.<br>
+If only one is initialized, T::~T() and T::T( T const& ) is called. </p>
 <p><b>Exception Safety:</b> If both are initialized, this operation has the exception
 safety guarantees of swap(T&,T&).<br>
-If only one is initialized, it has the same <b>basic</b> guarantee as optional&lt;T&gt;::reset( T const& ).
-</p>
+If only one is initialized, it has the same <b>basic</b> guarantee as optional&lt;T&gt;::reset( T const& ). </p>
 <p><b>Example:</b></p>
 <blockquote>
       <pre>T x(12);
@@ -1254,8 +1325,7 @@ assert(a==b);
 b = 3 ;
 assert(ra!=b); // 'ra' is not rebound to 'b'
 </pre>
-<p>Now, if you assign to an <i>initialized</i> optional&lt;T&amp;&gt;, the effect is to <b>
-rebind</b> to the new object instead of assigning the referee. This is unlike 
+<p>Now, if you assign to an <i>initialized</i> optional&lt;T&amp;&gt;, the effect is to <b>rebind</b> to the new object instead of assigning the referee. This is unlike 
 bare C++ references.</p>
 <pre>int a = 1 ;
 int b = 2 ;
@@ -1358,8 +1428,7 @@ public:
 </pre>
 <p>A limitation of this method is that it doesn't scale well to wrapped objects with multiple
 constructors nor to generic code were the constructor overloads are unknown.</p>
-<p>The solution presented in this library is the family of <b>InPlaceFactories</b> and
-<b>TypedInPlaceFactories</b>.<br>
+<p>The solution presented in this library is the family of <b>InPlaceFactories</b> and <b>TypedInPlaceFactories</b>.<br>
 These factories are a family of classes which encapsulate an increasing number of arbitrary
 constructor parameters and supply a method to construct an object of a given type using those
 parameters at an address specified by the user via placement new.</p>
@@ -1427,10 +1496,7 @@ public:
   W ( in_place(123,"hello") ) ;
 }
 </pre>
-<p>The factories are implemented in the headers:
-<a href="../../../boost/utility/in_place_factory.hpp">in_place_factory.hpp</a> and
-<a href="../../../boost/utility/typed_in_place_factory.hpp">typed_in_place_factory.hpp</a>
-</p>
+<p>The factories are implemented in the headers: <a href="../../../boost/utility/in_place_factory.hpp">in_place_factory.hpp</a> and <a href="../../../boost/utility/typed_in_place_factory.hpp">typed_in_place_factory.hpp</a> </p>
 
 <HR>
 
@@ -1473,8 +1539,7 @@ of the assignment methods:</p>
   TypedInPlaceFactory const&amp; ) </code></li>
   <li> <code>optional&lt;T&gt;:::reset ( T const&amp;)</code></li>
 </ul>
-<p>Can only <i>guarantee</i> the <u>basic exception safety</u>: The lvalue optional is left <u>uninitialized</u>
-if an exception is thrown (any previous value is <i>first</i> destroyed using T::~T())</p>
+<p>Can only <i>guarantee</i> the <u>basic exception safety</u>: The lvalue optional is left <u>uninitialized</u> if an exception is thrown (any previous value is <i>first</i> destroyed using T::~T())</p>
 <p>On the other hand, the <i>uninitializing</i> methods:</p>
 <ul>
   <li><code>optional&lt;T&gt;::operator= ( detail::none_t ) </code></li>
@@ -1603,12 +1668,9 @@ T <u>is not</u> required to be <a href="http://www.sgi.com/tech/stl/DefaultConst
 <P>Revised April 21, 2005</P>
 <p><EFBFBD> Copyright Fernando Luis Cacciola Carballal, 2003,2004,2005</p>
 <p> Use, modification, and distribution are subject to the Boost Software
-License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">
-LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
-www.boost.org/LICENSE_1_0.txt</a>)</p>
+License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
 <P>Developed by <A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>,
 the latest version of this file can be found at <A
-HREF="http://www.boost.org">www.boost.org</A>, and the boost
-<A HREF="http://www.boost.org/more/mailing_lists.htm#main">discussion lists</A></P>
-</BODY>
-</HTML>
+HREF="http://www.boost.org">www.boost.org</A>, and the boost <A HREF="http://www.boost.org/more/mailing_lists.htm#main">discussion lists</A></P>
+</pre></BODY>
+</HTML>

doc/optional.qbk

@@ -0,0 +1,131 @@
+[library Boost.Optional
+    [quickbook 1.4]
+    [authors [Cacciola Carballal, Fernando Luis]]
+    [copyright 2003-2007 Fernando Luis Cacciola Carballal]
+    [category miscellaneous]
+    [id optional]
+    [dirname optional]
+    [purpose
+        Discriminated-union wrapper for optional values
+    ]
+    [source-mode c++]
+    [license
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or copy at
+[@http://www.boost.org/LICENSE_1_0.txt])
+    ]
+]
+
+[/ Macros will be used for links so we have a central place to change them ]
+
+
+[/ Cited Boost resources ]
+
+[def __BOOST_VARIANT__ [@../../../variant/index.html Boost.Variant]]
+[def __BOOST_TRIBOOL__ [@../../../tribool/index.html boost::tribool]]
+
+[def __OPTIONAL_POINTEE__ [@../../../utility/OptionalPointee.html OptionalPointee]]
+[def __COPY_CONSTRUCTIBLE__ [@../../../utility/CopyConstructible.html Copy Constructible]]
+[def __FUNCTION_EQUAL_POINTEES__ [@../../../utility/OptionalPointee.html#equal `equal_pointees()`]]
+[def __FUNCTION_LESS_POINTEES__ [@../../../utility/OptionalPointee.html#less `less_pointees()`]]
+
+[def __IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/in_place_factory.hpp in_place_factory.hpp]]
+[def __TYPED_IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/typed_in_place_factory.hpp typed_in_place_factory.hpp]]
+
+[/ Other web resources ]
+
+[def __HASKELL__ [@http://www.haskell.org/ Haskell]]
+[def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html Default Constructible]]
+
+
+[/ Icons ]
+
+[def __NOTE__ [$images/note.png]]
+[def __ALERT__ [$images/caution.png]]
+[def __DETAIL__ [$images/note.png]]
+[def __TIP__ [$images/tip.png]]
+[def __QUESTION_MARK__ [$images/question.png]]
+[def __SPACE__ [$images/space.png]]
+[def __GO_TO__ [$images/callouts/R.png]]
+
+
+[section Motivation]
+
+Consider these functions which should return a value but which might not have
+a value to return:
+
+* (A) `double sqrt(double n );`
+* (B) `char get_async_input();`
+* (C) `point polygon::get_any_point_effectively_inside();`
+
+There are different approaches to the issue of not having a value to return.
+
+A typical approach is to consider the existence of a valid return value as a
+postcondition, so that if the function cannot compute the value to return, it
+has either undefined behavior (and can use assert in a debug build) or uses a
+runtime check and throws an exception if the postcondition is violated. This
+is a reasonable choice for example, for function (A), because the lack of a
+proper return value is directly related to an invalid parameter (out of domain
+argument), so it is appropriate to require the callee to supply only parameters
+in a valid domain for execution to continue normally.
+
+However, function (B), because of its asynchronous nature, does not fail just
+because it can't find a value to return; so it is incorrect to consider such
+a situation an error and assert or throw an exception. This function must
+return, and somehow, must tell the callee that it is not returning a meaningful
+value.
+
+A similar situation occurs with function (C): it is conceptually an error to
+ask a ['null-area] polygon to return a point inside itself, but in many
+applications, it is just impractical for performance reasons to treat this as
+an error (because detecting that the polygon has no area might be too expensive
+to be required to be tested previously), and either an arbitrary point
+(typically at infinity) is returned, or some efficient way to tell the callee
+that there is no such point is used.
+
+There are various mechanisms to let functions communicate that the returned
+value is not valid. One such mechanism, which is quite common since it has
+zero or negligible overhead, is to use a special value which is reserved to
+communicate this. Classical examples of such special values are `EOF`,
+`string::npos`, points at infinity, etc...
+
+When those values exist, i.e. the return type can hold all meaningful values
+['plus] the ['signal] value, this mechanism is quite appropriate and well known.
+Unfortunately, there are cases when such values do not exist. In these cases,
+the usual alternative is either to use a wider type, such as `int` in place of
+`char`; or a compound type, such as `std::pair<point,bool>`.
+
+Returning a `std::pair<T,bool>`, thus attaching a boolean flag to the result
+which indicates if the result is meaningful, has the advantage that can be
+turned into a consistent idiom since the first element of the pair can be
+whatever the function would conceptually return. For example, the last two
+functions could have the following interface:
+
+    std::pair<char,bool> get_async_input();
+    std::pair<point,bool> polygon::get_any_point_effectively_inside();
+
+These functions use a consistent interface for dealing with possibly inexistent
+results:
+
+    std::pair<point,bool> p = poly.get_any_point_effectively_inside();
+    if ( p.second )
+        flood_fill(p.first);
+
+However, not only is this quite a burden syntactically, it is also error prone
+since the user can easily use the function result (first element of the pair)
+without ever checking if it has a valid value.
+
+Clearly, we need a better idiom.
+
+[endsect]
+
+
+[include development.qbk]
+[include reference.qbk]
+[include examples.qbk]
+[include special_cases.qbk]
+[include implementation_notes.qbk]
+[include dependencies.qbk]
+[include acknowledgments.qbk]
+
+

doc/reference.qbk

@@ -0,0 +1,880 @@
+[/
+    Boost.Optional
+
+    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+
+[section Synopsis]
+
+    namespace boost {
+
+    template<class T>
+    class optional
+    {
+        public :
+
+        // (If T is of reference type, the parameters and results by reference are by value)
+
+        optional () ; ``[link reference_optional_constructor __GO_TO__]``
+
+        optional ( none_t ) ; ``[link reference_optional_constructor_none_t __GO_TO__]``
+
+        optional ( T const& v ) ; ``[link reference_optional_constructor_value __GO_TO__]``
+
+        // [new in 1.34]
+        optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]`` 
+
+        optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]``
+
+        template<class U> explicit optional ( optional<U> const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]``
+
+        template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
+
+        template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
+
+        optional& operator = ( none_t ) ; ``[/[link reference_optional_operator_equal_none_t __GO_TO__]]``
+
+        optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]``
+
+        optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]``
+
+        template<class U> optional& operator = ( optional<U> const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]``
+
+        template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
+
+        template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
+
+        T const& get() const ; ``[link reference_optional_get __GO_TO__]``
+        T&       get() ; ``[link reference_optional_get __GO_TO__]``
+
+        // [new in 1.34]
+        T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` 
+
+        T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]``
+        T*       operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]``
+
+        T const& operator *() const ; ``[link reference_optional_get __GO_TO__]``
+        T&       operator *() ; ``[link reference_optional_get __GO_TO__]``
+
+        T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]``
+        T*       get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]``
+
+        operator unspecified-bool-type() const ; ``[link reference_optional_operator_bool __GO_TO__]``
+
+        bool operator!() const ; ``[link reference_optional_operator_not __GO_TO__]``
+
+        // deprecated methods
+
+        // (deprecated)
+        void reset() ; ``[link reference_optional_reset __GO_TO__]``
+
+        // (deprecated)
+        void reset ( T const& ) ; ``[link reference_optional_reset_value __GO_TO__]``
+
+        // (deprecated)
+        bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]``
+
+    };
+
+    template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]``
+
+    template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]``
+
+    template<class T> inline bool operator <  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]``
+
+    template<class T> inline bool operator >  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]``
+
+    template<class T> inline bool operator <= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_or_equal_optional_optional __GO_TO__]``
+
+    template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_or_equal_optional_optional __GO_TO__]``
+
+    // [new in 1.34]
+    template<class T> inline optional<T> make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]``
+
+    // [new in 1.34]
+    template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]``
+
+    // [new in 1.34]
+    template<class T> inline T const& get_optional_value_or ( optional<T> const& opt, T const& default ) ; ``[link reference_optional_get_value_or_value __GO_TO__]`` 
+
+    template<class T> inline T const& get ( optional<T> const& opt ) ; ``[link reference_optional_get __GO_TO__]``
+
+    template<class T> inline T& get ( optional<T> & opt ) ; ``[link reference_optional_get __GO_TO__]``
+
+    template<class T> inline T const* get ( optional<T> const* opt ) ; ``[link reference_optional_get __GO_TO__]``
+
+    template<class T> inline T* get ( optional<T>* opt ) ; ``[link reference_optional_get __GO_TO__]``
+
+    template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
+
+    template<class T> inline T* get_pointer ( optional<T> & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
+
+    template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; ``[link reference_swap_optional_optional __GO_TO__]``
+
+    } // namespace boost
+
+
+[endsect]
+
+[section Detailed Semantics]
+
+Because `T` might be of reference type, in the sequel, those entries whose
+semantic depends on `T` being of reference type or not will be distinguished
+using the following convention:
+* If the entry reads: `optional<T`['(not a ref)]`>`, the description
+corresponds only to the case where `T` is not of reference type.
+* If the entry reads: `optional<T&>`, the description corresponds only to
+the case where `T` is of reference type.
+* If the entry reads: `optional<T>`, the description is the same for both
+cases.
+
+[note
+The following section contains various `assert()` which are used only to show
+the postconditions as sample code. It is not implied that the type `T` must
+support each particular expression but that if the expression is supported,
+the implied condition holds.
+]
+
+__SPACE__
+
+[heading optional class member functions]
+
+__SPACE__
+
+[#reference_optional_constructor]
+
+[: `optional<T>::optional();`]
+
+* [*Effect:] Default-Constructs an `optional`.
+* [*Postconditions:] `*this` is [_uninitialized].
+* [*Throws:] Nothing.
+* Notes: T's default constructor [_is not] called.
+* [*Example:]
+``
+optional<T> def ;
+assert ( !def ) ;
+``
+
+__SPACE__
+
+[#reference_optional_constructor_none_t]
+
+[: `optional<T>::optional( none_t );`]
+
+* [*Effect:] Constructs an `optional` uninitialized.
+* [*Postconditions:] `*this` is [_uninitialized].
+* [*Throws:] Nothing.
+* [*Notes:] `T`'s default constructor [_is not] called. The expression
+`boost::none` denotes an instance of `boost::none_t` that can be used as
+the parameter.
+* [*Example:]
+``
+#include <boost/none.hpp>
+optional<T> n(none) ;
+assert ( !n ) ;
+``
+
+__SPACE__
+
+[#reference_optional_constructor_value]
+
+[: `optional<T `['(not a ref)]`>::optional( T const& v )`]
+
+* [*Effect:] Directly-Constructs an `optional`.
+* [*Postconditions:] `*this` is [_initialized] and its value is a['copy]
+of `v`.
+* [*Throws:] Whatever `T::T( T const& )` throws.
+* [*Notes: ] `T::T( T const& )` is called.
+* [*Exception Safety:] Exceptions can only be thrown during
+`T::T( T const& );` in that case, this constructor has no effect.
+* [*Example:]
+``
+T v;
+optional<T> opt(v);
+assert ( *opt == v ) ;
+``
+
+__SPACE__
+
+[: `optional<T&>::optional( T& ref )`]
+
+* [*Effect:] Directly-Constructs an `optional`.
+* [*Postconditions:] `*this` is [_initialized] and its value is an instance
+of an internal type wrapping the reference `ref`.
+* [*Throws:] Nothing.
+* [*Example:]
+``
+T v;
+T& vref = v ;
+optional<T&> opt(vref);
+assert ( *opt == v ) ;
+++ v ; // mutate referee
+assert (*opt == v);
+``
+
+__SPACE__
+
+[#reference_optional_constructor_bool_value]
+
+[: `optional<T` ['(not a ref)]`>::optional( bool condition, T const& v ) ;` ]
+[: `optional<T&>           ::optional( bool condition, T&       v ) ;` ]
+
+* If condition is true, same as:
+
+[: `optional<T` ['(not a ref)]`>::optional( T const& v )`]
+[: `optional<T&>           ::optional( T&       v )`]
+
+* otherwise, same as:
+
+[: `optional<T ['(not a ref)]>::optional()`]
+[: `optional<T&>           ::optional()`]
+
+__SPACE__
+
+[#reference_optional_constructor_optional]
+
+[: `optional<T `['(not a ref)]`>::optional( optional const& rhs );`]
+
+* [*Effect:] Copy-Constructs an `optional`.
+* [*Postconditions:] If rhs is initialized, `*this` is initialized and
+its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
+* [*Throws:] Whatever `T::T( T const& )` throws.
+* [*Notes:] If rhs is initialized, `T::T(T const& )` is called.
+* [*Exception Safety:] Exceptions can only be thrown during
+`T::T( T const& );` in that case, this constructor has no effect.
+* [*Example:]
+``
+optional<T> uninit ;
+assert (!uninit);
+
+optional<T> uinit2 ( uninit ) ;
+assert ( uninit2 == uninit );
+
+optional<T> init( T(2) );
+assert ( *init == T(2) ) ;
+
+optional<T> init2 ( init ) ;
+assert ( init2 == init ) ;
+``
+
+__SPACE__
+
+[: `optional<T&>::optional( optional const& rhs );`]
+
+* [*Effect:] Copy-Constructs an `optional`.
+* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
+value is another reference to the same object referenced by `*rhs`; else
+`*this` is uninitialized.
+* [*Throws:] Nothing.
+* [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will reefer to the
+same object (they alias).
+* [*Example:]
+``
+optional<T&> uninit ;
+assert (!uninit);
+
+optional<T&> uinit2 ( uninit ) ;
+assert ( uninit2 == uninit );
+
+T v = 2 ; T& ref = v ;
+optional<T> init(ref);
+assert ( *init == v ) ;
+
+optional<T> init2 ( init ) ;
+assert ( *init2 == v ) ;
+
+v = 3 ;
+
+assert ( *init  == 3 ) ;
+assert ( *init2 == 3 ) ;
+``
+
+__SPACE__
+
+[#reference_optional_constructor_other_optional]
+
+[: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U> const& rhs );`]
+
+* [*Effect:] Copy-Constructs an `optional`.
+* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
+value is a ['copy] of the value of rhs converted to type `T`; else `*this` is
+uninitialized.
+* [*Throws:] Whatever `T::T( U const& )` throws.
+* [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a
+valid conversion from `U` to `T`.
+* [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );`
+in that case, this constructor has no effect.
+* [*Example:]
+``
+optional<double> x(123.4);
+assert ( *x == 123.4 ) ;
+
+optional<int> y(x) ;
+assert( *y == 123 ) ;
+``
+
+__SPACE__
+
+[#reference_optional_constructor_factory]
+
+[: `template<InPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( InPlaceFactory const& f );`]
+[: `template<TypedInPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( TypedInPlaceFactory const& f );`]
+
+* [*Effect:] Constructs an `optional` with a value of `T` obtained from the
+factory.
+* [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
+from the factory `f` (i.e., the value [_is not copied]).
+* [*Throws:] Whatever the `T` constructor called by the factory throws.
+* [*Notes:] See [link optional_in_place_factories In-Place Factories]
+* [*Exception Safety:] Exceptions can only be thrown during the call to
+the `T` constructor used by the factory; in that case, this constructor has
+no effect.
+* [*Example:]
+``
+class C { C ( char, double, std::string ) ; } ;
+
+C v('A',123.4,"hello");
+
+optional<C> x( in_place   ('A', 123.4, "hello") ); // InPlaceFactory used
+optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used
+
+assert ( *x == v ) ;
+assert ( *y == v ) ;
+``
+
+__SPACE__
+
+[#reference_optional_operator_equal_value]
+
+[: `optional& optional<T` ['(not a ref)]`>::operator= ( T const& rhs ) ;`]
+
+* [*Effect:] Assigns the value `rhs` to an `optional`.
+* [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
+* [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws.
+* [*Notes:] If `*this` was initialized, `T`'s assignment operator is used,
+otherwise, its copy-constructor is used.
+* [*Exception Safety:] In the event of an exception, the initialization
+state of `*this` is unchanged and its value unspecified as far as `optional`
+is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
+uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly
+uninitialized.
+* [*Example:]
+``
+T x;
+optional<T> def ;
+optional<T> opt(x) ;
+
+T y;
+def = y ;
+assert ( *def == y ) ;
+opt = y ;
+assert ( *opt == y ) ;
+``
+
+__SPACE__
+
+[: `optional<T&>& optional<T&>::operator= ( T& const& rhs ) ;`]
+
+* [*Effect:] (Re)binds thee wrapped reference.
+* [*Postconditions: ] `*this` is initialized and it references the same
+object referenced by `rhs`.
+* [*Notes:] If `*this` was initialized, is is ['rebound] to the new object.
+See [link optional_refassign here] for details on this behavior.
+* [*Example:]
+``
+int a = 1 ;
+int b = 2 ;
+T& ra = a ;
+T& rb = b ;
+optional<int&> def ;
+optional<int&> opt(ra) ;
+
+def = rb ; // binds 'def' to 'b' through 'rb'
+assert ( *def == b ) ;
+*def = a ; // changes the value of 'b' to a copy of the value of 'a'
+assert ( b == a ) ;
+int c = 3;
+int& rc = c ;
+opt = rc ; // REBINDS to 'c' through 'rc'
+c = 4 ;
+assert ( *opt == 4 ) ;
+``
+
+__SPACE__
+
+[#reference_optional_operator_equal_optional]
+
+[: `optional& optional<T` ['(not a ref)]`>::operator= ( optional const& rhs ) ;`]
+
+* [*Effect:] Assigns another `optional` to an `optional`.
+* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
+its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
+* [*Throws:] Whatever `T::operator( T const&)` or  `T::T( T const& )` throws.
+* [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s
+['assignment operator] is used. If `*this` is initially initialized but `rhs` is
+uninitialized, `T`'s [destructor] is called. If `*this` is initially uninitialized
+but `rhs` is initialized, `T`'s ['copy constructor] is called.
+* [*Exception Safety:] In the event of an exception, the initialization state of
+`*this` is unchanged and its value unspecified as far as optional is concerned
+(it is up to `T`'s `operator=()`). If `*this` is initially uninitialized and
+`T`'s ['copy constructor] fails, `*this` is left properly uninitialized.
+* [*Example:]
+``
+T v;
+optional<T> opt(v);
+optional<T> def ;
+
+opt = def ;
+assert ( !def ) ;
+// previous value (copy of 'v') destroyed from within 'opt'.
+``
+
+__SPACE__
+
+[: `optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;`]
+
+* [*Effect:] (Re)binds thee wrapped reference.
+* [*Postconditions:] If `*rhs` is initialized, `*this` is initialized and it
+references the same object referenced by `*rhs`; otherwise, `*this` is
+uninitialized (and references no object).
+* [*Notes:] If `*this` was initialized and so is *rhs, this is is ['rebound] to
+the new object. See [link optional_refassign here] for details on this behavior.
+* [*Example:]
+``
+int a = 1 ;
+int b = 2 ;
+T& ra = a ;
+T& rb = b ;
+optional<int&> def ;
+optional<int&> ora(ra) ;
+optional<int&> orb(rb) ;
+
+def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb'
+assert ( *def == b ) ;
+*def = ora ; // changes the value of 'b' to a copy of the value of 'a'
+assert ( b == a ) ;
+int c = 3;
+int& rc = c ;
+optional<int&> orc(rc) ;
+ora = orc ; // REBINDS ora to 'c' through 'rc'
+c = 4 ;
+assert ( *ora == 4 ) ;
+``
+
+__SPACE__
+
+[#reference_optional_operator_equal_other_optional]
+
+[: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U> const& rhs ) ;`]
+
+* [*Effect:] Assigns another convertible optional to an optional.
+* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
+its value is a ['copy] of the value of `rhs` ['converted] to type `T`; else
+`*this` is uninitialized. 
+* [*Throws:] Whatever `T::operator=( U const& )` or `T::T( U const& )` throws.
+* [*Notes:] If both `*this` and rhs are initially initialized, `T`'s
+['assignment operator] (from `U`) is used. If `*this` is initially initialized
+but `rhs` is uninitialized, `T`'s ['destructor] is called. If `*this` is
+initially uninitialized but rhs is initialized, `T`'s ['converting constructor]
+(from `U`) is called.
+* [*Exception Safety:] In the event of an exception, the initialization state
+of `*this` is unchanged and its value unspecified as far as optional is
+concerned (it is up to `T`'s `operator=()`). If `*this` is initially
+uninitialized and `T`'s converting constructor fails, `*this` is left properly
+uninitialized.
+* [*Example:]
+``
+T v;
+optional<T> opt0(v);
+optional<U> opt1;
+
+opt1 = opt0 ;
+assert ( *opt1 == static_cast<U>(v) ) ;
+``
+
+__SPACE__
+
+[#reference_optional_reset_value]
+
+[: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`]
+* [*Deprecated:] same as `operator= ( T const& v) ;`
+
+__SPACE__
+
+[#reference_optional_reset]
+
+[: `void optional<T>::reset() ;`]
+* [*Deprecated:] Same as `operator=( detail::none_t );`
+
+__SPACE__
+
+[#reference_optional_get]
+
+[: `T const& optional<T` ['(not a ref)]`>::operator*() const ;`]
+[: `T&       optional<T` ['(not a ref)]`>::operator*();`]
+[: `T const& optional<T` ['(not a ref)]`>::get() const ;`]
+[: `T&       optional<T` ['(not a ref)]`>::get() ;`]
+
+[: `inline T const& get ( optional<T` ['(not a ref)]`> const& ) ;`]
+[: `inline T&       get ( optional<T` ['(not a ref)]`> &) ;`]
+
+* [*Requirements:] `*this` is initialized
+* [*Returns:] A reference to the contained value
+* [*Throws:] Nothing.
+* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
+* [*Example:]
+``
+T v ;
+optional<T> opt ( v );
+T const& u = *opt;
+assert ( u == v ) ;
+T w ;
+*opt = w ;
+assert ( *opt == w ) ;
+``
+
+__SPACE__
+
+[#reference_optional_get_value_or_value]
+
+[: `T const& optional<T` ['(not a ref)]`>::get_value_or( T const& default) const ;`]
+[: `T&       optional<T` ['(not a ref)]`>::get_value_or( T&       default ) ;`]
+
+[: `inline T const& get_optional_value_or ( optional<T` ['(not a ref)]`> const& o, T const& default ) ;`]
+[: `inline T&       get_optional_value_or ( optional<T` ['(not a ref)]`>&       o, T&       default ) ;`]
+
+* [*Returns:] A reference to the contained value, if any, or `default`.
+* [*Throws:] Nothing.
+* [*Example:]
+``
+T v, z ;
+optional<T> def;
+T const& y = def.get_value_or(z);
+assert ( y == z ) ;
+
+optional<T> opt ( v );
+T const& u = get_optional_value_or(opt,z);
+assert ( u == v ) ;
+assert ( u != z ) ;
+``
+
+__SPACE__
+
+[: `T const& optional<T&>::operator*() const ;`]
+[: `T      & optional<T&>::operator*();`]
+[: `T const& optional<T&>::get() const ;`]
+[: `T&       optional<T&>::get() ;`]
+
+[: `inline T const& get ( optional<T&> const& ) ;`]
+[: `inline T&       get ( optional<T&> &) ;`]
+
+* [*Requirements: ] `*this` is initialized
+* [*Returns:] [_The] reference contained.
+* [*Throws:] Nothing.
+* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
+* [*Example:]
+``
+T v ;
+T& vref = v ;
+optional<T&> opt ( vref );
+T const& vref2 = *opt;
+assert ( vref2 == v ) ;
+++ v ;
+assert ( *opt == v ) ;
+``
+
+__SPACE__
+
+[#reference_optional_get_ptr]
+
+[: `T const* optional<T` ['(not a ref)]`>::get_ptr() const ;`]
+[: `T*       optional<T` ['(not a ref)]`>::get_ptr() ;`]
+
+[: `inline T const* get_pointer ( optional<T` ['(not a ref)]`> const& ) ;`]
+[: `inline T*       get_pointer ( optional<T` ['(not a ref)]`> &) ;`]
+
+* [*Returns:] If `*this` is initialized, a pointer to the contained value;
+else `0` (['null]).
+* [*Throws:] Nothing.
+* [*Notes:] The contained value is permanently stored within `*this`, so you
+should not hold nor delete this pointer
+* [*Example:]
+``
+T v;
+optional<T> opt(v);
+optional<T> const copt(v);
+T* p = opt.get_ptr() ;
+T const* cp = copt.get_ptr();
+assert ( p == get_pointer(opt) );
+assert ( cp == get_pointer(copt) ) ;
+``
+
+__SPACE__
+
+[#reference_optional_operator_arrow]
+
+[: `T const* optional<T` ['(not a ref)]`>::operator ->() const ;`]
+[: `T*       optional<T` ['(not a ref)]`>::operator ->()       ;`]
+
+* [*Requirements: ] `*this` is initialized.
+* [*Returns:] A pointer to the contained value.
+* [*Throws:] Nothing.
+* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
+* [*Example:]
+``
+struct X { int mdata ; } ;
+X x ;
+optional<X> opt (x);
+opt->mdata = 2 ;
+``
+
+__SPACE__
+
+[#reference_optional_operator_bool]
+
+[: `optional<T>::operator `['unspecified-bool-type]`() const ;`]
+
+* [*Returns:] An unspecified value which if used on a boolean context
+is equivalent to (`get() != 0`)
+* [*Throws:] Nothing.
+* [*Example:]
+``
+optional<T> def ;
+assert ( def == 0 );
+optional<T> opt ( v ) ;
+assert ( opt );
+assert ( opt != 0 );
+``
+
+__SPACE__
+
+[#reference_optional_operator_not]
+
+[: `bool optional<T>::operator!() ;`]
+
+* [*Returns:] If `*this` is uninitialized, `true`; else `false`.
+* [*Throws:] Nothing.
+* [*Notes:] This operator is provided for those compilers which can't
+use the ['unspecified-bool-type operator] in certain boolean contexts.
+* [*Example:]
+``
+optional<T> opt ;
+assert ( !opt );
+*opt = some_T ;
+
+// Notice the "double-bang" idiom here.
+assert ( !!opt ) ;
+``
+
+__SPACE__
+
+[#reference_optional_is_initialized]
+
+[: `bool optional<T>::is_initialized() const ;`]
+
+* [*Returns: ] `true` if the `optional` is initialized, `false` otherwise.
+* [*Throws:] Nothing.
+* [*Example:]
+``
+optional<T> def ;
+assert ( !def.is_initialized() );
+optional<T> opt ( v ) ;
+assert ( opt.is_initialized() );
+``
+
+__SPACE__
+
+[heading Free functions]
+
+__SPACE__
+
+[#reference_make_optional_value]
+
+[: `optional<T` ['(not a ref)]`> make_optional( T const& v )`]
+
+* [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
+* [*Example:]
+``
+template<class T> void foo ( optional<T> const& opt ) ;
+
+foo ( make_optional(1+1) ) ; // Creates an optional<int>
+``
+
+__SPACE__
+
+[#reference_make_optional_bool_value]
+
+[: `optional<T` ['(not a ref)]`> make_optional( bool condition, T const& v )`]
+
+* [*Returns: ] `optional<T>(condition,v)` for the ['deduced] type `T` of `v`.
+* [*Example:]
+``
+optional<double> calculate_foo()
+{
+  double val = compute_foo();
+  return make_optional(is_not_nan_and_finite(val),val);
+}
+
+optional<double> v = calculate_foo();
+if ( !v )
+  error("foo wasn't computed");
+``
+
+__SPACE__
+
+[#reference_operator_compare_equal_optional_optional]
+
+[: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
+`x` or `y` is initialized, `false`. If both are uninitialized, `true`.
+* [*Throws:] Nothing.
+* [*Notes:] Pointers have shallow relational operators while `optional` has
+deep relational operators. Do not use `operator ==` directly in generic
+code which expect to be given either an `optional<T>` or a pointer; use
+__FUNCTION_EQUAL_POINTEES__ instead
+* [*Example:]
+``
+T x(12);
+T y(12);
+T z(21);
+optional<T> def0 ;
+optional<T> def1 ;
+optional<T> optX(x);
+optional<T> optY(y);
+optional<T> optZ(z);
+
+// Identity always hold
+assert ( def0 == def0 );
+assert ( optX == optX );
+
+// Both uninitialized compare equal
+assert ( def0 == def1 );
+
+// Only one initialized compare unequal.
+assert ( def0 != optX );
+
+// Both initialized compare as (*lhs == *rhs)
+assert ( optX == optY ) ;
+assert ( optX != optZ ) ;
+``
+
+__SPACE__
+
+[#reference_operator_compare_less_optional_optional]
+
+[: `bool operator < ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns:] If `y` is not initialized, `false`. If `y` is initialized
+and `x` is not initialized, `true`. If both `x` and `y` are initialized,
+`(*x < *y)`.
+* [*Throws:] Nothing.
+* [*Notes:] Pointers have shallow relational operators while `optional` has
+deep relational operators. Do not use `operator <` directly in generic code
+which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead.
+* [*Example:]
+``
+T x(12);
+T y(34);
+optional<T> def ;
+optional<T> optX(x);
+optional<T> optY(y);
+
+// Identity always hold
+assert ( !(def < def) );
+assert ( optX == optX );
+
+// Both uninitialized compare equal
+assert ( def0 == def1 );
+
+// Only one initialized compare unequal.
+assert ( def0 != optX );
+
+// Both initialized compare as (*lhs == *rhs)
+assert ( optX == optY ) ;
+assert ( optX != optZ ) ;
+``
+
+__SPACE__
+
+[#reference_operator_compare_not_equal_optional_optional]
+
+[: `bool operator != ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns: ] `!( x == y );`
+* [*Throws:] Nothing.
+
+__SPACE__
+
+[#reference_operator_compare_greater_optional_optional]
+
+[: `bool operator > ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns: ] `( y < x );`
+* [*Throws:] Nothing.
+
+__SPACE__
+
+[#reference_operator_compare_less_or_equal_optional_optional]
+
+[: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns: ] `!( y<x );`
+* [*Throws:] Nothing.
+
+__SPACE__
+
+[#reference_operator_compare_greater_or_equal_optional_optional]
+
+[: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]
+
+* [*Returns: ] `!( x<y );`
+* [*Throws:] Nothing.
+
+__SPACE__
+
+[#reference_swap_optional_optional]
+
+[: `void swap ( optional<T>& x, optional<T>& y );`]
+
+* [*Effect:] If both `x` and `y` are initialized, calls `swap(*x,*y)`
+using `std::swap`. If only one is initialized, say `x`, calls:
+`y.reset(*x); x.reset();` If none is initialized, does nothing.
+* [*Postconditions:] The states of `x` and `y` interchanged.
+* [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only
+one is initialized, whatever `T::T ( T const& )` throws.
+* [*Notes:] If both are initialized, `swap(T&,T&)` is used unqualified but
+with `std::swap` introduced in scope.
+If only one is initialized, `T::~T()` and `T::T( T const& )` is called.
+* [*Exception Safety:] If both are initialized, this operation has the
+exception safety guarantees of `swap(T&,T&)`.
+If only one is initialized, it has the same basic guarantee as
+`optional<T>::reset( T const& )`.
+* [*Example:]
+``
+T x(12);
+T y(21);
+optional<T> def0 ;
+optional<T> def1 ;
+optional<T> optX(x);
+optional<T> optY(y);
+
+boost::swap(def0,def1); // no-op
+
+boost::swap(def0,optX);
+assert ( *def0 == x );
+assert ( !optX );
+
+boost::swap(def0,optX); // Get back to original values
+
+boost::swap(optX,optY);
+assert ( *optX == y );
+assert ( *optY == x );
+``
+
+[endsect]

doc/special_cases.qbk

@@ -0,0 +1,376 @@
+
+[section Optional references]
+
+This library allows the template parameter `T` to be of reference type:
+`T&`, and to some extent, `T const&`.
+
+However, since references are not real objects some restrictions apply and
+some operations are not available in this case:
+
+* Converting constructors
+* Converting assignment
+* InPlace construction
+* InPlace assignment
+* Value-access via pointer
+
+Also, even though `optional<T&>` treats it wrapped pseudo-object much as
+a real value, a true real reference is stored so aliasing will ocurr:
+
+* Copies of `optional<T&>` will copy the references but all these references
+will nonetheless reefer to the same object.
+* Value-access will actually provide access to the referenced object
+rather than the reference itself.
+
+[endsect]
+
+[#optional_refassign]
+
+[section Rebinding semantics for assignment of optional references]
+
+If you assign to an ['uninitialized ] `optional<T&>` the effect is to bind (for
+the first time) to the object. Clearly, there is no other choice.
+
+    int x = 1 ;
+    int& rx = x ;
+    optional<int&> ora ;
+    optional<int&> orb(x) ;
+    ora = orb ; // now 'ora' is bound to 'x' through 'rx'
+    *ora = 2 ; // Changes value of 'x' through 'ora'
+    assert(x==2); 
+
+If you assign to a bare C++ reference, the assignment is forwarded to the
+referenced object; it's value changes but the reference is never rebound.
+
+    int a = 1 ;
+    int& ra = a ;
+    int b = 2 ;
+    int& rb = b ;
+    ra = rb ; // Changes the value of 'a' to 'b'
+    assert(a==b);
+    b = 3 ;
+    assert(ra!=b); // 'ra' is not rebound to 'b'
+
+Now, if you assign to an ['initialized ] `optional<T&>`, the effect is to
+[*rebind] to the new object instead of assigning the referee. This is unlike
+bare C++ references.
+
+    int a = 1 ;
+    int b = 2 ;
+    int& ra = a ;
+    int& rb = b ;
+    optional<int&> ora(ra) ;
+    optional<int&> orb(rb) ;
+    ora = orb ; // 'ora' is rebound to 'b'
+    *ora = 3 ; // Changes value of 'b' (not 'a')
+    assert(a==1); 
+    assert(b==3); 
+
+[heading Rationale]
+
+Rebinding semantics for the assignment of ['initialized ] `optional` references has
+been chosen to provide [*consistency among initialization states] even at the
+expense of lack of consistency with the semantics of bare C++ references.
+It is true that `optional<U>` strives to behave as much as possible as `U`
+does whenever it is initialized; but in the case when `U` is `T&`, doing so would
+result in inconsistent behavior w.r.t to the lvalue initialization state.
+
+Imagine `optional<T&>` forwarding assignment to the referenced object (thus
+changing the referenced object value but not rebinding), and consider the
+following code:
+
+    optional<int&> a = get();
+    int x = 1 ;
+    int& rx = x ;
+    optional<int&> b(rx);
+    a = b ;
+
+What does the assignment do?
+
+If `a` is ['uninitialized], the answer is clear: it binds to `x` (we now have
+another reference to `x`).
+But what if `a` is already ['initialized]? it would change the value of the
+referenced object (whatever that is); which is inconsistent with the other
+possible case.
+
+If `optional<T&>` would assign just like `T&` does, you would never be able to
+use Optional's assignment without explicitly handling the previous
+initialization state unless your code is capable of functioning whether
+after the assignment, `a` aliases the same object as `b` or not.
+
+That is, you would have to discriminate in order to be consistency.
+
+If in your code rebinding to another object is not an option, then is very
+likely that binding for the fist time isn't either. In such case, assignment
+to an ['uninitialized ] `optional<T&>` shall be prohibited. It is quite possible
+that in such scenario the precondition that the lvalue must be already
+initialized exist. If it doesn't, then binding for the first time is OK
+while rebinding is not which is IMO very unlikely.
+In such scenario, you can assign the value itself directly, as in:
+
+    assert(!!opt);
+    *opt=value;
+
+[endsect]
+
+[#optional_in_place_factories]
+
+[section In-Place Factories]
+
+One of the typical problems with wrappers and containers is that their
+interfaces usually provide an operation to initialize or assign the
+contained object as a copy of some other object. This not only requires the
+underlying type to be __COPY_CONSTRUCTIBLE__, but also requires the existence of
+a fully constructed object, often temporary, just to follow the copy from:
+
+    struct X
+    {
+        X ( int, std:::string ) ;
+    } ;
+
+    class W
+    {
+        X wrapped_ ;
+
+        public:
+
+        W ( X const& x ) : wrapped_(x) {}
+    } ;
+
+    void foo()
+    {
+        // Temporary object created.
+        W ( X(123,"hello") ) ;
+    }
+
+A solution to this problem is to support direct construction of the
+contained object right in the container's storage.
+In this scheme, the user only needs to supply the arguments to the
+constructor to use in the wrapped object construction.
+
+    class W
+    {
+        X wrapped_ ;
+
+        public:
+
+        W ( X const& x ) : wrapped_(x) {}
+        W ( int a0, std::string a1) : wrapped_(a0,a1) {}
+    } ;
+
+    void foo()
+    {
+        // Wrapped object constructed in-place
+        // No temporary created.
+        W (123,"hello") ;
+    }
+
+A limitation of this method is that it doesn't scale well to wrapped
+objects with multiple constructors nor to generic code were the constructor
+overloads are unknown.
+
+The solution presented in this library is the family of [*InPlaceFactories]
+and [*TypedInPlaceFactories].
+These factories are a family of classes which encapsulate an increasing
+number of arbitrary constructor parameters and supply a method to construct
+an object of a given type using those parameters at an address specified by
+the user via placement new.
+
+For example, one member of this family looks like:
+
+    template<class T,class A0, class A1>
+    class TypedInPlaceFactory2
+    {
+        A0 m_a0 ; A1 m_a1 ;
+
+        public:
+
+        TypedInPlaceFactory2( A0 const& a0, A1 const& a1 ) : m_a0(a0), m_a1(a1) {}
+
+        void construct ( void* p ) { new (p) T(m_a0,m_a1) ; }
+     } ;
+
+A wrapper class aware of this can use it as:
+
+    class W
+    {
+        X wrapped_ ;
+
+        public:
+
+        W ( X const& x ) : wrapped_(x) {}
+        W ( TypedInPlaceFactory2 const& fac ) { fac.construct(&wrapped_) ; }
+    } ;
+
+    void foo()
+    {
+        // Wrapped object constructed in-place via a TypedInPlaceFactory.
+        // No temporary created.
+        W ( TypedInPlaceFactory2<X,int,std::string&rt(123,"hello")) ;
+    }
+
+The factories are divided in two groups:
+
+* [_TypedInPlaceFactories]: those which take the target type as a primary
+template parameter.
+* [_InPlaceFactories]: those with a template `construct(void*)` member
+function taking the target type.
+
+Within each group, all the family members differ only in the number of
+parameters allowed.
+
+This library provides an overloaded set of helper template functions to
+construct these factories without requiring unnecessary template parameters:
+
+    template<class A0,...,class AN>
+    InPlaceFactoryN <A0,...,AN> in_place ( A0 const& a0, ..., AN const& aN) ;
+
+    template<class T,class A0,...,class AN>
+    TypedInPlaceFactoryN <T,A0,...,AN> in_place ( T const& a0, A0 const& a0, ..., AN const& aN) ;
+
+In-place factories can be used generically by the wrapper and user as follows:
+
+    class W
+    {
+        X wrapped_ ;
+
+        public:
+
+        W ( X const& x ) : wrapped_(x) {}
+
+        template< class InPlaceFactory >
+        W ( InPlaceFactory const& fac ) { fac.template <X>construct(&wrapped_) ; }
+
+    } ;
+
+    void foo()
+    {
+        // Wrapped object constructed in-place via a InPlaceFactory.
+        // No temporary created.
+        W ( in_place(123,"hello") ) ;
+    }
+
+The factories are implemented in the headers: __IN_PLACE_FACTORY_HPP__ and __TYPED_IN_PLACE_FACTORY_HPP__
+
+[endsect]
+
+[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, `optional<>` provides an implicit conversion to `bool`. 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).
+
+[endsect]
+
+[section Exception Safety Guarantees]
+
+Because of the current implementation (see [link optional_implementation_notes Implementation Notes]), all of the assignment methods:
+
+* `optional<T>::operator= ( optional<T> const& )`
+* `optional<T>::operator= ( T const& )`
+* `template<class U> optional<T>::operator= ( optional<U> const& )`
+* `template<class InPlaceFactory> optional<T>::operator= ( InPlaceFactory const& )`
+* `template<class TypedInPlaceFactory> optional<T>::operator= ( TypedInPlaceFactory const& ) `
+* `optional<T>:::reset ( T const&)`
+
+Can only ['guarantee] the [_basic exception safety]: The lvalue optional is
+left [_uninitialized] if an exception is thrown (any previous value is ['first]
+destroyed using `T::~T()`)
+
+On the other hand, the ['uninitializing] methods:
+
+* `optional<T>::operator= ( detail::none_t )`
+* `optional<T>::reset()`
+
+Provide the no-throw guarantee (assuming a no-throw `T::~T()`)
+
+However, since `optional<>` itself doesn't throw any exceptions, the only
+source for exceptions here are `T`'s constructor, so if you know the exception
+guarantees for `T::T ( T const& )`, you know that `optional`'s assignment and
+reset has the same guarantees.
+
+    //
+    // Case 1: Exception thrown during assignment.
+    //
+    T v0(123);
+    optional<T> opt0(v0);
+    try
+    {
+        T v1(456);
+        optional<T> opt1(v1);
+        opt0 = opt1 ;
+
+        // If no exception was thrown, assignment succeeded.
+        assert( *opt0 == v1 ) ;
+    }
+    catch(...)
+    {
+        // If any exception was thrown, 'opt0' is reset to uninitialized.
+        assert( !opt0 ) ;
+    }
+
+    //
+    // Case 2: Exception thrown during reset(v)
+    //
+    T v0(123);
+    optional<T> opt(v0);
+    try
+    {
+        T v1(456);
+        opt.reset ( v1 ) ;
+
+        // If no exception was thrown, reset succeeded.
+        assert( *opt == v1 ) ;
+    }
+    catch(...)
+    {
+        // If any exception was thrown, 'opt' is reset to uninitialized.
+        assert( !opt ) ;
+    }
+
+[heading Swap]
+
+`void swap( optional<T>&, optional<T>& )` has the same exception guarantee
+as `swap(T&,T&)` when both optionals are initialized.
+If only one of the optionals is initialized, it gives the same ['basic]
+exception guarantee as `optional<T>::reset( T const& )` (since
+`optional<T>::reset()` doesn't throw).
+If none of the optionals is initialized, it has no-throw guarantee
+since it is a no-op.
+
+[endsect]
+
+[section Type requirements]
+
+In general, `T` must be __COPY_CONSTRUCTIBLE__ and have a no-throw destructor.
+The copy-constructible requirement is not needed if [*InPlaceFactories] are used.
+
+`T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__.
+
+[endsect]
+
+

include/boost/none.hpp

@@ -1,10 +1,10 @@
 // Copyright (C) 2003, Fernando Luis Cacciola Carballal.
 //
-// Use, modification, and distribution is subject to the Boost Software
-// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 //
-// See http://www.boost.org/lib/optional for documentation.
+// See http://www.boost.org/lib/optional/ for documentation.
 //
 // You are welcome to contact the author at:
 //  fernando_cacciola@hotmail.com
@@ -16,15 +16,12 @@
 
 // NOTE: Borland users have to include this header outside any precompiled headers
 // (bcc<=5.64 cannot include instance data in a precompiled header)
+//  -- * To be verified, now that there's no unnamed namespace
 
 namespace boost {
 
-namespace {
-
 none_t const none = ((none_t)0) ;
 
-}
-
 } // namespace boost
 
 #endif

include/boost/optional/optional.hpp

@@ -29,7 +29,9 @@
 #include "boost/none_t.hpp"
 #include "boost/utility/compare_pointees.hpp"
 
-#if BOOST_WORKAROUND(BOOST_MSVC, < 1300)
+#include "boost/optional/optional_fwd.hpp"
+
+#if BOOST_WORKAROUND(BOOST_MSVC, == 1200)
 // VC6.0 has the following bug:
 //   When a templated assignment operator exist, an implicit conversion
 //   constructing an optional<T> is used when assigment of the form:
@@ -64,7 +66,7 @@
 #endif
 
 #if !defined(BOOST_OPTIONAL_NO_INPLACE_FACTORY_SUPPORT) \
-    && BOOST_WORKAROUND(__BORLANDC__, <= 0x564)
+    && BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581) )
 // BCB (up to 5.64) has the following bug:
 //   If there is a member function/operator template of the form
 //     template<class Expr> mfunc( Expr expr ) ;
@@ -131,7 +133,11 @@ class optional_base : public optional_tag
 {
   private :
 
-    typedef BOOST_DEDUCED_TYPENAME detail::make_reference_content<T>::type internal_type ;
+    typedef
+#if !BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x564))
+    BOOST_DEDUCED_TYPENAME
+#endif 
+    ::boost::detail::make_reference_content<T>::type internal_type ;
 
     typedef aligned_storage<internal_type> storage_type ;
 
@@ -179,6 +185,16 @@ class optional_base : public optional_tag
     {
       construct(val);
     }
+    
+    // Creates an optional<T> initialized with 'val' IFF cond is true, otherwise creates an uninitialzed optional<T>.
+    // Can throw if T::T(T const&) does
+    optional_base ( bool cond, argument_type val )
+      :
+      m_initialized(false)
+    {
+      if ( cond )
+        construct(val);
+    }
 
     // Creates a deep copy of another optional<T>
     // Can throw if T::T(T const&) does
@@ -223,6 +239,23 @@ class optional_base : public optional_tag
       }
     }
 
+    // Assigns from another _convertible_ optional<U> (deep-copies the rhs value)
+    template<class U>
+    void assign ( optional<U> const& rhs )
+    {
+      if (is_initialized())
+      {
+        if ( rhs.is_initialized() )
+             assign_value(static_cast<value_type>(rhs.get()), is_reference_predicate() );
+        else destroy();
+      }
+      else
+      {
+        if ( rhs.is_initialized() )
+          construct(static_cast<value_type>(rhs.get()));
+      }
+    }
+
     // Assigns from a T (deep-copies the rhs value)
     void assign ( argument_type val )
     {
@@ -382,7 +415,7 @@ class optional_base : public optional_tag
     reference_const_type dereference( internal_type const* p, is_reference_tag     ) const { return p->get() ; }
     reference_type       dereference( internal_type*       p, is_reference_tag     )       { return p->get() ; }
 
-#if BOOST_WORKAROUND(__BORLANDC__, <= 0x564)
+#if BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x581))
     void destroy_impl ( is_not_reference_tag ) { get_ptr_impl()->internal_type::~internal_type() ; m_initialized = false ; }
 #else
     void destroy_impl ( is_not_reference_tag ) { get_ptr_impl()->T::~T() ; m_initialized = false ; }
@@ -432,6 +465,9 @@ class optional : public optional_detail::optional_base<T>
     // Can throw if T::T(T const&) does
     optional ( argument_type val ) : base(val) {}
 
+    // Creates an optional<T> initialized with 'val' IFF cond is true, otherwise creates an uninitialized optional.
+    // Can throw if T::T(T const&) does
+    optional ( bool cond, argument_type val ) : base(cond,val) {}
 
 #ifndef BOOST_OPTIONAL_NO_CONVERTING_COPY_CTOR
     // NOTE: MSVC needs templated versions first
@@ -481,6 +517,7 @@ class optional : public optional_detail::optional_base<T>
       }
 #endif
 
+
 #ifndef BOOST_OPTIONAL_NO_CONVERTING_ASSIGNMENT
     // Assigns from another convertible optional<U> (converts && deep-copies the rhs value)
     // Requires a valid conversion from U to T.
@@ -488,7 +525,7 @@ class optional : public optional_detail::optional_base<T>
     template<class U>
     optional& operator= ( optional<U> const& rhs )
       {
-        this->assign(rhs.get());
+        this->assign(rhs);
         return *this ;
       }
 #endif
@@ -525,6 +562,10 @@ class optional : public optional_detail::optional_base<T>
     reference_const_type get() const { BOOST_ASSERT(this->is_initialized()) ; return this->get_impl(); }
     reference_type       get()       { BOOST_ASSERT(this->is_initialized()) ; return this->get_impl(); }
 
+    // Returns a copy of the value if this is initialized, 'v' otherwise
+    reference_const_type get_value_or ( reference_const_type v ) const { return this->is_initialized() ? get() : v ; }
+    reference_type       get_value_or ( reference_type       v )       { return this->is_initialized() ? get() : v ; }
+    
     // Returns a pointer to the value if this is initialized, otherwise,
     // the behaviour is UNDEFINED
     // No-throw
@@ -546,6 +587,22 @@ class optional : public optional_detail::optional_base<T>
        bool operator!() const { return !this->is_initialized() ; }
 } ;
 
+// Returns optional<T>(v)
+template<class T> 
+inline 
+optional<T> make_optional ( T const& v  )
+{
+  return optional<T>(v);
+}
+
+// Returns optional<T>(cond,v)
+template<class T> 
+inline 
+optional<T> make_optional ( bool cond, T const& v )
+{
+  return optional<T>(cond,v);
+}
+
 // Returns a reference to the value if this is initialized, otherwise, the behaviour is UNDEFINED.
 // No-throw
 template<class T>
@@ -582,6 +639,24 @@ get ( optional<T>* opt )
   return opt->get_ptr() ;
 }
 
+// Returns a reference to the value if this is initialized, otherwise, the behaviour is UNDEFINED.
+// No-throw
+template<class T>
+inline
+BOOST_DEDUCED_TYPENAME optional<T>::reference_const_type
+get_optional_value_or ( optional<T> const& opt, BOOST_DEDUCED_TYPENAME optional<T>::reference_const_type v )
+{
+  return opt.get_value_or(v) ;
+}
+
+template<class T>
+inline
+BOOST_DEDUCED_TYPENAME optional<T>::reference_type
+get_optional_value_or ( optional<T>& opt, BOOST_DEDUCED_TYPENAME optional<T>::reference_type v )
+{
+  return opt.get_value_or(v) ;
+}
+
 // Returns a pointer to the value if this is initialized, otherwise, returns NULL.
 // No-throw
 template<class T>
@@ -743,6 +818,7 @@ template<class T> inline void swap ( optional<T>& x, optional<T>& y )
   optional_detail::optional_swap(x,y);
 }
 
+
 } // namespace boost
 
 #endif

include/boost/optional/optional_io.hpp

@@ -0,0 +1,84 @@
+// Copyright (C) 2005, Fernando Luis Cacciola Carballal.
+//
+// Use, modification, and distribution is subject to the Boost Software
+// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// See http://www.boost.org/lib/optional for documentation.
+//
+// You are welcome to contact the author at:
+//  fernando_cacciola@hotmail.com
+//
+#ifndef BOOST_OPTIONAL_OPTIONAL_IO_FLC_19NOV2002_HPP
+#define BOOST_OPTIONAL_OPTIONAL_IO_FLC_19NOV2002_HPP
+
+#if defined __GNUC__
+#  if (__GNUC__ == 2 && __GNUC_MINOR__ <= 97) 
+#    define BOOST_OPTIONAL_NO_TEMPLATED_STREAMS
+#  endif
+#endif // __GNUC__
+
+#if defined BOOST_OPTIONAL_NO_TEMPLATED_STREAMS
+#  include <iostream>
+#else 
+#  include <istream>
+#  include <ostream>
+#endif  
+
+
+#include "boost/optional/optional.hpp"
+#include "boost/utility/value_init.hpp"
+
+namespace boost
+{
+
+#if defined (BOOST_NO_TEMPLATED_STREAMS)
+template<class T>
+inline std::ostream& operator<<(std::ostream& out, optional<T> const& v)
+#else
+template<class CharType, class CharTrait, class T>
+inline
+std::basic_ostream<CharType, CharTrait>&
+operator<<(std::basic_ostream<CharType, CharTrait>& out, optional<T> const& v)
+#endif
+{
+  if ( out.good() )
+  {
+    if ( !v )
+         out << "--" ;
+    else out << ' ' << *v ;
+  }
+
+  return out;
+}
+
+#if defined (BOOST_NO_TEMPLATED_STREAMS)
+template<class T>
+inline std::istream& operator>>(std::istream& in, optional<T>& v)
+#else
+template<class CharType, class CharTrait, class T>
+inline
+std::basic_istream<CharType, CharTrait>&
+operator>>(std::basic_istream<CharType, CharTrait>& in, optional<T>& v)
+#endif
+{
+  if ( in.good() )
+  {
+    int d = in.get();
+    if ( d == ' ' )
+    {
+      T x ;
+      in >> x;
+      v = x ;
+    }
+    else
+      v = optional<T>() ;
+  }
+
+  return in;
+}
+
+} // namespace boost
+
+#endif
+

index.html

@@ -4,6 +4,10 @@
 </head>
 <body>
 Automatic redirection failed, please go to
-<a href="doc/optional.html">doc/optional.html</a>.
+<a href="doc/optional.html">doc/optional.html</a>.&nbsp;<hr>
+<p><EFBFBD> Copyright Beman Dawes, 2001</p>
+<p>Distributed under the Boost Software License, Version 1.0. (See accompanying 
+file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 
+at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
 </body>
 </html>

test/Jamfile

@@ -1,36 +0,0 @@
-# Boost.Optional Library test Jamfile
-#
-# Copyright (C) 2003, Fernando Luis Cacciola Carballal.
-#
-# Use, modification, and distribution is subject to the Boost Software
-# License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
-# http://www.boost.org/LICENSE_1_0.txt)
-#
-
-subproject libs/optional/test ;
-
-# bring in rules for testing
-SEARCH on testing.jam = $(BOOST_BUILD_PATH) ;
-include testing.jam ;
-
-# Make tests run by default.
-DEPENDS all : test ;
-
-{
-  test-suite optional :
-    [ run optional_test.cpp ]
-    [ run optional_test_tie.cpp ]
-    [ run optional_test_ref.cpp ]
-    [ run optional_test_inplace.cpp ]
-    [ compile-fail optional_test_fail1.cpp ]
-    [ compile-fail optional_test_fail2.cpp ]
-    [ compile-fail optional_test_fail3a.cpp ]
-    [ compile-fail optional_test_fail3b.cpp ]
-    [ compile-fail optional_test_ref_fail1.cpp ]
-    [ compile-fail optional_test_ref_fail2.cpp ]
-    [ compile-fail optional_test_ref_fail3.cpp ]
-    [ compile-fail optional_test_ref_fail4.cpp ]
-    [ compile-fail optional_test_inplace_fail.cpp ]
-    [ compile-fail optional_test_inplace_fail2.cpp ]
-  ;
-}

test/Jamfile.v2

@@ -20,6 +20,7 @@ import testing ;
     [ run optional_test_tie.cpp ]
     [ run optional_test_ref.cpp ]
     [ run optional_test_inplace.cpp ]
+    [ run optional_test_io.cpp ]
     [ compile-fail optional_test_fail1.cpp ]
     [ compile-fail optional_test_fail2.cpp ]
     [ compile-fail optional_test_fail3a.cpp ]

test/optional_test.cpp

@@ -15,7 +15,9 @@
 
 #define BOOST_ENABLE_ASSERT_HANDLER
 
-#include "boost/optional.hpp"
+#include "boost/bind/apply.hpp" // Included just to test proper interaction with boost::apply<> as reported by Daniel Wallin
+
+#include "boost/optional/optional.hpp"
 
 #ifdef __BORLANDC__
 #pragma hdrstop
@@ -115,12 +117,8 @@ void test_basics( T const* )
   // Assignment
   // T::operator= ( T const& x ) is used to copy new value.
   set_pending_assign( ARG(T) ) ;
-  set_pending_copy  ( ARG(T) ) ;
-  set_pending_dtor  ( ARG(T) ) ;
   oa = ob ;
   check_is_not_pending_assign( ARG(T) ) ;
-  check_is_pending_copy      ( ARG(T) ) ;
-  check_is_pending_dtor      ( ARG(T) ) ;
   check_initialized(oa);
   check_value(oa,b,z);
 
@@ -155,6 +153,95 @@ void test_basics( T const* )
   ob.reset();
   check_is_pending_dtor( ARG(T) ) ;
   check_uninitialized(ob);
+  
+}
+
+template<class T>
+void test_conditional_ctor_and_get_valur_or ( T const* )
+{
+  TRACE( std::endl << BOOST_CURRENT_FUNCTION  );
+  
+  T a(321);
+  
+  T z(123);
+  
+  optional<T> const cdef0(false,a);
+  
+  optional<T> def0(false,a);
+  optional<T> def1 = boost::make_optional(false,a); //  T is not within boost so ADL won't find make_optional unqualified
+  check_uninitialized(def0);
+  check_uninitialized(def1);
+
+  optional<T> const co0(true,a);
+  
+  optional<T> o0(true,a);
+  optional<T> o1 = boost::make_optional(true,a); //  T is not within boost so ADL won't find make_optional unqualified
+
+  check_initialized(o0);
+  check_initialized(o1);
+  check_value(o0,a,z);
+  check_value(o1,a,z);
+  
+  T b = def0.get_value_or(z);
+  BOOST_CHECK( b == z ) ;
+  
+  b = get_optional_value_or(def0,z);
+  BOOST_CHECK( b == z ) ;
+  
+  b = o0.get_value_or(z);
+  BOOST_CHECK( b == a ) ;
+
+  b = get_optional_value_or(o0,z);
+  BOOST_CHECK( b == a ) ;
+  
+  
+  T const& crz = z ;
+  T&        rz = z ;
+  
+  T const& crzz = def0.get_value_or(crz);
+  BOOST_CHECK( crzz == crz ) ;
+  
+  T& rzz = def0.get_value_or(rz);
+  BOOST_CHECK( rzz == rz ) ;
+  
+  T const& crzzz = get_optional_value_or(cdef0,crz);
+  BOOST_CHECK( crzzz == crz ) ;
+  
+  T& rzzz = get_optional_value_or(def0,rz);
+  BOOST_CHECK( rzzz == rz ) ;
+  
+  T const& crb = o0.get_value_or(crz);
+  BOOST_CHECK( crb == a ) ;
+  
+  T& rb = o0.get_value_or(rz);
+  BOOST_CHECK( rb == b ) ;
+  
+  T const& crbb = get_optional_value_or(co0,crz);
+  BOOST_CHECK( crbb == b ) ;
+  
+  T const& crbbb = get_optional_value_or(o0,crz);
+  BOOST_CHECK( crbbb == b ) ;
+  
+  T& rbb = get_optional_value_or(o0,rz);
+  BOOST_CHECK( rbb == b ) ;
+  
+  T& ra = a ;
+  
+  optional<T&> defref(false,ra);
+  BOOST_CHECK(!defref);
+  
+  optional<T&> ref(true,ra);
+  BOOST_CHECK(!!ref);
+  
+  a = T(432);
+  
+  BOOST_CHECK( *ref == a ) ;
+  
+  T& r1 = defref.get_value_or(z);
+  BOOST_CHECK( r1 == z ) ;
+  
+  T& r2 = ref.get_value_or(z);
+  BOOST_CHECK( r2 == a ) ;
 }
 
 //
@@ -692,6 +779,7 @@ void test_with_builtin_types()
   TRACE( std::endl << BOOST_CURRENT_FUNCTION   );
 
   test_basics( ARG(double) );
+  test_conditional_ctor_and_get_valur_or( ARG(double) );
   test_uninitialized_access( ARG(double) );
   test_no_throwing_swap( ARG(double) );
   test_relops( ARG(double) ) ;
@@ -703,6 +791,7 @@ void test_with_class_type()
   TRACE( std::endl << BOOST_CURRENT_FUNCTION   );
 
   test_basics( ARG(X) );
+  test_conditional_ctor_and_get_valur_or( ARG(X) );
   test_direct_value_manip( ARG(X) );
   test_uninitialized_access( ARG(X) );
   test_throwing_direct_init( ARG(X) );

test/optional_test_fail3b.cpp

@@ -13,14 +13,16 @@
 
 #include "boost/optional.hpp"
 
+struct A {} ;
+struct B {} ;
 //
 // THIS TEST SHOULD FAIL TO COMPILE
 //
 void test_no_unsupported_conversion()
 {
-  boost::optional<int> opt1(1) ;
-  boost::optional< std::string > opt2 ;
-  opt2 = opt1 ; // Cannot convert from "int" to "std::string"
+  boost::optional<A> opt1;
+  boost::optional<B> opt2;
+  opt2 = opt1 ; // Cannot convert from "A" to "B"
 }
 
 

test/optional_test_io.cpp

@@ -0,0 +1,89 @@
+// Copyright (C) 2003, Fernando Luis Cacciola Carballal.
+//
+// Use, modification, and distribution is subject to the Boost Software
+// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// See http://www.boost.org/lib/optional for documentation.
+//
+// You are welcome to contact the author at:
+//  fernando_cacciola@hotmail.com
+//
+#include<stdexcept>
+#include<string>
+#include<sstream>
+
+#define BOOST_ENABLE_ASSERT_HANDLER
+
+#include "boost/optional/optional.hpp"
+#include "boost/optional/optional_io.hpp"
+#include "boost/none.hpp"
+
+#include "boost/test/minimal.hpp"
+
+#ifdef ENABLE_TRACE
+#define TRACE(msg) std::cout << msg << std::endl ;
+#else
+#define TRACE(msg)
+#endif
+
+namespace boost {
+
+void assertion_failed (char const * expr, char const * func, char const * file, long )
+{
+  using std::string ;
+  string msg =  string("Boost assertion failure for \"")
+               + string(expr)
+               + string("\" at file \"")
+               + string(file)
+               + string("\" function \"")
+               + string(func)
+               + string("\"") ;
+
+  TRACE(msg);
+
+  throw std::logic_error(msg);
+}
+
+}
+
+using namespace std ;
+using namespace boost ;
+
+template<class Opt>
+void test2( Opt o, Opt buff )
+{
+  stringstream s ;
+
+  s << o ;
+  s >> buff ;
+
+  BOOST_ASSERT( buff == o ) ;
+}
+
+
+template<class T>
+void test( T v, T w )
+{
+  test2( make_optional(v), optional<T>  ());
+  test2( make_optional(v), make_optional(w));
+  test2( optional<T>  () , optional<T>  ());
+  test2( optional<T>  () , make_optional(w));
+}
+
+int test_main( int, char* [] )
+{
+  try
+  {
+    test(1,2);
+    test(string("hello"),string("buffer"));
+    test(string(""),string("buffer"));
+  }
+  catch ( ... )
+  {
+    BOOST_ERROR("Unexpected Exception caught!");
+  }
+
+  return 0;
+}
+