123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217 |
- <?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>
|