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

docs -- expanded tutprial section

Browse Source
This commit is contained in:
Andrzej Krzemienski
2014-06-08 16:23:35 +02:00
parent d25b0cfd59
commit befd3970d7
14 changed files with 353 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
doc/00_optional.qbk
View File

@ -23,6 +23,7 @@ Distributed under the Boost Software License, Version 1.0.
[/ Cited Boost resources ]
[def __BOOST_VARIANT__ [@../../../variant/index.html Boost.Variant]]
[def __BOOST_TUPLE__ [@../../../tuple/index.html Boost.Tuple]]
[def __BOOST_TRIBOOL__ [@../../../../doc/html/tribool.html boost::tribool]]
[def __OPTIONAL_POINTEE__ [@../../../utility/OptionalPointee.html OptionalPointee]]
@ -37,6 +38,8 @@ Distributed under the Boost Software License, Version 1.0.
[def __HASKELL__ [@http://www.haskell.org/ Haskell]]
[def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html `DefaultConstructible`]]
[def __SGI_LESS_THAN_COMPARABLE__ [@http://www.sgi.com/tech/stl/LessThanComparable.html `LessThanComparable`]]
[def __SGI_EQUALITY_COMPARABLE__ [@http://www.sgi.com/tech/stl/EqualityComparable.html `EqualityComparable`]]
[/ Icons ]
@ -71,8 +74,10 @@ This is how you solve it with `boost::optional`:
[include 01_quick_start.qbk]
[section Tutorial]
[include 12_motivation.qbk]
[include 13_development.qbk]
[include 10_motivation.qbk]
[include 11_development.qbk]
[include 12_when_to_use.qbk]
[include 13_relational_operators.qbk]
[include 14_optional_references.qbk]
[include 15_in_place_factories.qbk]
[include 16_optional_bool.qbk]

4
doc/01_quick_start.qbk
View File

@ -119,7 +119,7 @@ In other place we want to use the result of `getPeriod`, but want the two dates
Date begin, end; // Error: no default ctor!
boost::tie(begin, end) = getPeriod();
The second line works already, this is the capability of Boost.Tuple library, but the first line won't work. We could set some invented initial dates, but it is confusing and may be an unacceptable cost, given that these values will be overwritten in the next line anyway. This is where `optional` can help:
The second line works already, this is the capability of __BOOST_TUPLE__ library, but the first line won't work. We could set some invented initial dates, but it is confusing and may be an unacceptable cost, given that these values will be overwritten in the next line anyway. This is where `optional` can help:
boost::optional<Date> begin, end;
boost::tie(begin, end) = getPeriod();
@ -138,7 +138,7 @@ Suppose you want to ask users to choose some number (an `int`). One of the valid
++choices[choice];
}
This works because `optional<T>` is `LessThanComparable` whenever `T` is `LessThanComparable`. In this case the state of being uninitialized is treated as a yet another value of `T`, which is compared less than any value of `T`. So the set of values that type `optional<T>` can assume is {`boost::none`, -2147483648, -2147483647, ..., -1, 0, 1, ..., 2147483647} (assuming a 32-bit `int`).
This works because `optional<T>` is __SGI_LESS_THAN_COMPARABLE__ whenever `T` is __SGI_LESS_THAN_COMPARABLE__. In this case the state of being uninitialized is treated as a yet another value of `T`, which is compared less than any value of `T`.
[endsect]
[endsect]

0
doc/12_motivation.qbk → doc/10_motivation.qbk
View File

0
doc/13_development.qbk → doc/11_development.qbk
View File

37
doc/12_when_to_use.qbk Normal file
View File

@ -0,0 +1,37 @@

[section When to use Optional]
It is recommended to use `optional<T>` in situations where there is exactly one, clear (to all parties) reason for having no value of type `T`, and where the lack of value is as natural as having any regular value of `T`. One example of such situation is asking the user in some GUI form to optionally specify some limit on an `int` value, but the user is allowed to say 'I want the number not to be constrained by the maximum'.
For another example, consider a config parameter specifying how many threads the application should launch. Leaving this parameter unspecified means that the application should decide itself. For yet another example, consider a function returning the index of the smallest element in a `vector`. We need to be prepared for the situation, where the `vector` is empty. Therefore a natural signature for such function would be:
template <typename T>
optional<size_t> find_smallest_elem(const std::vector<T>& vec);
Here, having received an empty `vec` and having no `size_t` to return is not a ['failure] but a ['normal], albeit irregular, situation.
Another typical situation is to indicate that we do not have a value yet, but we expect to have it later. This notion can be used in implementing solutions like lazy initialization or a two-phase initialization.
`optional` can be used to take a non-__SGI_DEFAULT_CONSTRUCTIBLE__ type `T` and create a sibling type with a default constructor. This is a way to add a ['null-state] to any type that doesn't have it already.
Sometimes type `T` already provides a built-in null-state, but it may still be useful to wrap it into `optional`. Consider `std::string`. When you read a piece of text from a GUI form or a DB table, it is hardly ever that the empty string indicates anything else but a missing text. And some data bases do not even distinguish between a null string entry and a non-null string of length 0. Still, it may be practical to use `optional<string>` to indicate in the returned type that we want to treat the empty string in a special dedicated program path:
if(boost::optional<std::string> name = ask_user_name()) {
assert(*name != "");
logon_as(*name);
}
else {
skip_logon();
}
In the example above, the assertion indicates that if we choose to use this technique, we must translate the empty string state to an optional object with no contained value (inside function `ask_user_name`).
[heading Not recommended usages]
It is not recommended to use `optional` to indicate that we were not able to compute a value because of a ['failure]. It is difficult to define what a failure is, but it usually has one common characteristic: an associated information on the cause of the failure. This can be the type and member data of an exception object, or an error code. It is a bad design to signal a failure and not inform about the cause. If you do not want to use exceptions, and do not like the fact that by returning error codes you cannot return the computed value, you can use [@https://github.com/ptal/Boost.Expected Expected] library. It is sort of __BOOST_VARIANT__ that contains either a computed value or a reason why the computation failed.
Sometimes the distinction into what is a failure and what is a valid but irregular result is blurry and depends on a particular usage and personal preference. Consider a function that converts a `string` to an `int`. Is it a failure that you cannot convert? It might in some cases, but in other you may call it exactly for the purpose of figuring out if a given `string` is convertible, and you are not even interested in the resulting value. Sometimes when a conversion fails you may not consider it a failure, but you need to know why it cannot be converted; for instance at which character it is determined that the conversion is impossible. In this case returning `optional<T>` will not suffice. Finally, there is a use case where an input string that does not represent an `int` is not a failure condition, but during the conversion we use resources whose acquisition may fail. In that case the natural representation is to both return `optional<int>` and signal failure:
optional<int> convert1(const string& str); // throws
expected<ErrorT, optional<int>> convert2(const string& str); // return either optional or error
[endsect]

35
doc/13_relational_operators.qbk Normal file
View File

@ -0,0 +1,35 @@

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

8
doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html
View File

@ -44,10 +44,10 @@
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">tie</span><span class="special">(</span><span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">getPeriod</span><span class="special">();</span>
</pre>
<p>
The second line works already, this is the capability of Boost.Tuple library,
but the first line won't work. We could set some invented initial dates,
but it is confusing and may be an unacceptable cost, given that these values
will be overwritten in the next line anyway. This is where <code class="computeroutput"><span class="identifier">optional</span></code> can help:
The second line works already, this is the capability of <a href="../../../../../tuple/index.html" target="_top">Boost.Tuple</a>
library, but the first line won't work. We could set some invented initial
dates, but it is confusing and may be an unacceptable cost, given that these
values will be overwritten in the next line anyway. This is where <code class="computeroutput"><span class="identifier">optional</span></code> can help:
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Date</span><span class="special">&gt;</span> <span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">tie</span><span class="special">(</span><span class="identifier">begin</span><span class="special">,</span> <span class="identifier">end</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">getPeriod</span><span class="special">();</span>

11
doc/html/boost_optional/quick_start/storage_in_containers.html
View File

@ -43,14 +43,9 @@
</pre>
<p>
This works because <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 <code class="computeroutput"><span class="identifier">LessThanComparable</span></code> whenever
<code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="identifier">LessThanComparable</span></code>.
In this case the state of being uninitialized is treated as a yet another
value of <code class="computeroutput"><span class="identifier">T</span></code>, which is compared
less than any value of <code class="computeroutput"><span class="identifier">T</span></code>.
So the set of values that 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>
can assume is {<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code>, -2147483648, -2147483647, ..., -1,
0, 1, ..., 2147483647} (assuming a 32-bit <code class="computeroutput"><span class="keyword">int</span></code>).
is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a> whenever <code class="computeroutput"><span class="identifier">T</span></code> is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a>. In this case
the state of being uninitialized is treated as a yet another value of <code class="computeroutput"><span class="identifier">T</span></code>, which is compared less than any value
of <code class="computeroutput"><span class="identifier">T</span></code>.
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>

6
doc/html/boost_optional/tutorial/design_overview/the_interface.html
View File

@ -7,7 +7,7 @@
<link rel="home" href="../../../index.html" title="Boost.Optional">
<link rel="up" href="../design_overview.html" title="Design Overview">
<link rel="prev" href="the_semantics.html" title="The semantics">
<link rel="next" href="../optional_references.html" title="Optional references">
<link rel="next" href="../when_to_use_optional.html" title="When to use Optional">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="the_semantics.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_overview.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>
<a accesskey="p" href="the_semantics.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_overview.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="../when_to_use_optional.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
@ -180,7 +180,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="the_semantics.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_overview.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>
<a accesskey="p" href="the_semantics.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_overview.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="../when_to_use_optional.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

6
doc/html/boost_optional/tutorial/optional_references.html
View File

@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="design_overview/the_interface.html" title="The Interface">
<link rel="prev" href="relational_operators.html" title="Relational operators">
<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">
@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="design_overview/the_interface.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>
<a accesskey="p" href="relational_operators.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">
@ -109,7 +109,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="design_overview/the_interface.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>
<a accesskey="p" href="relational_operators.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>

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

@ -0,0 +1,108 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Relational operators</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="when_to_use_optional.html" title="When to use Optional">
<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="when_to_use_optional.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.relational_operators"></a><a class="link" href="relational_operators.html" title="Relational operators">Relational
operators</a>
</h3></div></div></div>
<p>
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> is
<a href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top"><code class="computeroutput"><span class="identifier">EqualityComparable</span></code></a> whenever <code class="computeroutput"><span class="identifier">T</span></code> is <a href="http://www.sgi.com/tech/stl/EqualityComparable.html" target="_top"><code class="computeroutput"><span class="identifier">EqualityComparable</span></code></a>. Two optional
objects containing a value compare in the same as their contained values.
The uninitialized state 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>
is treated as a distinct value, equal to itself, and unequal to any value
of type <code class="computeroutput"><span class="identifier">T</span></code>:
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">oN</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">o0</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">o1</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">oN</span> <span class="special">!=</span> <span class="identifier">o0</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o1</span> <span class="special">!=</span> <span class="identifier">oN</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o2</span> <span class="special">!=</span> <span class="identifier">o1</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">oN</span> <span class="special">==</span> <span class="identifier">oN</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o0</span> <span class="special">==</span> <span class="identifier">o0</span><span class="special">);</span>
</pre>
<p>
The converting constructor from <code class="computeroutput"><span class="identifier">T</span></code>
as well as from <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code> implies the existence and semantics
of the mixed comparison between <code class="computeroutput"><span class="identifier">T</span></code>
and <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code> as
well as between <code class="computeroutput"><span class="identifier">none_t</span></code> and
<code class="computeroutput"><span class="identifier">optionl</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>:
</p>
<pre class="programlisting"><span class="identifier">assert</span><span class="special">(</span><span class="identifier">oN</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o1</span> <span class="special">!=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o2</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">oN</span> <span class="special">==</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">);</span>
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">o0</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
</pre>
<p>
This mixed comparison has a practical interpretation, which is occasionally
useful:
</p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">choice</span> <span class="special">=</span> <span class="identifier">ask_user</span><span class="special">();</span>
<span class="keyword">if</span> <span class="special">(</span><span class="identifier">choice</span> <span class="special">==</span> <span class="number">2</span><span class="special">)</span>
<span class="identifier">start_procedure_2</span><span class="special">();</span>
</pre>
<p>
In the above example, the meaning of the comparison is 'user chose number
2'. If user chose nothing, he didn't choose number 2.
</p>
<p>
In a similar manner, 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>
is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a> whenever <code class="computeroutput"><span class="identifier">T</span></code> is <a href="http://www.sgi.com/tech/stl/LessThanComparable.html" target="_top"><code class="computeroutput"><span class="identifier">LessThanComparable</span></code></a>. The optional
object containing no value is compared less than any value of <code class="computeroutput"><span class="identifier">T</span></code>. To illustrate this, if the default ordering
of <code class="computeroutput"><span class="identifier">size_t</span></code> is {<code class="computeroutput"><span class="number">0</span></code>, <code class="computeroutput"><span class="number">1</span></code>,
<code class="computeroutput"><span class="number">2</span></code>, ...}, the default ordering
of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">size_t</span><span class="special">&gt;</span></code>
is {<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code>, <code class="computeroutput"><span class="number">0</span></code>,
<code class="computeroutput"><span class="number">1</span></code>, <code class="computeroutput"><span class="number">2</span></code>,
...}. This order does not have a practical interpretation. The goal is to
have any semantically correct default ordering in order 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
be usable in ordered associative containers (wherever <code class="computeroutput"><span class="identifier">T</span></code>
is usable).
</p>
<p>
Mixed relational operators are the only case where the contained value of
an optional object can be inspected without the usage of value accessing
function (<code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code>,
<code class="computeroutput"><span class="identifier">value</span></code>, <code class="computeroutput"><span class="identifier">value_or</span></code>).
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><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="when_to_use_optional.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>

142
doc/html/boost_optional/tutorial/when_to_use_optional.html Normal file
View File

@ -0,0 +1,142 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>When to use Optional</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="design_overview/the_interface.html" title="The Interface">
<link rel="next" href="relational_operators.html" title="Relational operators">
</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/the_interface.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="relational_operators.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.when_to_use_optional"></a><a class="link" href="when_to_use_optional.html" title="When to use Optional">When to
use Optional</a>
</h3></div></div></div>
<p>
It is recommended to use <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
in situations where there is exactly one, clear (to all parties) reason for
having no value of type <code class="computeroutput"><span class="identifier">T</span></code>,
and where the lack of value is as natural as having any regular value of
<code class="computeroutput"><span class="identifier">T</span></code>. One example of such situation
is asking the user in some GUI form to optionally specify some limit on an
<code class="computeroutput"><span class="keyword">int</span></code> value, but the user is allowed
to say 'I want the number not to be constrained by the maximum'. For another
example, consider a config parameter specifying how many threads the application
should launch. Leaving this parameter unspecified means that the application
should decide itself. For yet another example, consider a function returning
the index of the smallest element in a <code class="computeroutput"><span class="identifier">vector</span></code>.
We need to be prepared for the situation, where the <code class="computeroutput"><span class="identifier">vector</span></code>
is empty. Therefore a natural signature for such function would be:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">size_t</span><span class="special">&gt;</span> <span class="identifier">find_smallest_elem</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">vec</span><span class="special">);</span>
</pre>
<p>
Here, having received an empty <code class="computeroutput"><span class="identifier">vec</span></code>
and having no <code class="computeroutput"><span class="identifier">size_t</span></code> to return
is not a <span class="emphasis"><em>failure</em></span> but a <span class="emphasis"><em>normal</em></span>,
albeit irregular, situation.
</p>
<p>
Another typical situation is to indicate that we do not have a value yet,
but we expect to have it later. This notion can be used in implementing solutions
like lazy initialization or a two-phase initialization.
</p>
<p>
<code class="computeroutput"><span class="identifier">optional</span></code> can be used to take
a non-<a href="http://www.sgi.com/tech/stl/DefaultConstructible.html" target="_top"><code class="computeroutput"><span class="identifier">DefaultConstructible</span></code></a> type <code class="computeroutput"><span class="identifier">T</span></code> and create a sibling type with a default
constructor. This is a way to add a <span class="emphasis"><em>null-state</em></span> to any
type that doesn't have it already.
</p>
<p>
Sometimes type <code class="computeroutput"><span class="identifier">T</span></code> already
provides a built-in null-state, but it may still be useful to wrap it into
<code class="computeroutput"><span class="identifier">optional</span></code>. Consider <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>.
When you read a piece of text from a GUI form or a DB table, it is hardly
ever that the empty string indicates anything else but a missing text. And
some data bases do not even distinguish between a null string entry and a
non-null string of length 0. Still, it may be practical to use <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span></code>
to indicate in the returned type that we want to treat the empty string in
a special dedicated program path:
</p>
<pre class="programlisting"><span class="keyword">if</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">name</span> <span class="special">=</span> <span class="identifier">ask_user_name</span><span class="special">())</span> <span class="special">{</span>
<span class="identifier">assert</span><span class="special">(*</span><span class="identifier">name</span> <span class="special">!=</span> <span class="string">""</span><span class="special">);</span>
<span class="identifier">logon_as</span><span class="special">(*</span><span class="identifier">name</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">else</span> <span class="special">{</span>
<span class="identifier">skip_logon</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<p>
In the example above, the assertion indicates that if we choose to use this
technique, we must translate the empty string state to an optional object
with no contained value (inside function <code class="computeroutput"><span class="identifier">ask_user_name</span></code>).
</p>
<h5>
<a name="boost_optional.tutorial.when_to_use_optional.h0"></a>
<span class="phrase"><a name="boost_optional.tutorial.when_to_use_optional.not_recommended_usages"></a></span><a class="link" href="when_to_use_optional.html#boost_optional.tutorial.when_to_use_optional.not_recommended_usages">Not
recommended usages</a>
</h5>
<p>
It is not recommended to use <code class="computeroutput"><span class="identifier">optional</span></code>
to indicate that we were not able to compute a value because of a <span class="emphasis"><em>failure</em></span>.
It is difficult to define what a failure is, but it usually has one common
characteristic: an associated information on the cause of the failure. This
can be the type and member data of an exception object, or an error code.
It is a bad design to signal a failure and not inform about the cause. If
you do not want to use exceptions, and do not like the fact that by returning
error codes you cannot return the computed value, you can use <a href="https://github.com/ptal/Boost.Expected" target="_top">Expected</a>
library. It is sort of <a href="../../../../../variant/index.html" target="_top">Boost.Variant</a>
that contains either a computed value or a reason why the computation failed.
</p>
<p>
Sometimes the distinction into what is a failure and what is a valid but
irregular result is blurry and depends on a particular usage and personal
preference. Consider a function that converts a <code class="computeroutput"><span class="identifier">string</span></code>
to an <code class="computeroutput"><span class="keyword">int</span></code>. Is it a failure that
you cannot convert? It might in some cases, but in other you may call it
exactly for the purpose of figuring out if a given <code class="computeroutput"><span class="identifier">string</span></code>
is convertible, and you are not even interested in the resulting value. Sometimes
when a conversion fails you may not consider it a failure, but you need to
know why it cannot be converted; for instance at which character it is determined
that the conversion is impossible. In this case returning <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
will not suffice. Finally, there is a use case where an input string that
does not represent an <code class="computeroutput"><span class="keyword">int</span></code> is
not a failure condition, but during the conversion we use resources whose
acquisition may fail. In that case the natural representation is to both
return <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code> and
signal failure:
</p>
<pre class="programlisting"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">convert1</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">str</span><span class="special">);</span> <span class="comment">// throws</span>
<span class="identifier">expected</span><span class="special">&lt;</span><span class="identifier">ErrorT</span><span class="special">,</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;&gt;</span> <span class="identifier">convert2</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">str</span><span class="special">);</span> <span class="comment">// return either optional or error</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/the_interface.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="relational_operators.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

6
doc/html/index.html
View File

@ -55,6 +55,10 @@
<dd><dl>
<dt><span class="section"><a href="optional/tutorial.html#boost_optional.tutorial.motivation">Motivation</a></span></dt>
<dt><span class="section"><a href="boost_optional/tutorial/design_overview.html">Design Overview</a></span></dt>
<dt><span class="section"><a href="boost_optional/tutorial/when_to_use_optional.html">When to
use Optional</a></span></dt>
<dt><span class="section"><a href="boost_optional/tutorial/relational_operators.html">Relational
operators</a></span></dt>
<dt><span class="section"><a href="boost_optional/tutorial/optional_references.html">Optional
references</a></span></dt>
<dt><span class="section"><a href="boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html">Rebinding
@ -129,7 +133,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: June 06, 2014 at 21:50:26 GMT</small></p></td>
<td align="left"><p><small>Last revised: June 08, 2014 at 14:17:56 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

4
doc/html/optional/tutorial.html
View File

@ -29,6 +29,10 @@
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.motivation">Motivation</a></span></dt>
<dt><span class="section"><a href="../boost_optional/tutorial/design_overview.html">Design Overview</a></span></dt>
<dt><span class="section"><a href="../boost_optional/tutorial/when_to_use_optional.html">When to
use Optional</a></span></dt>
<dt><span class="section"><a href="../boost_optional/tutorial/relational_operators.html">Relational
operators</a></span></dt>
<dt><span class="section"><a href="../boost_optional/tutorial/optional_references.html">Optional
references</a></span></dt>
<dt><span class="section"><a href="../boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html">Rebinding