1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.79.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"><</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">></span> 56<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">></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">&</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"><</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">></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">&</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"><</span><span class="keyword">int</span><span class="special">></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"><</span><span class="keyword">int</span><span class="special">></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">-></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">&)</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"><<</span> <span class="string">"could not convert; using -1 instead"</span> <span class="special"><<</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"><</span><span class="keyword">int</span><span class="special">></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">&</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">>></span> <span class="identifier">i</span><span class="special">)</span> <span class="special">&&</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"><</span><span class="keyword">char</span><span class="special">>::</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"><</span><span class="identifier">T</span><span class="special">></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 © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014-2018 Andrzej Krzemień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> 170
