218 lines
7.0 KiB
XML
218 lines
7.0 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<section id="safe_numerics.exception">
|
|
<title>exception</title>
|
|
|
|
<?dbhtml stop-chunking?>
|
|
|
|
<section>
|
|
<title>Description</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>We've leveraged on the <ulink
|
|
url="http://en.cppreference.com/w/cpp/error/error_code">std::error_code</ulink>
|
|
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.</para>
|
|
</section>
|
|
|
|
<section id="safe_numerics.safe_numerics_error">
|
|
<title>enum class safe_numerics_error</title>
|
|
|
|
<para>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</para>
|
|
|
|
<para><informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Symbol</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>success</code></entry>
|
|
|
|
<entry>successful operation - no error returned</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>positive_overflow_error</code></entry>
|
|
|
|
<entry>A positive number is too large to be represented by the
|
|
data type</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>negative_overflow_error</code></entry>
|
|
|
|
<entry>The absolute value of a negative number is too large to
|
|
be represented by the data type.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>domain_error</code></entry>
|
|
|
|
<entry>the result of an operation is outside the legal range of
|
|
the result.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>range_error</code></entry>
|
|
|
|
<entry>an argument to a function or operator is outside the
|
|
legal range - e.g. sqrt(-1).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>precision_overflow_error</code></entry>
|
|
|
|
<entry>precision was lost in the course of executing the
|
|
operation.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>underflow_error</code></entry>
|
|
|
|
<entry>A number is too close to zero to be represented by the
|
|
data type.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>uninitialized_value</code></entry>
|
|
|
|
<entry>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.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable></para>
|
|
|
|
<para>The above listed codes can be transformed to a instance of type
|
|
<ulink
|
|
url="http://en.cppreference.com/w/cpp/error/error_code"><code>std::error_code</code></ulink>
|
|
with the function:</para>
|
|
|
|
<para><programlisting>std::error_code make_error_code(safe_numerics_error e)</programlisting></para>
|
|
|
|
<para>This object can be</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>enum class safe_numerics_actions</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Symbol</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>no_action</code></entry>
|
|
|
|
<entry>successful operation - no action action required</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>uninitialized_value</code></entry>
|
|
|
|
<entry>report attempt to use an uninitialized value - not
|
|
currently used</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>arithmetic_error</code></entry>
|
|
|
|
<entry>report an arithmetic error</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>implementation_defined_behavior</code></entry>
|
|
|
|
<entry>report an operation which the C++ standard permits but
|
|
fails to specify</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>undefined_behavior</code></entry>
|
|
|
|
<entry>report an operation whose result is undefined by the C++
|
|
standard.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Translation of a <code>safe_numerics_error</code> into the
|
|
corresponding <code>safe_numerics_action</code> can be accomplished with
|
|
the following function:</para>
|
|
|
|
<para><programlisting>constexpr enum safe_numerics_actions
|
|
make_safe_numerics_action(const safe_numerics_error & e);</programlisting></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>See Also</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><ulink url="http://en.cppreference.com/w/cpp/error">C++ Standard
|
|
Library version</ulink> The C++ standard error handling
|
|
utilities.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink
|
|
url="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html">Thinking
|
|
Asynchronously in C++</ulink> Another essential reference on the
|
|
design and usage of the error_code</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Header</title>
|
|
|
|
<para><ulink
|
|
url="../../include/boost/safe_numerics/exception.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/exception.hpp></code></ulink></para>
|
|
</section>
|
|
</section>
|