boostorg/optional
1
0
Fork 1
mirror of https://github.com/boostorg/optional.git synced 2025-07-15 21:32:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Reorganized docs. Minor code fix wrt opt refs

Browse Source
This commit is contained in:
Andrzej Krzemienski
2014-06-04 18:13:06 +02:00
parent f99618f09b
commit 3dd614fd91
47 changed files with 5607 additions and 856 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html Normal file
View File

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

423
doc/html/boost_optional/tutorial/design_overview.html Normal file
View File

@ -0,0 +1,423 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Design Overview</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="motivation.html" title="Motivation">
<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%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="motivation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.design_overview"></a><a class="link" href="design_overview.html" title="Design Overview">Design Overview</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="design_overview.html#boost_optional.tutorial.design_overview.the_models">The
models</a></span></dt>
<dt><span class="section"><a href="design_overview.html#boost_optional.tutorial.design_overview.the_semantics">The
semantics</a></span></dt>
<dt><span class="section"><a href="design_overview.html#boost_optional.tutorial.design_overview.the_interface">The
Interface</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_optional.tutorial.design_overview.the_models"></a><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_models" title="The models">The
models</a>
</h4></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>.
(cf. 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> (cf. 8.5/11).
<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;where <code class="computeroutput"><span class="identifier">nil_t</span></code>
is some stateless POD&#8212;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 precedent 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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
variant implies copies of the value.
</li>
<li class="listitem">
<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
between variants matches both current types and values
</li>
<li class="listitem">
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 class="listitem">
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 class="listitem">
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 class="listitem">
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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
container implies copies of the value.
</li>
<li class="listitem">
<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
between containers compare container size and if match, contained value
</li>
<li class="listitem">
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 class="listitem">
If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
optional.
</li>
<li class="listitem">
Testing if the container is empty models testing if the optional is
initialized
</li>
<li class="listitem">
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">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_optional.tutorial.design_overview.the_semantics"></a><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_semantics" title="The semantics">The
semantics</a>
</h4></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="bold"><strong>Default Construction:</strong></span> To introduce
a formally uninitialized wrapped object.
</li>
<li class="listitem">
<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 class="listitem">
<span class="bold"><strong>Deep Copy Construction:</strong></span> To obtain
a new yet equivalent wrapped object.
</li>
<li class="listitem">
<span class="bold"><strong>Direct Value Assignment (upon initialized):</strong></span>
To assign a value to the wrapped object.
</li>
<li class="listitem">
<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 class="listitem">
<span class="bold"><strong>Assignment (upon initialized):</strong></span> To
assign to the wrapped object the value of another wrapped object.
</li>
<li class="listitem">
<span class="bold"><strong>Assignment (upon uninitialized):</strong></span> To
initialize the wrapped object with value of another wrapped object.
</li>
<li class="listitem">
<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 class="listitem">
<span class="bold"><strong>Value access:</strong></span> To unwrap the wrapped
object.
</li>
<li class="listitem">
<span class="bold"><strong>Initialization state query:</strong></span> To determine
if the object is formally initialized or not.
</li>
<li class="listitem">
<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 class="listitem">
<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">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_optional.tutorial.design_overview.the_interface"></a><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_interface" title="The Interface">The
Interface</a>
</h4></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>
<h6>
<a name="boost_optional.tutorial.design_overview.the_interface.h0"></a>
<span class="phrase"><a name="boost_optional.tutorial.design_overview.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_"></a></span><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.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>
</h6>
<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 nonexistent
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 nonexistent) 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 contextual 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>
<h6>
<a name="boost_optional.tutorial.design_overview.the_interface.h1"></a>
<span class="phrase"><a name="boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee"></a></span><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional&lt;T&gt;
as a model of OptionalPointee</a>
</h6>
<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="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><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></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"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="motivation.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

175
doc/html/boost_optional/tutorial/exception_safety_guarantees.html Normal file
View File

