ceph/src/boost/libs/optional/doc/html/boost_optional/discussion.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Discussion</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="development.html" title="Development">
  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="development.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.discussion"></a><a class="link" href="discussion.html" title="Discussion">Discussion</a>
  28 </h2></div></div></div>
  29 <p>
  30       Consider these functions which should return a value but which might not have
  31       a value to return:
  32     </p>
  33 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  34 <li class="listitem">
  35           (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>
  36         </li>
  37 <li class="listitem">
  38           (B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
  39         </li>
  40 <li class="listitem">
  41           (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>
  42         </li>
  43 </ul></div>
  44 <p>
  45       There are different approaches to the issue of not having a value to return.
  46     </p>
  47 <p>
  48       A typical approach is to consider the existence of a valid return value as
  49       a postcondition, so that if the function cannot compute the value to return,
  50       it has either undefined behavior (and can use assert in a debug build) or uses
  51       a runtime check and throws an exception if the postcondition is violated. This
  52       is a reasonable choice for example, for function (A), because the lack of a
  53       proper return value is directly related to an invalid parameter (out of domain
  54       argument), so it is appropriate to require the callee to supply only parameters
  55       in a valid domain for execution to continue normally.
  56     </p>
  57 <p>
  58       However, function (B), because of its asynchronous nature, does not fail just
  59       because it can't find a value to return; so it is incorrect to consider such
  60       a situation an error and assert or throw an exception. This function must return,
  61       and somehow, must tell the callee that it is not returning a meaningful value.
  62     </p>
  63 <p>
  64       A similar situation occurs with function (C): it is conceptually an error to
  65       ask a <span class="emphasis"><em>null-area</em></span> polygon to return a point inside itself,
  66       but in many applications, it is just impractical for performance reasons to
  67       treat this as an error (because detecting that the polygon has no area might
  68       be too expensive to be required to be tested previously), and either an arbitrary
  69       point (typically at infinity) is returned, or some efficient way to tell the
  70       callee that there is no such point is used.
  71     </p>
  72 <p>
  73       There are various mechanisms to let functions communicate that the returned
  74       value is not valid. One such mechanism, which is quite common since it has
  75       zero or negligible overhead, is to use a special value which is reserved to
  76       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>, points
  77       at infinity, etc...
  78     </p>
  79 <p>
  80       When those values exist, i.e. the return type can hold all meaningful values
  81       <span class="emphasis"><em>plus</em></span> the <span class="emphasis"><em>signal</em></span> value, this mechanism
  82       is quite appropriate and well known. Unfortunately, there are cases when such
  83       values do not exist. In these cases, the usual alternative is either to use
  84       a wider type, such as <code class="computeroutput"><span class="keyword">int</span></code> in place
  85       of <code class="computeroutput"><span class="keyword">char</span></code>; or a compound type, such
  86       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>.
  87     </p>
  88 <p>
  89       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 result
  90       which indicates if the result is meaningful, has the advantage that can be
  91       turned into a consistent idiom since the first element of the pair can be whatever
  92       the function would conceptually return. For example, the last two functions
  93       could have the following interface:
  94     </p>
  95 <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>
  96 <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>
  97 </pre>
  98 <p>
  99       These functions use a consistent interface for dealing with possibly nonexistent
 100       results:
 101     </p>
 102 <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>
 103 <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>
 104     <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>
 105 </pre>
 106 <p>
 107       However, not only is this quite a burden syntactically, it is also error prone
 108       since the user can easily use the function result (first element of the pair)
 109       without ever checking if it has a valid value.
 110     </p>
 111 <p>
 112       Clearly, we need a better idiom.
 113     </p>
 114 </div>
 115 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 116 <td align="left"></td>
 117 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
 118         Distributed under the Boost Software License, Version 1.0. (See accompanying
 119         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>)
 120       </p>
 121 </div></td>
 122 </tr></table>
 123 <hr>
 124 <div class="spirit-nav">
 125 <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="development.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 126 </div>
 127 </body>
 128 </html>