123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193 |
- <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>
|