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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Quick Start</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="../index.html" title="Boost.Optional">
  10 <link rel="next" href="quick_start/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="../index.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="quick_start/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><h2 class="title" style="clear: both">
  27 <a name="boost_optional.quick_start"></a><a class="link" href="quick_start.html" title="Quick Start">Quick Start</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="quick_start.html#boost_optional.quick_start.optional_return_values">Optional
  31       return values</a></span></dt>
  32 <dt><span class="section"><a href="quick_start/optional_automatic_variables.html">Optional
  33       automatic variables</a></span></dt>
  34 <dt><span class="section"><a href="quick_start/optional_data_members.html">Optional
  35       data members</a></span></dt>
  36 <dt><span class="section"><a href="quick_start/bypassing_unnecessary_default_construction.html">Bypassing
  37       unnecessary default construction</a></span></dt>
  38 <dt><span class="section"><a href="quick_start/storage_in_containers.html">Storage
  39       in containers</a></span></dt>
  40 </dl></div>
  41 <div class="section">
  42 <div class="titlepage"><div><div><h3 class="title">
  43 <a name="boost_optional.quick_start.optional_return_values"></a><a class="link" href="quick_start.html#boost_optional.quick_start.optional_return_values" title="Optional return values">Optional
  44       return values</a>
  45 </h3></div></div></div>
  46 <p>
  47         Let's write and use a converter function that converts a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
  48         to an <code class="computeroutput"><span class="keyword">int</span></code>. It is possible that
  49         for a given string (e.g. <code class="computeroutput"><span class="string">"cat"</span></code>)
  50         there exists no value of type <code class="computeroutput"><span class="keyword">int</span></code>
  51         capable of representing the conversion result. We do not consider such situation
  52         an error. We expect that the converter can be used only to check if the conversion
  53         is possible. A natural signature for this function can be:
  54       </p>
  55 <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>
  56 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</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>
  57 </pre>
  58 <p>
  59         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>.
  60         The above function signature means that the function can either return a
  61         value of type <code class="computeroutput"><span class="keyword">int</span></code> or a flag
  62         indicating that no value of <code class="computeroutput"><span class="keyword">int</span></code>
  63         is available. This does not indicate an error. It is like one additional
  64         value of <code class="computeroutput"><span class="keyword">int</span></code>. This is how we
  65         can use our function:
  66       </p>
  67 <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>
  68 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</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>
  69 <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>
  70   <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>
  71 </pre>
  72 <p>
  73         In order to test if <code class="computeroutput"><span class="identifier">optional</span></code>
  74         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
  75         of the optional object and the test into one instruction:
  76       </p>
  77 <pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</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>
  78   <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>
  79 </pre>
  80 <p>
  81         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
  82         extract the contained value of an uninitialized optional object is an <span class="emphasis"><em>undefined
  83         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
  84         that the contained value is there before extracting. For instance, the following
  85         code is reasonably UB-safe:
  86       </p>
  87 <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>
  88 </pre>
  89 <p>
  90         This is because we know that string value <code class="computeroutput"><span class="string">"100"</span></code>
  91         converts to a valid value of <code class="computeroutput"><span class="keyword">int</span></code>.
  92         If you do not like this potential UB, you can use an alternative way of extracting
  93         the contained value:
  94       </p>
  95 <pre class="programlisting"><span class="keyword">try</span> <span class="special">{</span>
  96   <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>
  97 <span class="special">}</span>
  98 <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>
  99   <span class="comment">// deal with it</span>
 100 <span class="special">}</span>
 101 </pre>
 102 <p>
 103         This version throws an exception upon an attempt to access a non-existent
 104         contained value. If your way of dealing with the missing value is to use
 105         some default, like <code class="computeroutput"><span class="number">0</span></code>, there exists
 106         a yet another alternative:
 107       </p>
 108 <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>
 109 </pre>
 110 <p>
 111         This uses the <code class="computeroutput"><span class="identifier">atoi</span></code>-like approach
 112         to conversions: if <code class="computeroutput"><span class="identifier">text</span></code> does
 113         not represent an integral number just return <code class="computeroutput"><span class="number">0</span></code>.
 114         Finally, you can provide a callback to be called when trying to access the
 115         contained value fails:
 116       </p>
 117 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">fallback_to_default</span><span class="special">()</span>
 118 <span class="special">{</span>
 119   <span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"could not convert; using -1 instead"</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
 120   <span class="keyword">return</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span>
 121 <span class="special">}</span>
 122
 123 <span class="keyword">int</span> <span class="identifier">l</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_eval</span><span class="special">(</span><span class="identifier">fallback_to_default</span><span class="special">);</span>
 124 </pre>
 125 <p>
 126         This will call the provided callback and return whatever the callback returns.
 127         The callback can have side effects: they will only be observed when the optional
 128         object does not contain a value.
 129       </p>
 130 <p>
 131         Now, let's consider how function <code class="computeroutput"><span class="identifier">convert</span></code>
 132         can be implemented.
 133       </p>
 134 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</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>
 135 <span class="special">{</span>
 136   <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>
 137   <span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
 138   <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>
 139     <span class="keyword">return</span> <span class="identifier">i</span><span class="special">;</span>
 140   <span class="keyword">else</span>
 141     <span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">none</span><span class="special">;</span>
 142 <span class="special">}</span>
 143 </pre>
 144 <p>
 145         Observe the two return statements. <code class="computeroutput"><span class="keyword">return</span>
 146         <span class="identifier">i</span></code> uses the converting constructor
 147         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>
 148         from <code class="computeroutput"><span class="identifier">T</span></code>. Thus constructed
 149         optional object is initialized and its value is a copy of <code class="computeroutput"><span class="identifier">i</span></code>.
 150         The other return statement uses another converting constructor from a special
 151         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
 152         to create an uninitialized optional object.
 153       </p>
 154 </div>
 155 </div>
 156 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 157 <td align="left"></td>
 158 <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>
 159         Distributed under the Boost Software License, Version 1.0. (See accompanying
 160         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>)
 161       </p>
 162 </div></td>
 163 </tr></table>
 164 <hr>
 165 <div class="spirit-nav">
 166 <a accesskey="p" href="../index.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="quick_start/optional_automatic_variables.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 167 </div>
 168 </body>
 169 </html>