123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211 |
- <?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_policy">
- <title>ExceptionPolicy<EP></title>
- <?dbhtml stop-chunking?>
- <section>
- <title>Description</title>
- <para>The exception policy specifies what is to occur when a safe
- operation cannot return a valid result. A type is an ExceptionPolicy if it
- has functions for handling exceptional events that occur in the course of
- safe numeric operations.</para>
- </section>
- <section>
- <title>Notation</title>
- <informaltable>
- <tgroup cols="2" colsep="1" rowsep="1">
- <colspec align="left" colwidth="1*"/>
- <colspec align="left" colwidth="6*"/>
- <tbody>
- <row>
- <entry><code>EP</code></entry>
- <entry>A type that fulfills the requirements of an
- ExceptionPolicy</entry>
- </row>
- <row>
- <entry>e</entry>
- <entry>A code from <link
- linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry>
- </row>
- <row>
- <entry>message</entry>
- <entry>A const char * which refers to a text message about the
- cause of an exception</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section>
- <title>Valid Expressions</title>
- <para>Whenever an operation yield an invalid result, one of the following
- functions will be invoked.</para>
- <para><informaltable>
- <tgroup cols="3">
- <colspec align="left" colwidth="9*"/>
- <colspec align="left" colwidth="1*"/>
- <colspec align="left" colwidth="12*"/>
- <thead>
- <row>
- <entry align="left">Expression</entry>
- <entry>Return Value</entry>
- <entry>Invoked when:</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><code>EP::on_arithmetic_error(e, message)</code></entry>
- <entry>void</entry>
- <entry>The operation cannot produce valid arithmetic result such
- as overflows, divide by zero, etc.</entry>
- </row>
- <row>
- <entry><code>EP::on_undefined_behavior(e,
- message)</code></entry>
- <entry>void</entry>
- <entry>The result is undefined by the C++ standard</entry>
- </row>
- <row>
- <entry><code>EP::on_implementation_defined_behavior(e,
- message)</code></entry>
- <entry>void</entry>
- <entry>The result depends upon implementation defined behavior
- according to the C++ standard</entry>
- </row>
- <row>
- <entry><code>EP::on_uninitialized_value(e,
- message)</code></entry>
- <entry>void</entry>
- <entry>A variable is not initialized</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
- </section>
- <section>
- <title>dispatch<EP>(const safe_numerics_error & e, const char *
- msg)</title>
- <para>This function is used to invoke the exception handling policy for a
- particular exception code.</para>
- <section>
- <title>Synopsis</title>
- <para><programlisting>template<class EP>
- constexpr void
- dispatch<EP>(const boost::numeric::safe_numerics_error & e, char const * const & msg);</programlisting></para>
- </section>
- <section>
- <title>Example of use</title>
- <programlisting>#include <boost/safe_numerics/exception_policies.hpp"
- dispatch<boost::numeric::loose_exception_policy>(
- boost::numeric::safe_numerics_error::positive_overflow_error,
- "operation resulted in overflow"
- );</programlisting>
- </section>
- </section>
- <section>
- <title>Models</title>
- <para>The library header <ulink
- url="../../include/boost/safe_numerics/exception_policies.hpp"><code><boost/numerics/safe_numerics/exception_policies.hpp>
- </code></ulink>contains a number of pre-made exception policies:</para>
- <itemizedlist>
- <listitem>
- <para><code id="">boost::numeric::loose_exception_policy</code></para>
- <para>Throw on arithmetic errors, ignore other errors. Some
- applications ignore these issues and still work and we don't want to
- update them.</para>
- </listitem>
- <listitem>
- <para><code
- id="safe_numerics.exception_policies.loose_trap_policy">boost::numeric::loose_trap_policy</code></para>
- <para>Same as above in that it doesn't check for various undefined
- behaviors but traps at compile time for hard arithmetic errors. This
- policy would be suitable for older embedded systems which depend on
- bit manipulation operations to work.</para>
- </listitem>
- <listitem>
- <para><code
- id="safe_numerics.exception_policies.strict_exception_policy">boost::numeric::strict_exception_policy</code></para>
- <para>Permit just about anything, throw at runtime on any kind of
- error. Recommended for new code. Check everything at compile time if
- possible and runtime if necessary. Trap or Throw as appropriate.
- Should guarantee code to be portable across architectures.</para>
- </listitem>
- <listitem>
- <para><code
- id="safe_numerics.exception_policies.strict_trap_policy">boost::numeric::strict_trap_policy</code></para>
- <para>Same as above but requires code to be written in such a way as
- to make it impossible for errors to occur. This naturally will require
- extra coding effort but might be justified for embedded and/or safety
- critical systems.</para>
- </listitem>
- <listitem>
- <para><code
- id="safe_numerics.exception_policies.default_exception_policy">boost::numeric::default_exception_policy</code></para>
- <para>Alias for <code>strict_exception_policy</code>, One would use
- this first. After experimentation, one might switch to one of the
- above policies or perhaps use a custom policy.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Header</title>
- <para><ulink
- url="../../include/boost/safe_numerics/concept/exception_policy.hpp"><code>#include
- <boost/numeric/safe_numerics/concepts/exception_policy.hpp>
- </code></ulink></para>
- </section>
- </section>
|