ceph/src/boost/libs/optional/doc/html/boost_optional/tutorial/design_overview/the_interface.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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.78.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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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">&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>
  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 -&gt;</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&#8212;from the days of C APIs to modern C++ libraries&#8212;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">-&gt;</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">-&gt;</span></code> tell by themselves
  96           &#8212;without any additional context&#8212; 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">-&gt;</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">&lt;</span><span class="identifier">X</span><span class="special">&gt;</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&lt;T&gt;
 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">&lt;&gt;</span></code> uses operators <code class="computeroutput"><span class="special">*</span></code>
 141           and <code class="computeroutput"><span class="special">-&gt;</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">&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
 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">&lt;&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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 &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;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>