libs/optional/doc/html/index.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Boost.Optional</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="next" href="boost_optional/quick_start.html" title="Quick Start">
   9 </head>
  10 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  11 <table cellpadding="2" width="100%"><tr>
  12 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  13 <td align="center"><a href="../../../../index.html">Home</a></td>
  14 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  15 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  16 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  17 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  18 </tr></table>
  19 <hr>
  20 <div class="spirit-nav"><a accesskey="n" href="boost_optional/quick_start.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
  21 <div class="chapter">
  22 <div class="titlepage"><div>
  23 <div><h2 class="title">
  24 <a name="optional"></a>Boost.Optional</h2></div>
  25 <div><div class="author"><h3 class="author">
  26 <span class="firstname">Fernando Luis</span> <span class="surname">Cacciola Carballal</span>
  27 </h3></div></div>
  28 <div><p class="copyright">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal</p></div>
  29 <div><p class="copyright">Copyright &#169; 2014-2018 Andrzej Krzemie&#324;ski</p></div>
  30 <div><div class="legalnotice">
  31 <a name="optional.legal"></a><p>
  32         Distributed under the Boost Software License, Version 1.0. (See accompanying
  33         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>)
  34       </p>
  35 </div></div>
  36 </div></div>
  37 <div class="toc">
  38 <p><b>Table of Contents</b></p>
  39 <dl class="toc">
  40 <dt><span class="section"><a href="index.html#optional.introduction">Introduction</a></span></dt>
  41 <dt><span class="section"><a href="boost_optional/quick_start.html">Quick Start</a></span></dt>
  42 <dd><dl>
  43 <dt><span class="section"><a href="boost_optional/quick_start.html#boost_optional.quick_start.optional_return_values">Optional
  44       return values</a></span></dt>
  45 <dt><span class="section"><a href="boost_optional/quick_start/optional_automatic_variables.html">Optional
  46       automatic variables</a></span></dt>
  47 <dt><span class="section"><a href="boost_optional/quick_start/optional_data_members.html">Optional
  48       data members</a></span></dt>
  49 <dt><span class="section"><a href="boost_optional/quick_start/bypassing_unnecessary_default_construction.html">Bypassing
  50       unnecessary default construction</a></span></dt>
  51 <dt><span class="section"><a href="boost_optional/quick_start/storage_in_containers.html">Storage
  52       in containers</a></span></dt>
  53 </dl></dd>
  54 <dt><span class="section"><a href="optional/tutorial.html">Tutorial</a></span></dt>
  55 <dd><dl>
  56 <dt><span class="section"><a href="optional/tutorial.html#boost_optional.tutorial.motivation">Motivation</a></span></dt>
  57 <dt><span class="section"><a href="boost_optional/tutorial/design_overview.html">Design Overview</a></span></dt>
  58 <dt><span class="section"><a href="boost_optional/tutorial/when_to_use_optional.html">When to
  59       use Optional</a></span></dt>
  60 <dt><span class="section"><a href="boost_optional/tutorial/relational_operators.html">Relational
  61       operators</a></span></dt>
  62 <dt><span class="section"><a href="boost_optional/tutorial/io_operators.html">IO operators</a></span></dt>
  63 <dt><span class="section"><a href="boost_optional/tutorial/optional_references.html">Optional
  64       references</a></span></dt>
  65 <dt><span class="section"><a href="boost_optional/tutorial/in_place_factories.html">In-Place
  66       Factories</a></span></dt>
  67 <dt><span class="section"><a href="boost_optional/tutorial/gotchas.html">Gotchas</a></span></dt>
  68 <dt><span class="section"><a href="boost_optional/tutorial/exception_safety_guarantees.html">Exception
  69       Safety Guarantees</a></span></dt>
  70 <dt><span class="section"><a href="boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>
  71 <dt><span class="section"><a href="boost_optional/tutorial/performance_considerations.html">Performance
  72       considerations</a></span></dt>
  73 </dl></dd>
  74 <dt><span class="section"><a href="optional/reference.html">Reference</a></span></dt>
  75 <dd><dl>
  76 <dt><span class="section"><a href="optional/reference.html#boost_optional.reference.header__boost_none_hpp_">Header
  77       &lt;boost/none.hpp&gt;</a></span></dt>
  78 <dt><span class="section"><a href="boost_optional/reference/header__boost_optional_bad_optional_access_hpp_.html">Header
  79       &lt;boost/optional/bad_optional_access.hpp&gt;</a></span></dt>
  80 <dt><span class="section"><a href="boost_optional/reference/io_header.html">Header &lt;boost/optional/optional_io.hpp&gt;</a></span></dt>
  81 <dt><span class="section"><a href="boost_optional/reference/header__boost_optional_optional_fwd_hpp_.html">Header
  82       &lt;boost/optional/optional_fwd.hpp&gt;</a></span></dt>
  83 <dt><span class="section"><a href="optional/reference/header__boost_optional_optional_hpp_.html">Header
  84       &lt;boost/optional/optional.hpp&gt;</a></span></dt>
  85 <dt><span class="section"><a href="boost_optional/reference/header__boost_optional_hpp_.html">Header
  86       &lt;boost/optional.hpp&gt;</a></span></dt>
  87 </dl></dd>
  88 <dt><span class="section"><a href="boost_optional/dependencies_and_portability.html">Dependencies
  89     and Portability</a></span></dt>
  90 <dd><dl>
  91 <dt><span class="section"><a href="boost_optional/dependencies_and_portability.html#boost_optional.dependencies_and_portability.dependencies">Dependencies</a></span></dt>
  92 <dt><span class="section"><a href="boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html">Emplace
  93       operations in older compilers</a></span></dt>
  94 <dt><span class="section"><a href="boost_optional/dependencies_and_portability/optional_reference_binding.html">Optional
  95       Reference Binding</a></span></dt>
  96 </dl></dd>
  97 <dt><span class="section"><a href="boost_optional/relnotes.html">Release Notes</a></span></dt>
  98 <dt><span class="section"><a href="boost_optional/acknowledgements.html">Acknowledgements</a></span></dt>
  99 </dl>
 100 </div>
 101 <div class="section">
 102 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 103 <a name="optional.introduction"></a><a class="link" href="index.html#optional.introduction" title="Introduction">Introduction</a>
 104 </h2></div></div></div>
 105 <p>
 106       Class template <code class="computeroutput"><span class="identifier">optional</span></code> is
 107       a wrapper for representing 'optional' (or 'nullable') objects who may not (yet)
 108       contain a valid value. Optional objects offer full value semantics; they are
 109       good for passing by value and usage inside STL containers. This is a header-only
 110       library.
 111     </p>
 112 <h4>
 113 <a name="optional.introduction.h0"></a>
 114       <span class="phrase"><a name="optional.introduction.problem"></a></span><a class="link" href="index.html#optional.introduction.problem">Problem</a>
 115     </h4>
 116 <p>
 117       Suppose we want to read a parameter form a config file which represents some
 118       integral value, let's call it <code class="computeroutput"><span class="string">"MaxValue"</span></code>.
 119       It is possible that this parameter is not specified; such situation is no error.
 120       It is valid to not specify the parameter and in that case the program is supposed
 121       to behave slightly differently. Also, suppose that any possible value of type
 122       <code class="computeroutput"><span class="keyword">int</span></code> is a valid value for <code class="computeroutput"><span class="string">"MaxValue"</span></code>, so we cannot just use
 123       <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>
 124       to represent the absence of the parameter in the config file.
 125     </p>
 126 <h4>
 127 <a name="optional.introduction.h1"></a>
 128       <span class="phrase"><a name="optional.introduction.solution"></a></span><a class="link" href="index.html#optional.introduction.solution">Solution</a>
 129     </h4>
 130 <p>
 131       This is how you solve it with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span></code>:
 132     </p>
 133 <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>
 134
 135 <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">getConfigParam</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">name</span><span class="special">);</span>  <span class="comment">// return either an int or a `not-an-int`</span>
 136
 137 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 138 <span class="special">{</span>
 139   <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">getConfigParam</span><span class="special">(</span><span class="string">"MaxValue"</span><span class="special">))</span> <span class="comment">// did I get a real int?</span>
 140     <span class="identifier">runWithMax</span><span class="special">(*</span><span class="identifier">oi</span><span class="special">);</span>                                        <span class="comment">// use my int</span>
 141   <span class="keyword">else</span>
 142     <span class="identifier">runWithNoMax</span><span class="special">();</span>
 143 <span class="special">}</span>
 144 </pre>
 145 </div>
 146 </div>
 147 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 148 <td align="left"><p><small>Last revised: December 10, 2019 at 00:22:19 GMT</small></p></td>
 149 <td align="right"><div class="copyright-footer"></div></td>
 150 </tr></table>
 151 <hr>
 152 <div class="spirit-nav"><a accesskey="n" href="boost_optional/quick_start.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div>
 153 </body>
 154 </html>