@ -0,0 +1,175 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Exception Safety Guarantees</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="a_note_about_optional_bool_.html" title="A note about optional&lt;bool&gt;">
<link rel="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%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.exception_safety_guarantees"></a><a class="link" href="exception_safety_guarantees.html" title="Exception Safety Guarantees">Exception
Safety Guarantees</a>
</h3></div></div></div>
<p>
This library assumes that <code class="computeroutput"><span class="identifier">T</span></code>'s
destructor does not throw exceptions. If it does, the behaviour of many operations
on <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
undefined.
</p>
<p>
The following mutating operations never throw exceptions:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<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">none_t</span>
<span class="special">)</span> <span class="keyword">noexcept</span></code>
</li>
<li class="listitem">
<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="keyword">noexcept</span></code>
</li>
</ul></div>
<p>
In addition, the following constructors and the destructor never throw exceptions:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<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">optional</span><span class="special">()</span>
<span class="keyword">noexcept</span></code>
</li>
<li class="listitem">
<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">optional</span><span class="special">(</span>
<span class="identifier">none_t</span> <span class="special">)</span>
<span class="keyword">noexcept</span></code>
</li>
</ul></div>
<p>
Regarding the following assignment functions:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<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 class="listitem">
<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 class="listitem">
<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 class="listitem">
<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 class="listitem">
<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 class="listitem">
<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>
</li>
</ul></div>
<p>
They forward calls to the corresponding <code class="computeroutput"><span class="identifier">T</span></code>'s
constructors or assignments (depending on whether the optional object is
initialized or not); so if both <code class="computeroutput"><span class="identifier">T</span></code>'s
constructor and the assignment provide strong exception safety guarantee,
<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
assignment also provides strong exception safety guarantee; otherwise we
only get the basic guarantee. Additionally, if both involved <code class="computeroutput"><span class="identifier">T</span></code>'s constructor and the assignment never
throw, <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
assignment also never throws.
</p>
<p>
Unless <code class="computeroutput"><span class="identifier">T</span></code>'s constructor or
assignment throws, assignments to <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
do not throw anything else on its own. A throw during assignment never changes
the initialization state of any optional object involved:
</p>
<pre class="programlisting"><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">val1</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">opt2</span><span class="special">(</span><span class="identifier">val2</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span>
<span class="keyword">try</span>
<span class="special">{</span>
<span class="identifier">opt1</span> <span class="special">=</span> <span class="identifier">opt2</span><span class="special">;</span> <span class="comment">// throws</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(...)</span>
<span class="special">{</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
This also applies to move assignments/constructors. However, move operations
are made no-throw more often.
</p>
<p>
Operation <code class="computeroutput"><span class="identifier">emplace</span></code> provides
basic exception safety guarantee. If it throws, the optional object becomes
uninitialized regardless of its initial state, and its previous contained
value (if any) is destroyed. It doesn't call any assignment or move/copy
constructor on <code class="computeroutput"><span class="identifier">T</span></code>.
</p>
<h5>
<a name="boost_optional.tutorial.exception_safety_guarantees.h0"></a>
<span class="phrase"><a name="boost_optional.tutorial.exception_safety_guarantees.swap"></a></span><a class="link" href="exception_safety_guarantees.html#boost_optional.tutorial.exception_safety_guarantees.swap">Swap</a>
</h5>
<p>
Unless <code class="computeroutput"><span class="identifier">swap</span></code> on optional is
customized, its primary implementation forwards calls to <code class="computeroutput"><span class="identifier">T</span></code>'s
<code class="computeroutput"><span class="identifier">swap</span></code> or move constructor
(depending on the initialization state of the optional objects). Thus, if
both <code class="computeroutput"><span class="identifier">T</span></code>'s <code class="computeroutput"><span class="identifier">swap</span></code>
and move constructor never throw, <code class="computeroutput"><span class="identifier">swap</span></code>
on <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> never
throws. similarly, if both <code class="computeroutput"><span class="identifier">T</span></code>'s
<code class="computeroutput"><span class="identifier">swap</span></code> and move constructor
offer strong guarantee, <code class="computeroutput"><span class="identifier">swap</span></code>
on <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> also
offers a strong guarantee.
</p>
<p>
In case <code class="computeroutput"><span class="identifier">swap</span></code> on optional
is customized, the call to <code class="computeroutput"><span class="identifier">T</span></code>'s
move constructor are replaced with the calls to <code class="computeroutput"><span class="identifier">T</span></code>'s
default constructor followed by <code class="computeroutput"><span class="identifier">swap</span></code>.
(This is more useful on older compilers that do not support move semantics,
when one wants to acheive stronger exception safety guarantees.) In this
case the exception safety guarantees for <code class="computeroutput"><span class="identifier">swap</span></code>
are reliant on the guarantees of <code class="computeroutput"><span class="identifier">T</span></code>'s
<code class="computeroutput"><span class="identifier">swap</span></code> and default constructor
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

197
doc/html/boost_optional/tutorial/in_place_factories.html Normal file
View File

@ -0,0 +1,197 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>In-Place Factories</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<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%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.in_place_factories"></a><a class="link" href="in_place_factories.html" title="In-Place Factories">In-Place
Factories</a>
</h3></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">&gt;(</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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="underline">TypedInPlaceFactories</span>: those which
take the target type as a primary template parameter.
</li>
<li class="listitem">
<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"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

129
doc/html/boost_optional/tutorial/motivation.html Normal file
View File

@ -0,0 +1,129 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Motivation</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="../../optional/tutorial.html" title="Tutorial">
<link rel="next" href="design_overview.html" title="Design Overview">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.motivation"></a><a class="link" href="motivation.html" title="Motivation">Motivation</a>
</h3></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
(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 class="listitem">
(B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
</li>
<li class="listitem">
(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 nonexistent
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>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

115
doc/html/boost_optional/tutorial/optional_references.html Normal file
View File

@ -0,0 +1,115 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Optional references</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="design_overview.html" title="Design Overview">
<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%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="design_overview.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.optional_references"></a><a class="link" href="optional_references.html" title="Optional references">Optional
references</a>
</h3></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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Converting constructors
</li>
<li class="listitem">
Converting assignment
</li>
<li class="listitem">
InPlace construction
</li>
<li class="listitem">
InPlace assignment
</li>
<li class="listitem">
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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
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 refer
to the same object.
</li>
<li class="listitem">
Value-access will actually provide access to the referenced object rather
than the reference itself.
</li>
</ul></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
On compilers that do not conform to Standard C++ rules of reference binding,
operations on optional references might give adverse results: rather than
binding a reference to a designated object they may create an unexpected
temporary and bind to it. For more details see <a class="link" href="../dependencies_and_portability/optional_reference_binding.html" title="Optional Reference Binding">Dependencies
and Portability section</a>.
</p></td></tr>
</table></div>
<h5>
<a name="boost_optional.tutorial.optional_references.h0"></a>
<span class="phrase"><a name="boost_optional.tutorial.optional_references.rvalue_references"></a></span><a class="link" href="optional_references.html#boost_optional.tutorial.optional_references.rvalue_references">Rvalue
references</a>
</h5>
<p>
Rvalue references and lvalue references to const have the ability in C++
to extend the life time of a temporary they bind to. Optional references
do not have this capability, therefore to avoid surprising effects it is
not possible to initialize an optional references from a temporary. Optional
rvalue references are disabled altogether. Also, the initialization and assignment
of an optional reference to const from rvalue reference is disabled.
</p>
<pre class="programlisting"><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="comment">// legal</span>
<span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">int</span><span class="special">&amp;&gt;</span> <span class="identifier">oi</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="comment">// illegal</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="design_overview.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

149
doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html Normal file
View File

@ -0,0 +1,149 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Rebinding semantics for assignment of optional references</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<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%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references"></a><a class="link" 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>
</h3></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; its 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>
<h5>
<a name="boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references.h0"></a>
<span class="phrase"><a name="boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references.rationale"></a></span><a class="link" href="rebinding_semantics_for_assignment_of_optional_references.html#boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references.rationale">Rationale</a>
</h5>
<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 consistent.
</p>
<p>
If in your code rebinding to another object is not an option, then it is
very likely that binding for the first 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 a scenario it is a
precondition that the lvalue must be already initialized. If it isn't, then
binding for the first time is OK while rebinding is not which is IMO very
unlikely. In such a 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"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="optional_references.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

61
doc/html/boost_optional/tutorial/type_requirements.html Normal file
View File

@ -0,0 +1,61 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Type requirements</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="exception_safety_guarantees.html" title="Exception Safety Guarantees">
<link rel="next" href="../../optional/reference.html" title="Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="exception_safety_guarantees.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.type_requirements"></a><a class="link" href="type_requirements.html" title="Type requirements">Type requirements</a>
</h3></div></div></div>
<p>
At the very minimum for <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
to work with a minimum interface it is required that <code class="computeroutput"><span class="identifier">T</span></code>
has a publicly accessible no-throw destructor. In that case you need to initialize
the optional object with function <code class="computeroutput"><span class="identifier">emplace</span><span class="special">()</span></code> or use <span class="bold"><strong>InPlaceFactories</strong></span>.
Additionally, if <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">Moveable</span></code>, <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 also <code class="computeroutput"><span class="identifier">Moveable</span></code> and can
be easily initialized from an rvalue of type <code class="computeroutput"><span class="identifier">T</span></code>
and be passed by value. Additionally, if <code class="computeroutput"><span class="identifier">T</span></code>
is <code class="computeroutput"><span class="identifier">Copyable</span></code>, <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
also <code class="computeroutput"><span class="identifier">Copyable</span></code> and can be
easily initialized from an lvalue of type <code class="computeroutput"><span class="identifier">T</span></code>.
</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"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="exception_safety_guarantees.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>