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 1. Boost.Optional"> 8<link rel="up" href="../index.html" title="Chapter 1. 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"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></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"><</span><span class="keyword">char</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></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"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></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"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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>—where <code class="computeroutput"><span class="identifier">nil_t</span></code> 176 is some stateless POD—can be modeled in modern languages as a <span class="bold"><strong>discriminated union</strong></span> of T and nil_t. Discriminated 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"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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—i.e. 211 possibly uninitialized—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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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 -></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—from the days of C APIs to modern C++ libraries—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">-></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">-></span></code> tell by themselves 431 —without any additional context— 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">-></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"><</span><span class="identifier">X</span><span class="special">></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<T> 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"><></span></code> uses operators <code class="computeroutput"><span class="special">*</span></code> 475 and <code class="computeroutput"><span class="special">-></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"><></span></code> objects are not pointers. <span class="underline"><code class="computeroutput"><span class="identifier">optional</span><span class="special"><></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"><></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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"><</span><span class="identifier">T</span><span class="special">></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 © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014 Andrzej Krzemień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> 524
