townforge/safe_numerics
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
cc
safe_numerics/doc/html/exception_policy.html

197 lines
10 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>ExceptionPolicy&lt;EP&gt;</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="concepts.html" title="Type Requirements">
<link rel="prev" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;">
<link rel="next" href="types.html" title="Types">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="promotion_policy.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="types.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.exception_policy"></a>ExceptionPolicy&lt;EP&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="exception_policy.html#idm130203635456">Description</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm130203634048">Notation</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm130203624640">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm130203608816">dispatch&lt;EP&gt;(const safe_numerics_error &amp; e, const char *
msg)</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm130203580144">Models</a></span></dt>
<dt><span class="section"><a href="exception_policy.html#idm130203567040">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203635456"></a>Description</h4></div></div></div>
<p>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.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203634048"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><code class="computeroutput">EP</code></td>
<td align="left">A type that fulfills the requirements of an
ExceptionPolicy</td>
</tr>
<tr>
<td align="left">e</td>
<td align="left">A code from <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a>
</td>
</tr>
<tr>
<td align="left">message</td>
<td align="left">A const char * which refers to a text message about the
cause of an exception</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203624640"></a>Valid Expressions</h4></div></div></div>
<p>Whenever an operation yield an invalid result, one of the following
functions will be invoked.</p>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Value</th>
<th align="left">Invoked when:</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">EP::on_arithmetic_error(e, message)</code></td>
<td align="left">void</td>
<td align="left">The operation cannot produce valid arithmetic result such
as overflows, divide by zero, etc.</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_undefined_behavior(e,
message)</code></td>
<td align="left">void</td>
<td align="left">The result is undefined by the C++ standard</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_implementation_defined_behavior(e,
message)</code></td>
<td align="left">void</td>
<td align="left">The result depends upon implementation defined behavior
according to the C++ standard</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">EP::on_uninitialized_value(e,
message)</code></td>
<td align="left">void</td>
<td align="left">A variable is not initialized</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203608816"></a>dispatch&lt;EP&gt;(const safe_numerics_error &amp; e, const char *
msg)</h4></div></div></div>
<p>This function is used to invoke the exception handling policy for a
particular exception code.</p>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm130203607584"></a>Synopsis</h5></div></div></div>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">EP</span><span class="special">&gt;</span>
<span class="keyword">constexpr</span> <span class="keyword">void</span>
<span class="identifier">dispatch</span><span class="special">&lt;</span><span class="identifier">EP</span><span class="special">&gt;</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">safe_numerics_error</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span> <span class="special">*</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">msg</span><span class="special">)</span><span class="special">;</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm130203589824"></a>Example of use</h5></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">exception_policies</span><span class="special">.</span><span class="identifier">hpp</span><span class="string">"
dispatch&lt;boost::numeric::loose_exception_policy&gt;(
boost::numeric::safe_numerics_error::positive_overflow_error,
"</span><span class="identifier">operation</span> <span class="identifier">resulted</span> <span class="identifier">in</span> <span class="identifier">overflow</span><span class="string">"
);</span></pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203580144"></a>Models</h4></div></div></div>
<p>The library header <a href="../../include/exception_policies.hpp" target="_top"><code class="computeroutput">&lt;boost/numerics/safe_numerics/exception_policies.hpp&gt;
</code></a>contains a number of pre-made exception policies:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="computeroutput">boost::numeric::loose_exception_policy</code></p>
<p>Throw on arithmetic errors, ignore other errors. Some
applications ignore these issues and still work and we don't want to
update them.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::loose_trap_policy</code></p>
<p>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.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::strict_exception_policy</code></p>
<p>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.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::strict_trap_policy</code></p>
<p>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.</p>
</li>
<li class="listitem">
<p><code class="computeroutput">boost::numeric::default_exception_policy</code></p>
<p>Alias for <code class="computeroutput">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.</p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm130203567040"></a>Header</h4></div></div></div>
<p><a href="../../include/concept/exception_policy.hpp" target="_top"><code class="computeroutput">#include
&lt;boost/numeric/safe_numerics/concepts/exception_policy.hpp&gt;
</code></a></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="promotion_policy.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="types.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink