ceph/src/boost/libs/optional/doc/html/boost_optional/quick_start/optional_return_values.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Optional return values</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="../quick_start.html" title="Quick Start">
   9 <link rel="prev" href="../quick_start.html" title="Quick Start">
  10 <link rel="next" href="optional_automatic_variables.html" title="Optional automatic variables">
  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="../quick_start.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="optional_automatic_variables.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_optional.quick_start.optional_return_values"></a><a class="link" href="optional_return_values.html" title="Optional return values">Optional
  28       return values</a>
  29 </h3></div></div></div>
  30 <p>
  31         Let's write and use a converter function that converts an a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
  32         to an <code class="computeroutput"><span class="keyword">int</span></code>. It is possible that
  33         for a given string (e.g. <code class="computeroutput"><span class="string">"cat"</span></code>)
  34         there exist no value of type <code class="computeroutput"><span class="keyword">int</span></code>
  35         capable of representing the conversion result. We do not consider such situation
  36         an error. We expect that the converter can be used only to check if the conversion
  37         is possible. A natural signature for this function can be:
  38       </p>
  39 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">optional</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  40 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optionl</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">text</span><span class="special">);</span>
  41 </pre>
  42 <p>
  43         All necessary functionality can be included with one header <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">optional</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>.
  44         The above function signature means that the function can either return a
  45         value of type <code class="computeroutput"><span class="keyword">int</span></code> or a flag
  46         indicating that no value of <code class="computeroutput"><span class="keyword">int</span></code>
  47         is available. This does not indicate an error. It is like one additional
  48         value of <code class="computeroutput"><span class="keyword">int</span></code>. This is how we
  49         can use our function:
  50       </p>
  51 <pre class="programlisting"><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">text</span> <span class="special">=</span> <span class="comment">/*... */</span><span class="special">;</span>
  52 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optionl</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">oi</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">text</span><span class="special">);</span> <span class="comment">// move-construct</span>
  53 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">oi</span><span class="special">)</span>                                 <span class="comment">// contextual conversion to bool</span>
  54   <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">oi</span><span class="special">;</span>                          <span class="comment">// operator*</span>
  55 </pre>
  56 <p>
  57         In order to test if <code class="computeroutput"><span class="identifier">optional</span></code>
  58         contains a value, we use the contextual conversion to type <code class="computeroutput"><span class="keyword">bool</span></code>. Because of this we can combine the initialization
  59         of the optional object and the test into one instruction:
  60       </p>
  61 <pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optionl</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">oi</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">text</span><span class="special">))</span>
  62   <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">oi</span><span class="special">;</span>
  63 </pre>
  64 <p>
  65         We extract the contained value with <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> (and with <code class="computeroutput"><span class="keyword">operator</span><span class="special">-&gt;</span></code> where it makes sense). An attempt to
  66         extract the contained value of an uninitialized optional object is an <span class="emphasis"><em>undefined
  67         behaviour</em></span> (UB). This implementation guards the call with <code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>. Therefore you should be sure
  68         that the contained value is there before extracting. For instance, the following
  69         code is reasonably UB-safe:
  70       </p>
  71 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">convert</span><span class="special">(</span><span class="string">"100"</span><span class="special">);</span>
  72 </pre>
  73 <p>
  74         This is because we know that string value <code class="computeroutput"><span class="string">"100"</span></code>
  75         converts to a valid value of <code class="computeroutput"><span class="keyword">int</span></code>.
  76         If you do not like this potential UB, you can use an alternative way of extracting
  77         the contained value:
  78       </p>
  79 <pre class="programlisting"><span class="keyword">try</span> <span class="special">{</span>
  80   <span class="keyword">int</span> <span class="identifier">j</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">text</span><span class="special">).</span><span class="identifier">value</span><span class="special">();</span>
  81 <span class="special">}</span>
  82 <span class="keyword">catch</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bad_optional_access</span><span class="special">&amp;)</span> <span class="special">{</span>
  83   <span class="comment">// deal with it</span>
  84 <span class="special">}</span>
  85 </pre>
  86 <p>
  87         This version throws an exception upon an attempt to access a non-existent
  88         contained value. If your way of dealing with the missing value is to use
  89         some default, like <code class="computeroutput"><span class="number">0</span></code>, there exists
  90         a yet another alternative:
  91       </p>
  92 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">k</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">text</span><span class="special">).</span><span class="identifier">value_or</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
  93 </pre>
  94 <p>
  95         This uses the <code class="computeroutput"><span class="identifier">atoi</span></code>-like approach
  96         to conversions: if <code class="computeroutput"><span class="identifier">text</span></code> does
  97         not represent an integral number just return <code class="computeroutput"><span class="number">0</span></code>.
  98         Now, let's consider how function <code class="computeroutput"><span class="identifier">convert</span></code>
  99         can be implemented.
 100       </p>
 101 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optionl</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&amp;</span> <span class="identifier">text</span><span class="special">)</span>
 102 <span class="special">{</span>
 103   <span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">s</span><span class="special">(</span><span class="identifier">text</span><span class="special">);</span>
 104   <span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
 105   <span class="keyword">if</span> <span class="special">((</span><span class="identifier">s</span> <span class="special">&gt;&gt;</span> <span class="identifier">i</span><span class="special">)</span> <span class="special">&amp;&amp;</span> <span class="identifier">s</span><span class="special">.</span><span class="identifier">get</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">char_traits</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;::</span><span class="identifier">eof</span><span class="special">())</span>
 106     <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span>
 107   <span class="keyword">else</span>
 108     <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">;</span>
 109 <span class="special">}</span>
 110 </pre>
 111 <p>
 112         Observe the two return statements. <code class="computeroutput"><span class="keyword">return</span>
 113         <span class="identifier">i</span></code> uses the converting constructor
 114         that can create <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
 115         from <code class="computeroutput"><span class="identifier">T</span></code>. Thus constructed
 116         optional object is initialized and its value is a copy of <code class="computeroutput"><span class="identifier">i</span></code>.
 117         The other return statement uses another converting constructor from a special
 118         tag <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span></code>. It is used to indicate that we want
 119         to create an uninitialized optional object.
 120       </p>
 121 </div>
 122 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 123 <td align="left"></td>
 124 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
 125         Distributed under the Boost Software License, Version 1.0. (See accompanying
 126         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>)
 127       </p>
 128 </div></td>
 129 </tr></table>
 130 <hr>
 131 <div class="spirit-nav">
 132 <a accesskey="p" href="../quick_start.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quick_start.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="optional_automatic_variables.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 133 </div>
 134 </body>
 135 </html>