ceph/src/boost/libs/optional/doc/html/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="Boost.Optional">
   8 <link rel="up" href="../index.html" title="Boost.Optional">
   9 <link rel="prev" href="../boost_optional/quick_start/storage_in_containers.html" title="Storage in containers">
  10 <link rel="next" href="../boost_optional/tutorial/design_overview.html" title="Design Overview">
  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="../boost_optional/quick_start/storage_in_containers.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="../boost_optional/tutorial/design_overview.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="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="../boost_optional/tutorial/design_overview.html">Design Overview</a></span></dt>
  32 <dt><span class="section"><a href="../boost_optional/tutorial/when_to_use_optional.html">When to
  33       use Optional</a></span></dt>
  34 <dt><span class="section"><a href="../boost_optional/tutorial/relational_operators.html">Relational
  35       operators</a></span></dt>
  36 <dt><span class="section"><a href="../boost_optional/tutorial/io_operators.html">IO operators</a></span></dt>
  37 <dt><span class="section"><a href="../boost_optional/tutorial/optional_references.html">Optional
  38       references</a></span></dt>
  39 <dt><span class="section"><a href="../boost_optional/tutorial/in_place_factories.html">In-Place
  40       Factories</a></span></dt>
  41 <dt><span class="section"><a href="../boost_optional/tutorial/gotchas.html">Gotchas</a></span></dt>
  42 <dt><span class="section"><a href="../boost_optional/tutorial/exception_safety_guarantees.html">Exception
  43       Safety Guarantees</a></span></dt>
  44 <dt><span class="section"><a href="../boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>
  45 <dt><span class="section"><a href="../boost_optional/tutorial/performance_considerations.html">Performance
  46       considerations</a></span></dt>
  47 </dl></div>
  48 <div class="section">
  49 <div class="titlepage"><div><div><h3 class="title">
  50 <a name="boost_optional.tutorial.motivation"></a><a class="link" href="tutorial.html#boost_optional.tutorial.motivation" title="Motivation">Motivation</a>
  51 </h3></div></div></div>
  52 <p>
  53         Consider these functions which should return a value but which might not
  54         have a value to return:
  55       </p>
  56 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  57 <li class="listitem">
  58             (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>
  59           </li>
  60 <li class="listitem">
  61             (B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
  62           </li>
  63 <li class="listitem">
  64             (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>
  65           </li>
  66 </ul></div>
  67 <p>
  68         There are different approaches to the issue of not having a value to return.
  69       </p>
  70 <p>
  71         A typical approach is to consider the existence of a valid return value as
  72         a postcondition, so that if the function cannot compute the value to return,
  73         it has either undefined behavior (and can use assert in a debug build) or
  74         uses a runtime check and throws an exception if the postcondition is violated.
  75         This is a reasonable choice for example, for function (A), because the lack
  76         of a proper return value is directly related to an invalid parameter (out
  77         of domain argument), so it is appropriate to require the callee to supply
  78         only parameters in a valid domain for execution to continue normally.
  79       </p>
  80 <p>
  81         However, function (B), because of its asynchronous nature, does not fail
  82         just because it can't find a value to return; so it is incorrect to consider
  83         such a situation an error and assert or throw an exception. This function
  84         must return, and somehow, must tell the callee that it is not returning a
  85         meaningful value.
  86       </p>
  87 <p>
  88         A similar situation occurs with function (C): it is conceptually an error
  89         to ask a <span class="emphasis"><em>null-area</em></span> polygon to return a point inside
  90         itself, but in many applications, it is just impractical for performance
  91         reasons to treat this as an error (because detecting that the polygon has
  92         no area might be too expensive to be required to be tested previously), and
  93         either an arbitrary point (typically at infinity) is returned, or some efficient
  94         way to tell the callee that there is no such point is used.
  95       </p>
  96 <p>
  97         There are various mechanisms to let functions communicate that the returned
  98         value is not valid. One such mechanism, which is quite common since it has
  99         zero or negligible overhead, is to use a special value which is reserved
 100         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>,
 101         points at infinity, etc...
 102       </p>
 103 <p>
 104         When those values exist, i.e. the return type can hold all meaningful values
 105         <span class="emphasis"><em>plus</em></span> the <span class="emphasis"><em>signal</em></span> value, this mechanism
 106         is quite appropriate and well known. Unfortunately, there are cases when
 107         such values do not exist. In these cases, the usual alternative is either
 108         to use a wider type, such as <code class="computeroutput"><span class="keyword">int</span></code>
 109         in place of <code class="computeroutput"><span class="keyword">char</span></code>; or a compound
 110         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>.
 111       </p>
 112 <p>
 113         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
 114         result which indicates if the result is meaningful, has the advantage that
 115         can be turned into a consistent idiom since the first element of the pair
 116         can be whatever the function would conceptually return. For example, the
 117         last two functions could have the following interface:
 118       </p>
 119 <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>
 120 <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>
 121 </pre>
 122 <p>
 123         These functions use a consistent interface for dealing with possibly nonexistent
 124         results:
 125       </p>
 126 <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>
 127 <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>
 128     <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>
 129 </pre>
 130 <p>
 131         However, not only is this quite a burden syntactically, it is also error
 132         prone since the user can easily use the function result (first element of
 133         the pair) without ever checking if it has a valid value.
 134       </p>
 135 <p>
 136         Clearly, we need a better idiom.
 137       </p>
 138 </div>
 139 </div>
 140 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 141 <td align="left"></td>
 142 <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>
 143         Distributed under the Boost Software License, Version 1.0. (See accompanying
 144         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>)
 145       </p>
 146 </div></td>
 147 </tr></table>
 148 <hr>
 149 <div class="spirit-nav">
 150 <a accesskey="p" href="../boost_optional/quick_start/storage_in_containers.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="../boost_optional/tutorial/design_overview.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 151 </div>
 152 </body>
 153 </html>