libs/optional/doc/html/boost_optional/tutorial.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Tutorial</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Optional">
   9 <link rel="prev" href="quick_start.html" title="Quick Start">
  10 <link rel="next" href="synopsis.html" title="Synopsis">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="quick_start.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="synopsis.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="boost_optional.tutorial"></a><a class="link" href="tutorial.html" title="Tutorial">Tutorial</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.motivation">Motivation</a></span></dt>
  31 <dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.design_overview">Design Overview</a></span></dt>
  32 </dl></div>
  33 <div class="section">
  34 <div class="titlepage"><div><div><h3 class="title">
  35 <a name="boost_optional.tutorial.motivation"></a><a class="link" href="tutorial.html#boost_optional.tutorial.motivation" title="Motivation">Motivation</a>
  36 </h3></div></div></div>
  37 <p>
  38         Consider these functions which should return a value but which might not
  39         have a value to return:
  40       </p>
  41 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  42 <li class="listitem">
  43             (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>
  44           </li>
  45 <li class="listitem">
  46             (B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
  47           </li>
  48 <li class="listitem">
  49             (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>
  50           </li>
  51 </ul></div>
  52 <p>
  53         There are different approaches to the issue of not having a value to return.
  54       </p>
  55 <p>
  56         A typical approach is to consider the existence of a valid return value as
  57         a postcondition, so that if the function cannot compute the value to return,
  58         it has either undefined behavior (and can use assert in a debug build) or
  59         uses a runtime check and throws an exception if the postcondition is violated.
  60         This is a reasonable choice for example, for function (A), because the lack
  61         of a proper return value is directly related to an invalid parameter (out
  62         of domain argument), so it is appropriate to require the callee to supply
  63         only parameters in a valid domain for execution to continue normally.
  64       </p>
  65 <p>
  66         However, function (B), because of its asynchronous nature, does not fail
  67         just because it can't find a value to return; so it is incorrect to consider
  68         such a situation an error and assert or throw an exception. This function
  69         must return, and somehow, must tell the callee that it is not returning a
  70         meaningful value.
  71       </p>
  72 <p>
  73         A similar situation occurs with function (C): it is conceptually an error
  74         to ask a <span class="emphasis"><em>null-area</em></span> polygon to return a point inside
  75         itself, but in many applications, it is just impractical for performance
  76         reasons to treat this as an error (because detecting that the polygon has
  77         no area might be too expensive to be required to be tested previously), and
  78         either an arbitrary point (typically at infinity) is returned, or some efficient
  79         way to tell the callee that there is no such point is used.
  80       </p>
  81 <p>
  82         There are various mechanisms to let functions communicate that the returned
  83         value is not valid. One such mechanism, which is quite common since it has
  84         zero or negligible overhead, is to use a special value which is reserved
  85         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>,
  86         points at infinity, etc...
  87       </p>
  88 <p>
  89         When those values exist, i.e. the return type can hold all meaningful values
  90         <span class="emphasis"><em>plus</em></span> the <span class="emphasis"><em>signal</em></span> value, this mechanism
  91         is quite appropriate and well known. Unfortunately, there are cases when
  92         such values do not exist. In these cases, the usual alternative is either
  93         to use a wider type, such as <code class="computeroutput"><span class="keyword">int</span></code>
  94         in place of <code class="computeroutput"><span class="keyword">char</span></code>; or a compound
  95         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>.
  96       </p>
  97 <p>
  98         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
  99         result which indicates if the result is meaningful, has the advantage that
 100         can be turned into a consistent idiom since the first element of the pair
 101         can be whatever the function would conceptually return. For example, the
 102         last two functions could have the following interface:
 103       </p>
 104 <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>
 105 <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>
 106 </pre>
 107 <p>
 108         These functions use a consistent interface for dealing with possibly nonexistent
 109         results:
 110       </p>
 111 <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>
 112 <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>
 113     <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>
 114 </pre>
 115 <p>
 116         However, not only is this quite a burden syntactically, it is also error
 117         prone since the user can easily use the function result (first element of
 118         the pair) without ever checking if it has a valid value.
 119       </p>
 120 <p>
 121         Clearly, we need a better idiom.
 122       </p>
 123 </div>
 124 <div class="section">
 125 <div class="titlepage"><div><div><h3 class="title">
 126 <a name="boost_optional.tutorial.design_overview"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview" title="Design Overview">Design Overview</a>
 127 </h3></div></div></div>
 128 <div class="toc"><dl class="toc">
 129 <dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.design_overview.the_models">The
 130         models</a></span></dt>
 131 <dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.design_overview.the_semantics">The
 132         semantics</a></span></dt>
 133 <dt><span class="section"><a href="tutorial.html#boost_optional.tutorial.design_overview.the_interface">The
 134         Interface</a></span></dt>
 135 </dl></div>
 136 <div class="section">
 137 <div class="titlepage"><div><div><h4 class="title">
 138 <a name="boost_optional.tutorial.design_overview.the_models"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_models" title="The models">The
 139         models</a>
 140 </h4></div></div></div>
 141 <p>
 142           In C++, we can <span class="emphasis"><em>declare</em></span> an object (a variable) of type
 143           <code class="computeroutput"><span class="identifier">T</span></code>, and we can give this
 144           variable an <span class="emphasis"><em>initial value</em></span> (through an <span class="emphasis"><em>initializer</em></span>.
 145           (cf. 8.5)). When a declaration includes a non-empty initializer (an initial
 146           value is given), it is said that the object has been initialized. If the
 147           declaration uses an empty initializer (no initial value is given), and
 148           neither default nor value initialization applies, it is said that the object
 149           is <span class="bold"><strong>uninitialized</strong></span>. Its actual value exist
 150           but has an <span class="emphasis"><em>indeterminate initial value</em></span> (cf. 8.5/11).
 151           <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
 152           intends to formalize the notion of initialization (or lack of it) allowing
 153           a program to test whether an object has been initialized and stating that
 154           access to the value of an uninitialized object is undefined behavior. That
 155           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
 156           variable is <span class="emphasis"><em>formally</em></span> uninitialized. A formally uninitialized
 157           optional object has conceptually no value at all and this situation can
 158           be tested at runtime. It is formally <span class="emphasis"><em>undefined behavior</em></span>
 159           to try to access the value of an uninitialized optional. An uninitialized
 160           optional can be assigned a value, in which case its initialization state
 161           changes to initialized. Furthermore, given the formal treatment of initialization
 162           states in optional objects, it is even possible to reset an optional to
 163           <span class="emphasis"><em>uninitialized</em></span>.
 164         </p>
 165 <p>
 166           In C++ there is no formal notion of uninitialized objects, which means
 167           that objects always have an initial value even if indeterminate. As discussed
 168           on the previous section, this has a drawback because you need additional
 169           information to tell if an object has been effectively initialized. One
 170           of the typical ways in which this has been historically dealt with is via
 171           a special value: <code class="computeroutput"><span class="identifier">EOF</span></code>,
 172           <code class="computeroutput"><span class="identifier">npos</span></code>, -1, etc... This is
 173           equivalent to adding the special value to the set of possible values of
 174           a given type. This super set of <code class="computeroutput"><span class="identifier">T</span></code>
 175           plus some <span class="emphasis"><em>nil_t</em></span>&#8212;where <code class="computeroutput"><span class="identifier">nil_t</span></code>
 176           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
 177           unions are often called <span class="emphasis"><em>variants</em></span>. A variant has a
 178           <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>.
 179           Using the <a href="../../../../variant/index.html" target="_top">Boost.Variant</a>
 180           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
 181           union as a model for an optional value: the <a href="http://www.haskell.org/" target="_top">Haskell</a>
 182           <span class="bold"><strong>Maybe</strong></span> built-in type constructor. Thus,
 183           a discriminated union <code class="computeroutput"><span class="identifier">T</span><span class="special">+</span><span class="identifier">nil_t</span></code>
 184           serves as a conceptual foundation.
 185         </p>
 186 <p>
 187           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
 188           idiom of extending the range of possible values adding an additional sentinel
 189           value with the special meaning of <span class="emphasis"><em>Nothing</em></span>. However,
 190           this additional <span class="emphasis"><em>Nothing</em></span> value is largely irrelevant
 191           for our purpose since our goal is to formalize the notion of uninitialized
 192           objects and, while a special extended value can be used to convey that
 193           meaning, it is not strictly necessary in order to do so.
 194         </p>
 195 <p>
 196           The observation made in the last paragraph about the irrelevant nature
 197           of the additional <code class="computeroutput"><span class="identifier">nil_t</span></code>
 198           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>
 199           suggests an alternative model: a <span class="emphasis"><em>container</em></span> that either
 200           has a value of <code class="computeroutput"><span class="identifier">T</span></code> or nothing.
 201         </p>
 202 <p>
 203           As of this writing I don't know of any precedent for a variable-size fixed-capacity
 204           (of 1) stack-based container model for optional values, yet I believe this
 205           is the consequence of the lack of practical implementations of such a container
 206           rather than an inherent shortcoming of the container model.
 207         </p>
 208 <p>
 209           In any event, both the discriminated-union or the single-element container
 210           models serve as a conceptual ground for a class representing optional&#8212;i.e.
 211           possibly uninitialized&#8212;objects. For instance, these models show the
 212           <span class="emphasis"><em>exact</em></span> semantics required for a wrapper of optional
 213           values:
 214         </p>
 215 <p>
 216           Discriminated-union:
 217         </p>
 218 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 219 <li class="listitem">
 220               <span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
 221               variant implies copies of the value.
 222             </li>
 223 <li class="listitem">
 224               <span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
 225               between variants matches both current types and values
 226             </li>
 227 <li class="listitem">
 228               If the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>,
 229               it is modeling an <span class="emphasis"><em>initialized</em></span> optional.
 230             </li>
 231 <li class="listitem">
 232               If the variant's current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
 233               it is modeling an <span class="emphasis"><em>uninitialized</em></span> optional.
 234             </li>
 235 <li class="listitem">
 236               Testing if the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>
 237               models testing if the optional is initialized
 238             </li>
 239 <li class="listitem">
 240               Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code>
 241               from a variant when its current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
 242               models the undefined behavior of trying to access the value of an uninitialized
 243               optional
 244             </li>
 245 </ul></div>
 246 <p>
 247           Single-element container:
 248         </p>
 249 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 250 <li class="listitem">
 251               <span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
 252               container implies copies of the value.
 253             </li>
 254 <li class="listitem">
 255               <span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
 256               between containers compare container size and if match, contained value
 257             </li>
 258 <li class="listitem">
 259               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>
 260               optional.
 261             </li>
 262 <li class="listitem">
 263               If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
 264               optional.
 265             </li>
 266 <li class="listitem">
 267               Testing if the container is empty models testing if the optional is
 268               initialized
 269             </li>
 270 <li class="listitem">
 271               Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code>
 272               from an empty container models the undefined behavior of trying to
 273               access the value of an uninitialized optional
 274             </li>
 275 </ul></div>
 276 </div>
 277 <div class="section">
 278 <div class="titlepage"><div><div><h4 class="title">
 279 <a name="boost_optional.tutorial.design_overview.the_semantics"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_semantics" title="The semantics">The
 280         semantics</a>
 281 </h4></div></div></div>
 282 <p>
 283           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
 284           objects of type <code class="computeroutput"><span class="identifier">T</span></code> would
 285           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
 286           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>
 287           can have the same operational semantics of <code class="computeroutput"><span class="identifier">T</span></code>
 288           plus the additional semantics corresponding to this special state. As such,
 289           <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
 290           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++,
 291           so we need to compose the desired semantics using a different mechanism.
 292           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
 293           <code class="computeroutput"><span class="identifier">T</span></code> is not only conceptually
 294           wrong but also impractical: it is not allowed to derive from a non-class
 295           type, such as a built-in type.
 296         </p>
 297 <p>
 298           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:
 299         </p>
 300 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 301 <li class="listitem">
 302               <span class="bold"><strong>Default Construction:</strong></span> To introduce
 303               a formally uninitialized wrapped object.
 304             </li>
 305 <li class="listitem">
 306               <span class="bold"><strong>Direct Value Construction via copy:</strong></span>
 307               To introduce a formally initialized wrapped object whose value is obtained
 308               as a copy of some object.
 309             </li>
 310 <li class="listitem">
 311               <span class="bold"><strong>Deep Copy Construction:</strong></span> To obtain
 312               a new yet equivalent wrapped object.
 313             </li>
 314 <li class="listitem">
 315               <span class="bold"><strong>Direct Value Assignment (upon initialized):</strong></span>
 316               To assign a value to the wrapped object.
 317             </li>
 318 <li class="listitem">
 319               <span class="bold"><strong>Direct Value Assignment (upon uninitialized):</strong></span>
 320               To initialize the wrapped object with a value obtained as a copy of
 321               some object.
 322             </li>
 323 <li class="listitem">
 324               <span class="bold"><strong>Assignment (upon initialized):</strong></span> To
 325               assign to the wrapped object the value of another wrapped object.
 326             </li>
 327 <li class="listitem">
 328               <span class="bold"><strong>Assignment (upon uninitialized):</strong></span> To
 329               initialize the wrapped object with value of another wrapped object.
 330             </li>
 331 <li class="listitem">
 332               <span class="bold"><strong>Deep Relational Operations (when supported by
 333               the type T):</strong></span> To compare wrapped object values taking into
 334               account the presence of uninitialized states.
 335             </li>
 336 <li class="listitem">
 337               <span class="bold"><strong>Value access:</strong></span> To unwrap the wrapped
 338               object.
 339             </li>
 340 <li class="listitem">
 341               <span class="bold"><strong>Initialization state query:</strong></span> To determine
 342               if the object is formally initialized or not.
 343             </li>
 344 <li class="listitem">
 345               <span class="bold"><strong>Swap:</strong></span> To exchange wrapped objects.
 346               (with whatever exception safety guarantees are provided by <code class="computeroutput"><span class="identifier">T</span></code>'s swap).
 347             </li>
 348 <li class="listitem">
 349               <span class="bold"><strong>De-initialization:</strong></span> To release the
 350               wrapped object (if any) and leave the wrapper in the uninitialized
 351               state.
 352             </li>
 353 </ul></div>
 354 <p>
 355           Additional operations are useful, such as converting constructors and converting
 356           assignments, in-place construction and assignment, and safe value access
 357           via a pointer to the wrapped object or null.
 358         </p>
 359 </div>
 360 <div class="section">
 361 <div class="titlepage"><div><div><h4 class="title">
 362 <a name="boost_optional.tutorial.design_overview.the_interface"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_interface" title="The Interface">The
 363         Interface</a>
 364 </h4></div></div></div>
 365 <p>
 366           Since the purpose of optional is to allow us to use objects with a formal
 367           uninitialized additional state, the interface could try to follow the interface
 368           of the underlying <code class="computeroutput"><span class="identifier">T</span></code> type
 369           as much as possible. In order to choose the proper degree of adoption of
 370           the native <code class="computeroutput"><span class="identifier">T</span></code> interface,
 371           the following must be noted: Even if all the operations supported by an
 372           instance of type <code class="computeroutput"><span class="identifier">T</span></code> are
 373           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>
 374           extends such a set of values with a new value for which most (otherwise
 375           valid) operations are not defined in terms of <code class="computeroutput"><span class="identifier">T</span></code>.
 376         </p>
 377 <p>
 378           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>
 379           wrapper (modeling a <code class="computeroutput"><span class="identifier">T</span></code> supertype),
 380           any attempt to define such operations upon uninitialized optionals will
 381           be totally artificial w.r.t. <code class="computeroutput"><span class="identifier">T</span></code>.
 382         </p>
 383 <p>
 384           This library chooses an interface which follows from <code class="computeroutput"><span class="identifier">T</span></code>'s
 385           interface only for those operations which are well defined (w.r.t the type
 386           <code class="computeroutput"><span class="identifier">T</span></code>) even if any of the operands
 387           are uninitialized. These operations include: construction, copy-construction,
 388           assignment, swap and relational operations.
 389         </p>
 390 <p>
 391           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,
 392           a different interface is chosen (which will be explained next).
 393         </p>
 394 <p>
 395           Also, the presence of the possibly uninitialized state requires additional
 396           operations not provided by <code class="computeroutput"><span class="identifier">T</span></code>
 397           itself which are supported by a special interface.
 398         </p>
 399 <h6>
 400 <a name="boost_optional.tutorial.design_overview.the_interface.h0"></a>
 401           <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="tutorial.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
 402           Value Access in the presence of possibly untitialized optional objects:
 403           The operators * and -&gt;</a>
 404         </h6>
 405 <p>
 406           A relevant feature of a pointer is that it can have a <span class="bold"><strong>null
 407           pointer value</strong></span>. This is a <span class="emphasis"><em>special</em></span> value
 408           which is used to indicate that the pointer is not referring to any object
 409           at all. In other words, null pointer values convey the notion of nonexistent
 410           objects.
 411         </p>
 412 <p>
 413           This meaning of the null pointer value allowed pointers to became a <span class="emphasis"><em>de
 414           facto</em></span> standard for handling optional objects because all you
 415           have to do to refer to a value which you don't really have is to use a
 416           null pointer value of the appropriate type. Pointers have been used for
 417           decades&#8212;from the days of C APIs to modern C++ libraries&#8212;to <span class="emphasis"><em>refer</em></span>
 418           to optional (that is, possibly nonexistent) objects; particularly as optional
 419           arguments to a function, but also quite often as optional data members.
 420         </p>
 421 <p>
 422           The possible presence of a null pointer value makes the operations that
 423           access the pointee's value possibly undefined, therefore, expressions which
 424           use dereference and access operators, such as: <code class="computeroutput"><span class="special">(</span>
 425           <span class="special">*</span><span class="identifier">p</span>
 426           <span class="special">=</span> <span class="number">2</span> <span class="special">)</span></code> and <code class="computeroutput"><span class="special">(</span>
 427           <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,
 428           and this information is tied to the <span class="emphasis"><em>syntax</em></span> of the
 429           expressions. That is, the presence of operators <code class="computeroutput"><span class="special">*</span></code>
 430           and <code class="computeroutput"><span class="special">-&gt;</span></code> tell by themselves
 431           &#8212;without any additional context&#8212; that the expression will be undefined
 432           unless the implied pointee actually exist.
 433         </p>
 434 <p>
 435           Such a <span class="emphasis"><em>de facto</em></span> idiom for referring to optional objects
 436           can be formalized in the form of a concept: the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>
 437           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>
 438           and contextual conversion to <code class="computeroutput"><span class="keyword">bool</span></code>
 439           to convey the notion of optionality.
 440         </p>
 441 <p>
 442           However, pointers are good to <span class="underline">refer</span>
 443           to optional objects, but not particularly good to handle the optional objects
 444           in all other respects, such as initializing or moving/copying them. The
 445           problem resides in the shallow-copy of pointer semantics: if you need to
 446           effectively move or copy the object, pointers alone are not enough. The
 447           problem is that copies of pointers do not imply copies of pointees. For
 448           example, as was discussed in the motivation, pointers alone cannot be used
 449           to return optional objects from a function because the object must move
 450           outside from the function and into the caller's context.
 451         </p>
 452 <p>
 453           A solution to the shallow-copy problem that is often used is to resort
 454           to dynamic allocation and use a smart pointer to automatically handle the
 455           details of this. For example, if a function is to optionally return an
 456           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>
 457           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>
 458           is a built-in or small POD, this technique is very poor in terms of required
 459           resources. Optional objects are essentially values so it is very convenient
 460           to be able to use automatic storage and deep-copy semantics to manipulate
 461           optional values just as we do with ordinary values. Pointers do not have
 462           this semantics, so are inappropriate for the initialization and transport
 463           of optional values, yet are quite convenient for handling the access to
 464           the possible undefined value because of the idiomatic aid present in the
 465           <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>
 466           concept incarnated by pointers.
 467         </p>
 468 <h6>
 469 <a name="boost_optional.tutorial.design_overview.the_interface.h1"></a>
 470           <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="tutorial.html#boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional&lt;T&gt;
 471           as a model of OptionalPointee</a>
 472         </h6>
 473 <p>
 474           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>
 475           and <code class="computeroutput"><span class="special">-&gt;</span></code> to lexically warn
 476           about the possibly uninitialized state appealing to the familiar pointer
 477           semantics w.r.t. to null pointers.
 478         </p>
 479 <div class="warning"><table border="0" summary="Warning">
 480 <tr>
 481 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../doc/src/images/warning.png"></td>
 482 <th align="left">Warning</th>
 483 </tr>
 484 <tr><td align="left" valign="top"><p>
 485             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
 486             pointer</span>.
 487           </p></td></tr>
 488 </table></div>
 489 <p>
 490           For instance, <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> does not have shallow-copy so does
 491           not alias: two different optionals never refer to the <span class="emphasis"><em>same</em></span>
 492           value unless <code class="computeroutput"><span class="identifier">T</span></code> itself is
 493           a reference (but may have <span class="emphasis"><em>equivalent</em></span> values). The
 494           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,
 495           particularly because the semantics of relational operators are different:
 496           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>
 497           is a value-wrapper, relational operators are deep: they compare optional
 498           values; but relational operators for pointers are shallow: they do not
 499           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>
 500           by <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code>
 501           on some situations but not always. Specifically, on generic code written
 502           for both, you cannot use relational operators directly, and must use the
 503           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>
 504           and <a href="../../../../utility/OptionalPointee.html#less" target="_top"><code class="computeroutput"><span class="identifier">less_pointees</span><span class="special">()</span></code></a>
 505           instead.
 506         </p>
 507 </div>
 508 </div>
 509 </div>
 510 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 511 <td align="left"></td>
 512 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
 513         Distributed under the Boost Software License, Version 1.0. (See accompanying
 514         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>)
 515       </p>
 516 </div></td>
 517 </tr></table>
 518 <hr>
 519 <div class="spirit-nav">
 520 <a accesskey="p" href="quick_start.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="synopsis.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 521 </div>
 522 </body>
 523 </html>