1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>The Interface</title> 5<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../../index.html" title="Boost.Optional"> 8<link rel="up" href="../design_overview.html" title="Design Overview"> 9<link rel="prev" href="the_semantics.html" title="The semantics"> 10<link rel="next" href="../when_to_use_optional.html" title="When to use Optional"> 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="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> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_optional.tutorial.design_overview.the_interface"></a><a class="link" href="the_interface.html" title="The Interface">The 28 Interface</a> 29</h4></div></div></div> 30<p> 31 Since the purpose of optional is to allow us to use objects with a formal 32 uninitialized additional state, the interface could try to follow the interface 33 of the underlying <code class="computeroutput"><span class="identifier">T</span></code> type 34 as much as possible. In order to choose the proper degree of adoption of 35 the native <code class="computeroutput"><span class="identifier">T</span></code> interface, 36 the following must be noted: Even if all the operations supported by an 37 instance of type <code class="computeroutput"><span class="identifier">T</span></code> are 38 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> 39 extends such a set of values with a new value for which most (otherwise 40 valid) operations are not defined in terms of <code class="computeroutput"><span class="identifier">T</span></code>. 41 </p> 42<p> 43 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> 44 wrapper (modeling a <code class="computeroutput"><span class="identifier">T</span></code> supertype), 45 any attempt to define such operations upon uninitialized optionals will 46 be totally artificial w.r.t. <code class="computeroutput"><span class="identifier">T</span></code>. 47 </p> 48<p> 49 This library chooses an interface which follows from <code class="computeroutput"><span class="identifier">T</span></code>'s 50 interface only for those operations which are well defined (w.r.t the type 51 <code class="computeroutput"><span class="identifier">T</span></code>) even if any of the operands 52 are uninitialized. These operations include: construction, copy-construction, 53 assignment, swap and relational operations. 54 </p> 55<p> 56 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, 57 a different interface is chosen (which will be explained next). 58 </p> 59<p> 60 Also, the presence of the possibly uninitialized state requires additional 61 operations not provided by <code class="computeroutput"><span class="identifier">T</span></code> 62 itself which are supported by a special interface. 63 </p> 64<h6> 65<a name="boost_optional.tutorial.design_overview.the_interface.h0"></a> 66 <span class="phrase"><a name="boost_optional.tutorial.design_overview.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_uninitialized_optional_objects__the_operators___and___gt_"></a></span><a class="link" href="the_interface.html#boost_optional.tutorial.design_overview.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_uninitialized_optional_objects__the_operators___and___gt_">Lexically-hinted 67 Value Access in the presence of possibly uninitialized optional objects: 68 The operators * and -></a> 69 </h6> 70<p> 71 A relevant feature of a pointer is that it can have a <span class="bold"><strong>null 72 pointer value</strong></span>. This is a <span class="emphasis"><em>special</em></span> value 73 which is used to indicate that the pointer is not referring to any object 74 at all. In other words, null pointer values convey the notion of nonexistent 75 objects. 76 </p> 77<p> 78 This meaning of the null pointer value allowed pointers to became a <span class="emphasis"><em>de 79 facto</em></span> standard for handling optional objects because all you 80 have to do to refer to a value which you don't really have is to use a 81 null pointer value of the appropriate type. Pointers have been used for 82 decades—from the days of C APIs to modern C++ libraries—to <span class="emphasis"><em>refer</em></span> 83 to optional (that is, possibly nonexistent) objects; particularly as optional 84 arguments to a function, but also quite often as optional data members. 85 </p> 86<p> 87 The possible presence of a null pointer value makes the operations that 88 access the pointee's value possibly undefined, therefore, expressions which 89 use dereference and access operators, such as: <code class="computeroutput"><span class="special">(</span> 90 <span class="special">*</span><span class="identifier">p</span> 91 <span class="special">=</span> <span class="number">2</span> <span class="special">)</span></code> and <code class="computeroutput"><span class="special">(</span> 92 <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, 93 and this information is tied to the <span class="emphasis"><em>syntax</em></span> of the 94 expressions. That is, the presence of operators <code class="computeroutput"><span class="special">*</span></code> 95 and <code class="computeroutput"><span class="special">-></span></code> tell by themselves 96 —without any additional context— that the expression will be undefined 97 unless the implied pointee actually exist. 98 </p> 99<p> 100 Such a <span class="emphasis"><em>de facto</em></span> idiom for referring to optional objects 101 can be formalized in the form of a concept: the <a href="../../../../../../utility/OptionalPointee.html" target="_top"><code class="computeroutput"><span class="identifier">OptionalPointee</span></code></a> concept. This 102 concept captures the syntactic usage of operators <code class="computeroutput"><span class="special">*</span></code>, 103 <code class="computeroutput"><span class="special">-></span></code> and contextual conversion 104 to <code class="computeroutput"><span class="keyword">bool</span></code> to convey the notion 105 of optionality. 106 </p> 107<p> 108 However, pointers are good to <span class="underline">refer</span> 109 to optional objects, but not particularly good to handle the optional objects 110 in all other respects, such as initializing or moving/copying them. The 111 problem resides in the shallow-copy of pointer semantics: if you need to 112 effectively move or copy the object, pointers alone are not enough. The 113 problem is that copies of pointers do not imply copies of pointees. For 114 example, as was discussed in the motivation, pointers alone cannot be used 115 to return optional objects from a function because the object must move 116 outside from the function and into the caller's context. 117 </p> 118<p> 119 A solution to the shallow-copy problem that is often used is to resort 120 to dynamic allocation and use a smart pointer to automatically handle the 121 details of this. For example, if a function is to optionally return an 122 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> 123 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> 124 is a built-in or small POD, this technique is very poor in terms of required 125 resources. Optional objects are essentially values so it is very convenient 126 to be able to use automatic storage and deep-copy semantics to manipulate 127 optional values just as we do with ordinary values. Pointers do not have 128 this semantics, so are inappropriate for the initialization and transport 129 of optional values, yet are quite convenient for handling the access to 130 the possible undefined value because of the idiomatic aid present in the 131 <a href="../../../../../../utility/OptionalPointee.html" target="_top"><code class="computeroutput"><span class="identifier">OptionalPointee</span></code></a> 132 concept incarnated by pointers. 133 </p> 134<h6> 135<a name="boost_optional.tutorial.design_overview.the_interface.h1"></a> 136 <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="the_interface.html#boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional<T> 137 as a model of OptionalPointee</a> 138 </h6> 139<p> 140 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> 141 and <code class="computeroutput"><span class="special">-></span></code> to lexically warn 142 about the possibly uninitialized state appealing to the familiar pointer 143 semantics w.r.t. to null pointers. 144 </p> 145<div class="caution"><table border="0" summary="Caution"> 146<tr> 147<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td> 148<th align="left">Caution</th> 149</tr> 150<tr><td align="left" valign="top"><p> 151 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 152 pointer</span>. 153 </p></td></tr> 154</table></div> 155<p> 156 For instance, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code> does not have shallow-copy so does 157 not alias: two different optionals never refer to the <span class="emphasis"><em>same</em></span> 158 value unless <code class="computeroutput"><span class="identifier">T</span></code> itself is 159 a reference (but may have <span class="emphasis"><em>equivalent</em></span> values). The 160 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, 161 particularly because the semantics of relational operators are different: 162 since <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> 163 is a value-wrapper, relational operators are deep: they compare optional 164 values; but relational operators for pointers are shallow: they do not 165 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> 166 by <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code> 167 on some situations but not always. Specifically, on generic code written 168 for both, you cannot use relational operators directly, and must use the 169 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> 170 and <a href="../../../../../../utility/OptionalPointee.html#less" target="_top"><code class="computeroutput"><span class="identifier">less_pointees</span><span class="special">()</span></code></a> 171 instead. 172 </p> 173</div> 174<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 175<td align="left"></td> 176<td align="right"><div class="copyright-footer">Copyright © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014-2018 Andrzej Krzemieński<p> 177 Distributed under the Boost Software License, Version 1.0. (See accompanying 178 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>) 179 </p> 180</div></td> 181</tr></table> 182<hr> 183<div class="spirit-nav"> 184<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> 185</div> 186</body> 187</html> 188
