EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/safe_numerics/doc/boostbook/exception.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 &gt;&gt; 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 &amp; 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
    &lt;boost/numeric/safe_numerics/exception.hpp&gt;</code></ulink></para>
  </section>
</section>