1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>checked_result<R></title> 5<link rel="stylesheet" href="boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Safe Numerics"> 8<link rel="up" href="library_implementation.html" title="Library Implementation"> 9<link rel="prev" href="library_implementation.html" title="Library Implementation"> 10<link rel="next" href="checked_arithmetic.html" title="Checked Arithmetic"> 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 href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td> 15<td><h2>Safe Numerics</h2></td> 16</tr></table> 17<div class="spirit-nav"> 18<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> 19</div> 20<div class="section"> 21<div class="titlepage"><div><div><h3 class="title"> 22<a name="safenumerics.checked_result"></a>checked_result<R></h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="checked_result.html#idm130202581904">Description</a></span></dt> 25<dt><span class="section"><a href="checked_result.html#idm130202564160">Notation</a></span></dt> 26<dt><span class="section"><a href="checked_result.html#idm130202541568">Template Parameters</a></span></dt> 27<dt><span class="section"><a href="checked_result.html#idm130202533440">Model of</a></span></dt> 28<dt><span class="section"><a href="checked_result.html#idm130202531728">Valid Expressions</a></span></dt> 29<dt><span class="section"><a href="checked_result.html#idm130202483424">Example of use</a></span></dt> 30<dt><span class="section"><a href="checked_result.html#idm130202416320">See Also</a></span></dt> 31<dt><span class="section"><a href="checked_result.html#idm130202414608">Header</a></span></dt> 32</dl></div> 33<div class="section"> 34<div class="titlepage"><div><div><h4 class="title"> 35<a name="idm130202581904"></a>Description</h4></div></div></div> 36<p>checked_result is a special kind of variant class designed to hold 37 the result of some operation. It can hold either the result of the 38 operation or information on why the operation failed to produce a valid 39 result. It is similar to other types proposed for and/or included to the 40 C++ standard library or Boost such as<code class="computeroutput"> expected</code>, 41 <code class="computeroutput">variant</code>, <code class="computeroutput">optional</code> and <code class="computeroutput">outcome</code>. In 42 some circumstances it may be referred to as a "monad".</p> 43<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 44<li class="listitem"><p>All instances of <code class="computeroutput">checked_result<R></code> are 45 immutable. That is, once constructed, they cannot be altered.</p></li> 46<li class="listitem"><p>There is no default constructor.</p></li> 47<li class="listitem"><p><code class="computeroutput">checked_result<R></code> is never empty.</p></li> 48<li class="listitem"><p>Binary operations supported by type R are guaranteed to be 49 supported by checked_result<R>.</p></li> 50<li class="listitem"><p>Binary operations can be invoked on a pair of 51 <code class="computeroutput">checked_result<R></code> instances if and only if the 52 underlying type (R) is identical for both instances. They will 53 return a value of type <code class="computeroutput">checked_result<R></code>.</p></li> 54<li class="listitem"><p>Unary operations can be invoked on 55 <code class="computeroutput">checked_result<R></code> instances. They will return a 56 value of type <code class="computeroutput">checked_result<R></code>.</p></li> 57<li class="listitem"><p>Comparison operations will return a 58 <code class="computeroutput">boost::logic::tribool</code>. Other binary operations will a 59 value of the same type as the arguments.</p></li> 60</ul></div> 61<p>Think of <code class="computeroutput">checked<R></code> as an "extended" version of R 62 which can hold all the values that R can hold in addition other "special 63 values". For example, consider checked<int>.</p> 64</div> 65<div class="section"> 66<div class="titlepage"><div><div><h4 class="title"> 67<a name="idm130202564160"></a>Notation</h4></div></div></div> 68<div class="informaltable"><table class="table"> 69<colgroup> 70<col align="left"> 71<col align="left"> 72</colgroup> 73<thead><tr> 74<th align="left">Symbol</th> 75<th align="left">Description</th> 76</tr></thead> 77<tbody> 78<tr> 79<td align="left"><code class="computeroutput">R</code></td> 80<td align="left">Underlying type</td> 81</tr> 82<tr> 83<td align="left"><code class="computeroutput">r</code></td> 84<td align="left">An instance of type R</td> 85</tr> 86<tr> 87<td align="left"><code class="computeroutput">c, c1, c2</code></td> 88<td align="left">an instance of checked_result<R></td> 89</tr> 90<tr> 91<td align="left"><code class="computeroutput">t</code></td> 92<td align="left">an instance of checked_result<T> for some type T not 93 necessarily the same as R</td> 94</tr> 95<tr> 96<td align="left"><code class="computeroutput">e</code></td> 97<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> 98</td> 99</tr> 100<tr> 101<td align="left"><code class="computeroutput">msg</code></td> 102<td align="left">An instance of type const char *</td> 103</tr> 104<tr> 105<td align="left"><code class="computeroutput">OS</code></td> 106<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> 107</td> 108</tr> 109<tr> 110<td align="left"><code class="computeroutput">os</code></td> 111<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> 112</td> 113</tr> 114</tbody> 115</table></div> 116</div> 117<div class="section"> 118<div class="titlepage"><div><div><h4 class="title"> 119<a name="idm130202541568"></a>Template Parameters</h4></div></div></div> 120<p>R must model the type requirements of <a class="link" href="numeric.html" title="Numeric<T>">Numeric</a></p> 121<div class="informaltable"><table class="table"> 122<colgroup> 123<col align="left"> 124<col align="left"> 125</colgroup> 126<thead><tr> 127<th align="left">Parameter</th> 128<th align="left">Description</th> 129</tr></thead> 130<tbody><tr> 131<td align="left"><code class="computeroutput">R</code></td> 132<td align="left">Underlying type</td> 133</tr></tbody> 134</table></div> 135</div> 136<div class="section"> 137<div class="titlepage"><div><div><h4 class="title"> 138<a name="idm130202533440"></a>Model of</h4></div></div></div> 139<p><a class="link" href="numeric.html" title="Numeric<T>">Numeric</a></p> 140</div> 141<div class="section"> 142<div class="titlepage"><div><div><h4 class="title"> 143<a name="idm130202531728"></a>Valid Expressions</h4></div></div></div> 144<p>All expressions are <code class="computeroutput">constexpr</code>.</p> 145<div class="informaltable"><table class="table"> 146<colgroup> 147<col align="left"> 148<col align="left"> 149<col align="left"> 150</colgroup> 151<thead><tr> 152<th align="left">Expression</th> 153<th align="left">Return Type</th> 154<th align="left">Semantics</th> 155</tr></thead> 156<tbody> 157<tr> 158<td align="left"><code class="computeroutput">checked_result(r)</code></td> 159<td align="left"><code class="computeroutput">checked_result<R></code></td> 160<td align="left">constructor with valid instance of R</td> 161</tr> 162<tr> 163<td align="left"><code class="computeroutput">checked_result<R>(t)</code></td> 164<td align="left"><code class="computeroutput">checked_result<R></code></td> 165<td align="left">constructor with <code class="computeroutput">checked_result<T></code> 166 where T is not R. T must be convertible to R.</td> 167</tr> 168<tr> 169<td align="left"><code class="computeroutput">checked_result(e, msg)</code></td> 170<td align="left"><code class="computeroutput">checked_result<R></code></td> 171<td align="left">constructor with error information</td> 172</tr> 173<tr> 174<td align="left"><code class="computeroutput">static_cast<R>(c)</code></td> 175<td align="left">R</td> 176<td align="left">extract wrapped value - compile time error if not 177 possible</td> 178</tr> 179<tr> 180<td align="left"><code class="computeroutput">static_cast<<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>>(c)</code></td> 181<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> 182<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> 183 if there is no error</td> 184</tr> 185<tr> 186<td align="left"><code class="computeroutput">static_cast<const char *>(c)</code></td> 187<td align="left"><code class="computeroutput">const char *</code></td> 188<td align="left">returns pointer to the included error message</td> 189</tr> 190<tr> 191<td align="left"><code class="computeroutput">c.exception()</code></td> 192<td align="left"><code class="computeroutput">bool</code></td> 193<td align="left">true if <code class="computeroutput">checked_result</code> contains an error 194 condition.</td> 195</tr> 196<tr> 197<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist"> 198<tr><td>c1 < c2</td></tr> 199<tr><td>c1 >= c2</td></tr> 200<tr><td>c1 > c2</td></tr> 201<tr><td>c1 <= c2</td></tr> 202<tr><td>c1 == c2</td></tr> 203<tr><td>c1 != c2</td></tr> 204</table></code></td> 205<td align="left"><code class="computeroutput">boost::logic::tribool</code></td> 206<td align="left">compare the wrapped values of two checked_result 207 instances. If the values are such that the result of such a 208 comparison cannot be reasonably defined, The result of the 209 comparison is 210 <code class="computeroutput">boost::logic::tribool::indeterminant</code>.</td> 211</tr> 212<tr> 213<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist"> 214<tr><td>c1 + c2</td></tr> 215<tr><td>c1 - c2</td></tr> 216<tr><td>c1 * c2</td></tr> 217<tr><td>c1 / c2</td></tr> 218<tr><td>c1 % c2</td></tr> 219<tr><td>c1 | c2</td></tr> 220<tr><td>c1 & c2</td></tr> 221<tr><td>c1 ^ c2</td></tr> 222<tr><td>c1 << c2</td></tr> 223<tr><td>c1 >> c2</td></tr> 224</table></code></td> 225<td align="left"><code class="computeroutput">checked_result<R></code></td> 226<td align="left">returns a new instance of 227 <code class="computeroutput">checked_result<R>.</code> 228</td> 229</tr> 230<tr> 231<td align="left"><code class="computeroutput"><table border="0" summary="Simple list" class="simplelist"><tr><td>os << c</td></tr></table></code></td> 232<td align="left"><code class="computeroutput">OS</code></td> 233<td align="left">writes result to output stream. If the result is an error 234 it writes the string corresponding to the error message. 235 Otherwise, it writes the numeric value resulting from the 236 operation. Returns reference to output stream.</td> 237</tr> 238</tbody> 239</table></div> 240</div> 241<div class="section"> 242<div class="titlepage"><div><div><h4 class="title"> 243<a name="idm130202483424"></a>Example of use</h4></div></div></div> 244<pre class="programlisting"><span class="comment">// Copyright (c) 2018 Robert Ramey</span> 245<span class="comment">//</span> 246<span class="comment">// Distributed under the Boost Software License, Version 1.0. (See</span> 247<span class="comment">// accompanying file LICENSE_1_0.txt or copy at</span> 248<span class="comment">// http://www.boost.org/LICENSE_1_0.txt)</span> 249 250<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 251 252<span class="preprocessor">#include</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">.</span><span class="identifier">hpp</span><span class="special">></span> 253<span class="preprocessor">#include</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_operations</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 254 255<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span> 256 <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"><</span><span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">></span><span class="special">;</span> 257 <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> 258 <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> 259 260 <span class="comment">// operation is a success!</span> 261 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"success! x - y = "</span> <span class="special"><<</span> <span class="identifier">x</span> <span class="special">-</span> <span class="identifier">y</span><span class="special">;</span> 262 263 <span class="comment">// subtraction would result in -1, and invalid result for an unsigned value</span> 264 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"problem: y - x = "</span> <span class="special"><<</span> <span class="identifier">y</span> <span class="special">-</span> <span class="identifier">x</span><span class="special">;</span> 265 266 <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> 267 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"z = "</span> <span class="special"><<</span> <span class="identifier">z</span><span class="special">;</span> 268 <span class="comment">// sum of two negative overflows is a negative overflow.</span> 269 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"z + z"</span> <span class="special"><<</span> <span class="identifier">z</span> <span class="special">+</span> <span class="identifier">z</span><span class="special">;</span> 270 271 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 272<span class="special">}</span> 273</pre> 274</div> 275<div class="section"> 276<div class="titlepage"><div><div><h4 class="title"> 277<a name="idm130202416320"></a>See Also</h4></div></div></div> 278<p><a class="link" href="exception_policy.html" title="ExceptionPolicy<EP>">ExceptionPolicy</a></p> 279</div> 280<div class="section"> 281<div class="titlepage"><div><div><h4 class="title"> 282<a name="idm130202414608"></a>Header</h4></div></div></div> 283<p><a href="../include/checked_result.hpp" target="_top"><code class="computeroutput">#include 284 <boost/numeric/safe_numerics/checked_result.hpp></code></a></p> 285<p><a href="../include/checked_result_operations.hpp" target="_top"><code class="computeroutput">#include 286 <boost/numeric/safe_numerics/checked_result_operations.hpp> 287 </code></a></p> 288</div> 289</div> 290<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 291<td align="left"></td> 292<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost 293 Software License</a></p> 294</div></td> 295</tr></table> 296<hr> 297<div class="spirit-nav"> 298<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> 299</div> 300</body> 301</html> 302
