1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>exception</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="types.html" title="Types"> 9<link rel="prev" href="safe_literal.html" title="safe_signed_literal<Value, PP , EP> and safe_unsigned_literal<Value, PP, EP>"> 10<link rel="next" href="exception_policies.html" title="exception_policy<AE, IDB, UB, UV>"> 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="safe_literal.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="types.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="exception_policies.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="safe_numerics.exception"></a>exception</h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="exception.html#idm130203013808">Description</a></span></dt> 25<dt><span class="section"><a href="exception.html#safe_numerics.safe_numerics_error">enum class safe_numerics_error</a></span></dt> 26<dt><span class="section"><a href="exception.html#idm130202982864">enum class safe_numerics_actions</a></span></dt> 27<dt><span class="section"><a href="exception.html#idm130202959008">See Also</a></span></dt> 28<dt><span class="section"><a href="exception.html#idm130202954976">Header</a></span></dt> 29</dl></div> 30<div class="section"> 31<div class="titlepage"><div><div><h4 class="title"> 32<a name="idm130203013808"></a>Description</h4></div></div></div> 33<p>Here we describe the data types used to refer to exceptional 34 conditions which might occur. Note that when we use the word "exception", 35 we don't mean the C++ term which refers to a data type, but rather the 36 colloquial sense of a anomaly, irregularity, deviation, special case, 37 isolated example, peculiarity, abnormality, oddity; misfit, aberration or 38 out of the ordinary occurrence. This concept of "exception" is more 39 complex that one would think and hence is not manifested by a single 40 simple type. A small number of types work together to implement this 41 concept within the library.</p> 42<p>We've leveraged on the <a href="http://en.cppreference.com/w/cpp/error/error_code" target="_top">std::error_code</a> 43 which is part of the standard library. We don't use all the facilities 44 that it offers so it's not an exact match, but it's useful and works for 45 our purposes.</p> 46</div> 47<div class="section"> 48<div class="titlepage"><div><div><h4 class="title"> 49<a name="safe_numerics.safe_numerics_error"></a>enum class safe_numerics_error</h4></div></div></div> 50<p>The following values are those which a numeric result might return. 51 They resemble the standard error codes used by C++ standard exceptions. 52 This resemblance is coincidental and they are wholly unrelated to any 53 codes of similar names. The reason for the resemblance is that the library 54 started it's development using the standard library codes. But as 55 development progressed it became clear that the original codes weren't 56 sufficient so now they stand on their own. Here are a list of error codes. 57 The description of what they mean is</p> 58<div class="informaltable"><table class="table"> 59<colgroup> 60<col align="left"> 61<col align="left"> 62</colgroup> 63<thead><tr> 64<th align="left">Symbol</th> 65<th align="left">Description</th> 66</tr></thead> 67<tbody> 68<tr> 69<td align="left"><code class="computeroutput">success</code></td> 70<td align="left">successful operation - no error returned</td> 71</tr> 72<tr> 73<td align="left"><code class="computeroutput">positive_overflow_error</code></td> 74<td align="left">A positive number is too large to be represented by the 75 data type</td> 76</tr> 77<tr> 78<td align="left"><code class="computeroutput">negative_overflow_error</code></td> 79<td align="left">The absolute value of a negative number is too large to 80 be represented by the data type.</td> 81</tr> 82<tr> 83<td align="left"><code class="computeroutput">domain_error</code></td> 84<td align="left">the result of an operation is outside the legal range of 85 the result.</td> 86</tr> 87<tr> 88<td align="left"><code class="computeroutput">range_error</code></td> 89<td align="left">an argument to a function or operator is outside the 90 legal range - e.g. sqrt(-1).</td> 91</tr> 92<tr> 93<td align="left"><code class="computeroutput">precision_overflow_error</code></td> 94<td align="left">precision was lost in the course of executing the 95 operation.</td> 96</tr> 97<tr> 98<td align="left"><code class="computeroutput">underflow_error</code></td> 99<td align="left">A number is too close to zero to be represented by the 100 data type.</td> 101</tr> 102<tr> 103<td align="left"><code class="computeroutput">uninitialized_value</code></td> 104<td align="left">According to the C++ standard, the result may be defined 105 by the application. e.g. 16 >> 10 will result the expected 106 result of 0 on most machines.</td> 107</tr> 108</tbody> 109</table></div> 110<p>The above listed codes can be transformed to a instance of type 111 <a href="http://en.cppreference.com/w/cpp/error/error_code" target="_top"><code class="computeroutput">std::error_code</code></a> 112 with the function:</p> 113<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">make_error_code</span><span class="special">(</span><span class="identifier">safe_numerics_error</span> <span class="identifier">e</span><span class="special">)</span></pre> 114<p>This object can be</p> 115</div> 116<div class="section"> 117<div class="titlepage"><div><div><h4 class="title"> 118<a name="idm130202982864"></a>enum class safe_numerics_actions</h4></div></div></div> 119<p>The above error codes are classified into groups according to how 120 such exceptions should be handled. The following table shows the possible 121 actions that an error could be mapped to.</p> 122<div class="informaltable"><table class="table"> 123<colgroup> 124<col align="left"> 125<col align="left"> 126</colgroup> 127<thead><tr> 128<th align="left">Symbol</th> 129<th align="left">Description</th> 130</tr></thead> 131<tbody> 132<tr> 133<td align="left"><code class="computeroutput">no_action</code></td> 134<td align="left">successful operation - no action action required</td> 135</tr> 136<tr> 137<td align="left"><code class="computeroutput">uninitialized_value</code></td> 138<td align="left">report attempt to use an uninitialized value - not 139 currently used</td> 140</tr> 141<tr> 142<td align="left"><code class="computeroutput">arithmetic_error</code></td> 143<td align="left">report an arithmetic error</td> 144</tr> 145<tr> 146<td align="left"><code class="computeroutput">implementation_defined_behavior</code></td> 147<td align="left">report an operation which the C++ standard permits but 148 fails to specify</td> 149</tr> 150<tr> 151<td align="left"><code class="computeroutput">undefined_behavior</code></td> 152<td align="left">report an operation whose result is undefined by the C++ 153 standard.</td> 154</tr> 155</tbody> 156</table></div> 157<p>Translation of a <code class="computeroutput">safe_numerics_error</code> into the 158 corresponding <code class="computeroutput">safe_numerics_action</code> can be accomplished with 159 the following function:</p> 160<pre class="programlisting"><span class="keyword">constexpr</span> <span class="keyword">enum</span> <span class="identifier">safe_numerics_actions</span> 161<span class="identifier">make_safe_numerics_action</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">safe_numerics_error</span> <span class="special">&</span> <span class="identifier">e</span><span class="special">)</span><span class="special">;</span></pre> 162</div> 163<div class="section"> 164<div class="titlepage"><div><div><h4 class="title"> 165<a name="idm130202959008"></a>See Also</h4></div></div></div> 166<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 167<li class="listitem"><p><a href="http://en.cppreference.com/w/cpp/error" target="_top">C++ Standard 168 Library version</a> The C++ standard error handling 169 utilities.</p></li> 170<li class="listitem"><p><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html" target="_top">Thinking 171 Asynchronously in C++</a> Another essential reference on the 172 design and usage of the error_code</p></li> 173</ul></div> 174</div> 175<div class="section"> 176<div class="titlepage"><div><div><h4 class="title"> 177<a name="idm130202954976"></a>Header</h4></div></div></div> 178<p><a href="../../include/exception.hpp" target="_top"><code class="computeroutput">#include 179 <boost/numeric/safe_numerics/exception.hpp></code></a></p> 180</div> 181</div> 182<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 183<td align="left"></td> 184<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 185 Software License</a></p> 186</div></td> 187</tr></table> 188<hr> 189<div class="spirit-nav"> 190<a accesskey="p" href="safe_literal.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="types.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="exception_policies.html"><img src="images/next.png" alt="Next"></a> 191</div> 192</body> 193</html> 194
