1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>ExceptionPolicy<EP></title> 5<link rel="stylesheet" href="boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Safe Numerics"> 8<link rel="up" href="concepts.html" title="Type Requirements"> 9<link rel="prev" href="promotion_policy.html" title="PromotionPolicy<PP>"> 10<link rel="next" href="types.html" title="Types"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td> 15<td><h2>Safe Numerics</h2></td> 16</tr></table> 17<div class="spirit-nav"> 18<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> 19</div> 20<div class="section"> 21<div class="titlepage"><div><div><h3 class="title"> 22<a name="safe_numerics.exception_policy"></a>ExceptionPolicy<EP></h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="exception_policy.html#idm130203635456">Description</a></span></dt> 25<dt><span class="section"><a href="exception_policy.html#idm130203634048">Notation</a></span></dt> 26<dt><span class="section"><a href="exception_policy.html#idm130203624640">Valid Expressions</a></span></dt> 27<dt><span class="section"><a href="exception_policy.html#idm130203608816">dispatch<EP>(const safe_numerics_error & e, const char * 28 msg)</a></span></dt> 29<dt><span class="section"><a href="exception_policy.html#idm130203580144">Models</a></span></dt> 30<dt><span class="section"><a href="exception_policy.html#idm130203567040">Header</a></span></dt> 31</dl></div> 32<div class="section"> 33<div class="titlepage"><div><div><h4 class="title"> 34<a name="idm130203635456"></a>Description</h4></div></div></div> 35<p>The exception policy specifies what is to occur when a safe 36 operation cannot return a valid result. A type is an ExceptionPolicy if it 37 has functions for handling exceptional events that occur in the course of 38 safe numeric operations.</p> 39</div> 40<div class="section"> 41<div class="titlepage"><div><div><h4 class="title"> 42<a name="idm130203634048"></a>Notation</h4></div></div></div> 43<div class="informaltable"><table class="table"> 44<colgroup> 45<col align="left"> 46<col align="left"> 47</colgroup> 48<tbody> 49<tr> 50<td align="left"><code class="computeroutput">EP</code></td> 51<td align="left">A type that fulfills the requirements of an 52 ExceptionPolicy</td> 53</tr> 54<tr> 55<td align="left">e</td> 56<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> 57</td> 58</tr> 59<tr> 60<td align="left">message</td> 61<td align="left">A const char * which refers to a text message about the 62 cause of an exception</td> 63</tr> 64</tbody> 65</table></div> 66</div> 67<div class="section"> 68<div class="titlepage"><div><div><h4 class="title"> 69<a name="idm130203624640"></a>Valid Expressions</h4></div></div></div> 70<p>Whenever an operation yield an invalid result, one of the following 71 functions will be invoked.</p> 72<div class="informaltable"><table class="table"> 73<colgroup> 74<col align="left"> 75<col align="left"> 76<col align="left"> 77</colgroup> 78<thead><tr> 79<th align="left">Expression</th> 80<th align="left">Return Value</th> 81<th align="left">Invoked when:</th> 82</tr></thead> 83<tbody> 84<tr> 85<td align="left"><code class="computeroutput">EP::on_arithmetic_error(e, message)</code></td> 86<td align="left">void</td> 87<td align="left">The operation cannot produce valid arithmetic result such 88 as overflows, divide by zero, etc.</td> 89</tr> 90<tr> 91<td align="left"><code class="computeroutput">EP::on_undefined_behavior(e, 92 message)</code></td> 93<td align="left">void</td> 94<td align="left">The result is undefined by the C++ standard</td> 95</tr> 96<tr> 97<td align="left"><code class="computeroutput">EP::on_implementation_defined_behavior(e, 98 message)</code></td> 99<td align="left">void</td> 100<td align="left">The result depends upon implementation defined behavior 101 according to the C++ standard</td> 102</tr> 103<tr> 104<td align="left"><code class="computeroutput">EP::on_uninitialized_value(e, 105 message)</code></td> 106<td align="left">void</td> 107<td align="left">A variable is not initialized</td> 108</tr> 109</tbody> 110</table></div> 111</div> 112<div class="section"> 113<div class="titlepage"><div><div><h4 class="title"> 114<a name="idm130203608816"></a>dispatch<EP>(const safe_numerics_error & e, const char * 115 msg)</h4></div></div></div> 116<p>This function is used to invoke the exception handling policy for a 117 particular exception code.</p> 118<div class="section"> 119<div class="titlepage"><div><div><h5 class="title"> 120<a name="idm130203607584"></a>Synopsis</h5></div></div></div> 121<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">EP</span><span class="special">></span> 122<span class="keyword">constexpr</span> <span class="keyword">void</span> 123<span class="identifier">dispatch</span><span class="special"><</span><span class="identifier">EP</span><span class="special">></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">&</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">&</span> <span class="identifier">msg</span><span class="special">)</span><span class="special">;</span></pre> 124</div> 125<div class="section"> 126<div class="titlepage"><div><div><h5 class="title"> 127<a name="idm130203589824"></a>Example of use</h5></div></div></div> 128<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">" 129 130dispatch<boost::numeric::loose_exception_policy>( 131 boost::numeric::safe_numerics_error::positive_overflow_error, 132 "</span><span class="identifier">operation</span> <span class="identifier">resulted</span> <span class="identifier">in</span> <span class="identifier">overflow</span><span class="string">" 133);</span></pre> 134</div> 135</div> 136<div class="section"> 137<div class="titlepage"><div><div><h4 class="title"> 138<a name="idm130203580144"></a>Models</h4></div></div></div> 139<p>The library header <a href="../../include/exception_policies.hpp" target="_top"><code class="computeroutput"><boost/numerics/safe_numerics/exception_policies.hpp> 140 </code></a>contains a number of pre-made exception policies:</p> 141<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 142<li class="listitem"> 143<p><code class="computeroutput">boost::numeric::loose_exception_policy</code></p> 144<p>Throw on arithmetic errors, ignore other errors. Some 145 applications ignore these issues and still work and we don't want to 146 update them.</p> 147</li> 148<li class="listitem"> 149<p><code class="computeroutput">boost::numeric::loose_trap_policy</code></p> 150<p>Same as above in that it doesn't check for various undefined 151 behaviors but traps at compile time for hard arithmetic errors. This 152 policy would be suitable for older embedded systems which depend on 153 bit manipulation operations to work.</p> 154</li> 155<li class="listitem"> 156<p><code class="computeroutput">boost::numeric::strict_exception_policy</code></p> 157<p>Permit just about anything, throw at runtime on any kind of 158 error. Recommended for new code. Check everything at compile time if 159 possible and runtime if necessary. Trap or Throw as appropriate. 160 Should guarantee code to be portable across architectures.</p> 161</li> 162<li class="listitem"> 163<p><code class="computeroutput">boost::numeric::strict_trap_policy</code></p> 164<p>Same as above but requires code to be written in such a way as 165 to make it impossible for errors to occur. This naturally will require 166 extra coding effort but might be justified for embedded and/or safety 167 critical systems.</p> 168</li> 169<li class="listitem"> 170<p><code class="computeroutput">boost::numeric::default_exception_policy</code></p> 171<p>Alias for <code class="computeroutput">strict_exception_policy</code>, One would use 172 this first. After experimentation, one might switch to one of the 173 above policies or perhaps use a custom policy.</p> 174</li> 175</ul></div> 176</div> 177<div class="section"> 178<div class="titlepage"><div><div><h4 class="title"> 179<a name="idm130203567040"></a>Header</h4></div></div></div> 180<p><a href="../../include/concept/exception_policy.hpp" target="_top"><code class="computeroutput">#include 181 <boost/numeric/safe_numerics/concepts/exception_policy.hpp> 182 </code></a></p> 183</div> 184</div> 185<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 186<td align="left"></td> 187<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost 188 Software License</a></p> 189</div></td> 190</tr></table> 191<hr> 192<div class="spirit-nav"> 193<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> 194</div> 195</body> 196</html> 197
