devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>checked_result&lt;R&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="library_implementation.html" title="Library Implementation">
<link rel="prev" href="library_implementation.html" title="Library Implementation">
<link rel="next" href="checked_arithmetic.html" title="Checked Arithmetic">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="library_implementation.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="library_implementation.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="checked_arithmetic.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safenumerics.checked_result"></a>checked_result&lt;R&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="checked_result.html#idm130202581904">Description</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202564160">Notation</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202541568">Template Parameters</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202533440">Model of</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202531728">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202483424">Example of use</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202416320">See Also</a></span></dt>
<dt><span class="section"><a href="checked_result.html#idm130202414608">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202581904"></a>Description</h4></div></div></div>
<p>checked_result is a special kind of variant class designed to hold
    the result of some operation. It can hold either the result of the
    operation or information on why the operation failed to produce a valid
    result. It is similar to other types proposed for and/or included to the
    C++ standard library or Boost such as<code class="computeroutput"> expected</code>,
    <code class="computeroutput">variant</code>, <code class="computeroutput">optional</code> and <code class="computeroutput">outcome</code>. In
    some circumstances it may be referred to as a "monad".</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>All instances of <code class="computeroutput">checked_result&lt;R&gt;</code> are
          immutable. That is, once constructed, they cannot be altered.</p></li>
<li class="listitem"><p>There is no default constructor.</p></li>
<li class="listitem"><p><code class="computeroutput">checked_result&lt;R&gt;</code> is never empty.</p></li>
<li class="listitem"><p>Binary operations supported by type R are guaranteed to be
          supported by checked_result&lt;R&gt;.</p></li>
<li class="listitem"><p>Binary operations can be invoked on a pair of
          <code class="computeroutput">checked_result&lt;R&gt;</code> instances if and only if the
          underlying type (R) is identical for both instances. They will
          return a value of type <code class="computeroutput">checked_result&lt;R&gt;</code>.</p></li>
<li class="listitem"><p>Unary operations can be invoked on
          <code class="computeroutput">checked_result&lt;R&gt;</code> instances. They will return a
          value of type <code class="computeroutput">checked_result&lt;R&gt;</code>.</p></li>
<li class="listitem"><p>Comparison operations will return a
          <code class="computeroutput">boost::logic::tribool</code>. Other binary operations will a
          value of the same type as the arguments.</p></li>
</ul></div>
<p>Think of <code class="computeroutput">checked&lt;R&gt;</code> as an "extended" version of R
    which can hold all the values that R can hold in addition other "special
    values". For example, consider checked&lt;int&gt;.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202564160"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">R</code></td>
<td align="left">Underlying type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">r</code></td>
<td align="left">An instance of type R</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">c, c1, c2</code></td>
<td align="left">an instance of checked_result&lt;R&gt;</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t</code></td>
<td align="left">an instance of checked_result&lt;T&gt; for some type T not
            necessarily the same as R</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">e</code></td>
<td align="left">An instance of type <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">msg</code></td>
<td align="left">An instance of type const char *</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">OS</code></td>
<td align="left">A type convertible to <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">std::basic_ostream</code></a>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">os</code></td>
<td align="left">An instance of type convertible to <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">std::basic_ostream</code></a>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202541568"></a>Template Parameters</h4></div></div></div>
<p>R must model the type requirements of <a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a></p>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Parameter</th>
<th align="left">Description</th>
</tr></thead>
<tbody><tr>
<td align="left"><code class="computeroutput">R</code></td>
<td align="left">Underlying type</td>
</tr></tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202533440"></a>Model of</h4></div></div></div>
<p><a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202531728"></a>Valid Expressions</h4></div></div></div>
<p>All expressions are <code class="computeroutput">constexpr</code>.</p>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Type</th>
<th align="left">Semantics</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">checked_result(r)</code></td>
<td align="left"><code class="computeroutput">checked_result&lt;R&gt;</code></td>
<td align="left">constructor with valid instance of R</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">checked_result&lt;R&gt;(t)</code></td>
<td align="left"><code class="computeroutput">checked_result&lt;R&gt;</code></td>
<td align="left">constructor with <code class="computeroutput">checked_result&lt;T&gt;</code>
              where T is not R. T must be convertible to R.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">checked_result(e, msg)</code></td>
<td align="left"><code class="computeroutput">checked_result&lt;R&gt;</code></td>
<td align="left">constructor with error information</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast&lt;R&gt;(c)</code></td>
<td align="left">R</td>
<td align="left">extract wrapped value - compile time error if not
              possible</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast&lt;<code class="computeroutput"><a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a></code>&gt;(c)</code></td>
<td align="left"><a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a></td>
<td align="left">extract wrapped value - may return <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a><code class="computeroutput">::success</code>
              if there is no error</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast&lt;const char *&gt;(c)</code></td>
