263 lines
8.9 KiB
XML
263 lines
8.9 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_numeric.exception_policies">
|
|
<title>exception_policy<AE, IDB, UB, UV></title>
|
|
|
|
<?dbhtml stop-chunking?>
|
|
|
|
<section>
|
|
<title>Description</title>
|
|
|
|
<para>Create a valid exception policy from 4 function objects. This
|
|
specifies the actions to be taken for different types of invalid
|
|
results.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Template Parameters</title>
|
|
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="6*"/>
|
|
|
|
<colspec align="left" colwidth="9*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Parameter</entry>
|
|
|
|
<entry align="left">Type Requirements</entry>
|
|
|
|
<entry>Invoked when:</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>AE</code></entry>
|
|
|
|
<entry>Function object callable with the expression AE(e,
|
|
message)</entry>
|
|
|
|
<entry><para>The operation cannot produce valid arithmetic result
|
|
such as overflows, divide by zero, etc.</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>UB</code></entry>
|
|
|
|
<entry>Function object callable with the expression UB(e,
|
|
message)</entry>
|
|
|
|
<entry><para>The result is undefined by the C++
|
|
standard</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>IDB</code></entry>
|
|
|
|
<entry>Function object callable with the expression IDB(e,</entry>
|
|
|
|
<entry><para>The result depends upon implementation defined
|
|
behavior according to the C++ standard</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>UV</code></entry>
|
|
|
|
<entry>Function object callable with the expression UV(e,
|
|
message)</entry>
|
|
|
|
<entry><para>A variable is not initialized</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Model of</title>
|
|
|
|
<para><link
|
|
linkend="safe_numerics.promotion_policy">ExceptionPolicy</link></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Inherited Valid Expressions</title>
|
|
|
|
<para>This class implements all the valid operations from the type
|
|
requirements <link
|
|
linkend="safe_numerics.promotion_policy">ExceptionPolicy</link>. Aside
|
|
from these, there are no other operations implemented.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Function Objects</title>
|
|
|
|
<para>In order to create an exception policy, one needs some function
|
|
objects. The library includes some appropriate examples of these:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Name</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>ignore_exception</code></entry>
|
|
|
|
<entry>Ignore any runtime exception and just return - thus
|
|
propagating the error. This is what would happen with unsafe data
|
|
types</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>throw_exception</code></entry>
|
|
|
|
<entry>throw an exception of type std::system_error</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>trap_exception</code></entry>
|
|
|
|
<entry>Invoke a function which is undefined. Compilers will
|
|
include this function if and only if there is a possibility of a
|
|
runtime error. Conversely, This will create a compile time error
|
|
if there is any possibility that the operation will fail at
|
|
runtime. Use the action to guarantee that your application will
|
|
never produce an invalid result. Any operation invoke</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>But of course one is free to provide his own. Here is an example of
|
|
a function object which would could be used exception conditions.</para>
|
|
|
|
<programlisting>// log an exception condition but continue processing as though nothing has happened
|
|
// this would emulate the behavior of an unsafe type.
|
|
struct log_runtime_exception {
|
|
log_runtime_exception(const safe_numerics_error & e, const char * message){
|
|
std::cout << "Caught system_error with code " << e.code()
|
|
<< " meaning " << e.what() << '\n';
|
|
}
|
|
};
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Policies Provided by the library</title>
|
|
|
|
<para>The above function object can be composed into an exception policy
|
|
by this class. The library provides common policies all ready to use. In
|
|
the table below, the word "loose" is used to indicate that implementation
|
|
defined and undefined behavior is not considered an exceptional condition,
|
|
while "strict" means the opposite. The word "exception" means that a
|
|
runtime exception will be thrown. The word "trap" means that the mere
|
|
possibility of an error condition will result in a compile time
|
|
error.</para>
|
|
|
|
<para><informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Name</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry
|
|
id="safe_numerics.exception_policies.loose_exception_policy"><link
|
|
linkend="safe_numerics.exception_policies.loose_exception_policy">loose_exception_policy</link></entry>
|
|
|
|
<entry>Throws runtime exception on any arithmetic error.
|
|
Undefined and implementation defined behavior is permitted as
|
|
long as it does not produce an arithmetic error.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry
|
|
id="safe_numerics.exception_policies.loose_trap_policy"><code><link
|
|
linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy</link></code></entry>
|
|
|
|
<entry>Invoke a compile time error in any case where it's
|
|
possible to result in an arithmetic error.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry
|
|
id="safe_numerics.exception_policies.strict_exception_policy"><code><link
|
|
linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry>
|
|
|
|
<entry>Throws runtime exception on any arithmetic error. Any
|
|
undefined or implementation defined behavior also results in
|
|
throwing an exception.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry
|
|
id="safe_numerics.exception_policies.strict_trap_policy"><code><link
|
|
linkend="safe_numerics.exception_policies.strict_trap_policy">strict_trap_policy</link></code></entry>
|
|
|
|
<entry>Invoke a compile time error in any case where it's
|
|
possible to result in an arithmetic error, undefined behavior or
|
|
implementation defined behavior</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry
|
|
id="safe_numerics.exception_policies.default_exception_policy"><code><link
|
|
linkend="safe_numerics.exception_policies.default_exception_policy">default_exception_policy</link></code></entry>
|
|
|
|
<entry>an alias for <code><link
|
|
linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>If none of the above suit your needs, you're free to
|
|
create your own. Here is one where use the logging function object defined
|
|
above as a component in a loose exception policy which logs any arithmetic
|
|
errors and ignores any other types of errors.</para>
|
|
|
|
<para><programlisting>// logging policy
|
|
// log arithmetic errors but ignore them and continue to execute
|
|
// implementation defined and undefined behavior is just executed
|
|
// without logging.
|
|
|
|
using logging_exception_policy = exception_policy<
|
|
log_runtime_exception, // arithmetic error
|
|
ignore_exception, // implementation defined behavior
|
|
ignore_exception, // undefined behavior
|
|
ignore_exception // uninitialized value
|
|
>;
|
|
</programlisting></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Header</title>
|
|
|
|
<para><ulink
|
|
url="../../include/boost/safe_numerics/concept/exception_policy.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/concept/exception_policy.hpp></code></ulink></para>
|
|
</section>
|
|
</section>
|