194 lines
9.8 KiB
HTML
194 lines
9.8 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
|
<title>exception</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="types.html" title="Types">
|
|
<link rel="prev" href="safe_literal.html" title="safe_signed_literal<Value, PP , EP> and safe_unsigned_literal<Value, PP, EP>">
|
|
<link rel="next" href="exception_policies.html" title="exception_policy<AE, IDB, UB, UV>">
|
|
</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="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>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h3 class="title">
|
|
<a name="safe_numerics.exception"></a>exception</h3></div></div></div>
|
|
<div class="toc"><dl class="toc">
|
|
<dt><span class="section"><a href="exception.html#idm130203013808">Description</a></span></dt>
|
|
<dt><span class="section"><a href="exception.html#safe_numerics.safe_numerics_error">enum class safe_numerics_error</a></span></dt>
|
|
<dt><span class="section"><a href="exception.html#idm130202982864">enum class safe_numerics_actions</a></span></dt>
|
|
<dt><span class="section"><a href="exception.html#idm130202959008">See Also</a></span></dt>
|
|
<dt><span class="section"><a href="exception.html#idm130202954976">Header</a></span></dt>
|
|
</dl></div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm130203013808"></a>Description</h4></div></div></div>
|
|
<p>Here we describe the data types used to refer to exceptional
|
|
conditions which might occur. Note that when we use the word "exception",
|
|
we don't mean the C++ term which refers to a data type, but rather the
|
|
colloquial sense of a anomaly, irregularity, deviation, special case,
|
|
isolated example, peculiarity, abnormality, oddity; misfit, aberration or
|
|
out of the ordinary occurrence. This concept of "exception" is more
|
|
complex that one would think and hence is not manifested by a single
|
|
simple type. A small number of types work together to implement this
|
|
concept within the library.</p>
|
|
<p>We've leveraged on the <a href="http://en.cppreference.com/w/cpp/error/error_code" target="_top">std::error_code</a>
|
|
which is part of the standard library. We don't use all the facilities
|
|
that it offers so it's not an exact match, but it's useful and works for
|
|
our purposes.</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="safe_numerics.safe_numerics_error"></a>enum class safe_numerics_error</h4></div></div></div>
|
|
<p>The following values are those which a numeric result might return.
|
|
They resemble the standard error codes used by C++ standard exceptions.
|
|
This resemblance is coincidental and they are wholly unrelated to any
|
|
codes of similar names. The reason for the resemblance is that the library
|
|
started it's development using the standard library codes. But as
|
|
development progressed it became clear that the original codes weren't
|
|
sufficient so now they stand on their own. Here are a list of error codes.
|
|
The description of what they mean is</p>
|
|
<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">success</code></td>
|
|
<td align="left">successful operation - no error returned</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">positive_overflow_error</code></td>
|
|
<td align="left">A positive number is too large to be represented by the
|
|
data type</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">negative_overflow_error</code></td>
|
|
<td align="left">The absolute value of a negative number is too large to
|
|
be represented by the data type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">domain_error</code></td>
|
|
<td align="left">the result of an operation is outside the legal range of
|
|
the result.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">range_error</code></td>
|
|
<td align="left">an argument to a function or operator is outside the
|
|
legal range - e.g. sqrt(-1).</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">precision_overflow_error</code></td>
|
|
<td align="left">precision was lost in the course of executing the
|
|
operation.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">underflow_error</code></td>
|
|
<td align="left">A number is too close to zero to be represented by the
|
|
data type.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">uninitialized_value</code></td>
|
|
<td align="left">According to the C++ standard, the result may be defined
|
|
by the application. e.g. 16 >> 10 will result the expected
|
|
result of 0 on most machines.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table></div>
|
|
<p>The above listed codes can be transformed to a instance of type
|
|
<a href="http://en.cppreference.com/w/cpp/error/error_code" target="_top"><code class="computeroutput">std::error_code</code></a>
|
|
with the function:</p>
|
|
<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>
|
|
<p>This object can be</p>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm130202982864"></a>enum class safe_numerics_actions</h4></div></div></div>
|
|
<p>The above error codes are classified into groups according to how
|
|
such exceptions should be handled. The following table shows the possible
|
|
actions that an error could be mapped to.</p>
|
|
<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">no_action</code></td>
|
|
<td align="left">successful operation - no action action required</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">uninitialized_value</code></td>
|
|
<td align="left">report attempt to use an uninitialized value - not
|
|
currently used</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">arithmetic_error</code></td>
|
|
<td align="left">report an arithmetic error</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">implementation_defined_behavior</code></td>
|
|
<td align="left">report an operation which the C++ standard permits but
|
|
fails to specify</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left"><code class="computeroutput">undefined_behavior</code></td>
|
|
<td align="left">report an operation whose result is undefined by the C++
|
|
standard.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table></div>
|
|
<p>Translation of a <code class="computeroutput">safe_numerics_error</code> into the
|
|
corresponding <code class="computeroutput">safe_numerics_action</code> can be accomplished with
|
|
the following function:</p>
|
|
<pre class="programlisting"><span class="keyword">constexpr</span> <span class="keyword">enum</span> <span class="identifier">safe_numerics_actions</span>
|
|
<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>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm130202959008"></a>See Also</h4></div></div></div>
|
|
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
|
<li class="listitem"><p><a href="http://en.cppreference.com/w/cpp/error" target="_top">C++ Standard
|
|
Library version</a> The C++ standard error handling
|
|
utilities.</p></li>
|
|
<li class="listitem"><p><a href="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html" target="_top">Thinking
|
|
Asynchronously in C++</a> Another essential reference on the
|
|
design and usage of the error_code</p></li>
|
|
</ul></div>
|
|
</div>
|
|
<div class="section">
|
|
<div class="titlepage"><div><div><h4 class="title">
|
|
<a name="idm130202954976"></a>Header</h4></div></div></div>
|
|
<p><a href="../../include/exception.hpp" target="_top"><code class="computeroutput">#include
|
|
<boost/numeric/safe_numerics/exception.hpp></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 © 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="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>
|
|
</div>
|
|
</body>
|
|
</html>
|