<td align="left"><code class="computeroutput">const char *</code></td>
<td align="left">returns pointer to the included error message</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">c.exception()</code></td>
<td align="left"><code class="computeroutput">bool</code></td>
<td align="left">true if <code class="computeroutput">checked_result</code> contains an error
              condition.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist">
<tr><td>c1 &lt; c2</td></tr>
<tr><td>c1 &gt;= c2</td></tr>
<tr><td>c1 &gt; c2</td></tr>
<tr><td>c1 &lt;= c2</td></tr>
<tr><td>c1 == c2</td></tr>
<tr><td>c1 != c2</td></tr>
</table></code></td>
<td align="left"><code class="computeroutput">boost::logic::tribool</code></td>
<td align="left">compare the wrapped values of two checked_result
              instances. If the values are such that the result of such a
              comparison cannot be reasonably defined, The result of the
              comparison is
              <code class="computeroutput">boost::logic::tribool::indeterminant</code>.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist">
<tr><td>c1 + c2</td></tr>
<tr><td>c1 - c2</td></tr>
<tr><td>c1 * c2</td></tr>
<tr><td>c1 / c2</td></tr>
<tr><td>c1 % c2</td></tr>
<tr><td>c1 | c2</td></tr>
<tr><td>c1 &amp; c2</td></tr>
<tr><td>c1 ^ c2</td></tr>
<tr><td>c1 &lt;&lt; c2</td></tr>
<tr><td>c1 &gt;&gt; c2</td></tr>
</table></code></td>
<td align="left"><code class="computeroutput">checked_result&lt;R&gt;</code></td>
<td align="left">returns a new instance of
              <code class="computeroutput">checked_result&lt;R&gt;.</code>
</td>
</tr>
<tr>
<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist"><tr><td>os &lt;&lt; c</td></tr></table></code></td>
<td align="left"><code class="computeroutput">OS</code></td>
<td align="left">writes result to output stream. If the result is an error
              it writes the string corresponding to the error message.
              Otherwise, it writes the numeric value resulting from the
              operation. Returns reference to output stream.</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202483424"></a>Example of use</h4></div></div></div>
<pre class="programlisting"><span class="comment">//  Copyright (c) 2018 Robert Ramey</span>
<span class="comment">//</span>
<span class="comment">// Distributed under the Boost Software License, Version 1.0. (See</span>
<span class="comment">// accompanying file LICENSE_1_0.txt or copy at</span>
<span class="comment">// http://www.boost.org/LICENSE_1_0.txt)</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">checked_result</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">checked_result_operations</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span>
    <span class="keyword">using</span> <span class="identifier">ext_uint</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">safe_numerics</span><span class="special">::</span><span class="identifier">checked_result</span><span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">&gt;</span><span class="special">;</span>
    <span class="keyword">const</span> <span class="identifier">ext_uint</span> <span class="identifier">x</span><span class="special">{</span><span class="number">4</span><span class="special">}</span><span class="special">;</span>
    <span class="keyword">const</span> <span class="identifier">ext_uint</span> <span class="identifier">y</span><span class="special">{</span><span class="number">3</span><span class="special">}</span><span class="special">;</span>

    <span class="comment">// operation is a success!</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"success! x - y = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">x</span> <span class="special">-</span> <span class="identifier">y</span><span class="special">;</span>

    <span class="comment">// subtraction would result in -1, and invalid result for an unsigned value</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"problem: y - x = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">y</span> <span class="special">-</span> <span class="identifier">x</span><span class="special">;</span>

    <span class="keyword">const</span> <span class="identifier">ext_uint</span> <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">y</span> <span class="special">-</span> <span class="identifier">x</span><span class="special">;</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"z = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span><span class="special">;</span>
    <span class="comment">// sum of two negative overflows is a negative overflow.</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"z + z"</span> <span class="special">&lt;&lt;</span> <span class="identifier">z</span> <span class="special">+</span> <span class="identifier">z</span><span class="special">;</span>

    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202416320"></a>See Also</h4></div></div></div>
<p><a class="link" href="exception_policy.html" title="ExceptionPolicy&lt;EP&gt;">ExceptionPolicy</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130202414608"></a>Header</h4></div></div></div>
<p><a href="../include/checked_result.hpp" target="_top"><code class="computeroutput">#include
    &lt;boost/numeric/safe_numerics/checked_result.hpp&gt;</code></a></p>
<p><a href="../include/checked_result_operations.hpp" target="_top"><code class="computeroutput">#include
    &lt;boost/numeric/safe_numerics/checked_result_operations.hpp&gt;
    </code></a></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="library_implementation.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="library_implementation.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="checked_arithmetic.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>