1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN" 3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<section id="safe_numerics.exception_policy"> 5 <title>ExceptionPolicy<EP></title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>The exception policy specifies what is to occur when a safe 13 operation cannot return a valid result. A type is an ExceptionPolicy if it 14 has functions for handling exceptional events that occur in the course of 15 safe numeric operations.</para> 16 </section> 17 18 <section> 19 <title>Notation</title> 20 21 <informaltable> 22 <tgroup cols="2" colsep="1" rowsep="1"> 23 <colspec align="left" colwidth="1*"/> 24 25 <colspec align="left" colwidth="6*"/> 26 27 <tbody> 28 <row> 29 <entry><code>EP</code></entry> 30 31 <entry>A type that fulfills the requirements of an 32 ExceptionPolicy</entry> 33 </row> 34 35 <row> 36 <entry>e</entry> 37 38 <entry>A code from <link 39 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry> 40 </row> 41 42 <row> 43 <entry>message</entry> 44 45 <entry>A const char * which refers to a text message about the 46 cause of an exception</entry> 47 </row> 48 </tbody> 49 </tgroup> 50 </informaltable> 51 </section> 52 53 <section> 54 <title>Valid Expressions</title> 55 56 <para>Whenever an operation yield an invalid result, one of the following 57 functions will be invoked.</para> 58 59 <para><informaltable> 60 <tgroup cols="3"> 61 <colspec align="left" colwidth="9*"/> 62 63 <colspec align="left" colwidth="1*"/> 64 65 <colspec align="left" colwidth="12*"/> 66 67 <thead> 68 <row> 69 <entry align="left">Expression</entry> 70 71 <entry>Return Value</entry> 72 73 <entry>Invoked when:</entry> 74 </row> 75 </thead> 76 77 <tbody> 78 <row> 79 <entry><code>EP::on_arithmetic_error(e, message)</code></entry> 80 81 <entry>void</entry> 82 83 <entry>The operation cannot produce valid arithmetic result such 84 as overflows, divide by zero, etc.</entry> 85 </row> 86 87 <row> 88 <entry><code>EP::on_undefined_behavior(e, 89 message)</code></entry> 90 91 <entry>void</entry> 92 93 <entry>The result is undefined by the C++ standard</entry> 94 </row> 95 96 <row> 97 <entry><code>EP::on_implementation_defined_behavior(e, 98 message)</code></entry> 99 100 <entry>void</entry> 101 102 <entry>The result depends upon implementation defined behavior 103 according to the C++ standard</entry> 104 </row> 105 106 <row> 107 <entry><code>EP::on_uninitialized_value(e, 108 message)</code></entry> 109 110 <entry>void</entry> 111 112 <entry>A variable is not initialized</entry> 113 </row> 114 </tbody> 115 </tgroup> 116 </informaltable></para> 117 </section> 118 119 <section> 120 <title>dispatch<EP>(const safe_numerics_error & e, const char * 121 msg)</title> 122 123 <para>This function is used to invoke the exception handling policy for a 124 particular exception code.</para> 125 126 <section> 127 <title>Synopsis</title> 128 129 <para><programlisting>template<class EP> 130constexpr void 131dispatch<EP>(const boost::numeric::safe_numerics_error & e, char const * const & msg);</programlisting></para> 132 </section> 133 134 <section> 135 <title>Example of use</title> 136 137 <programlisting>#include <boost/safe_numerics/exception_policies.hpp" 138 139dispatch<boost::numeric::loose_exception_policy>( 140 boost::numeric::safe_numerics_error::positive_overflow_error, 141 "operation resulted in overflow" 142);</programlisting> 143 </section> 144 </section> 145 146 <section> 147 <title>Models</title> 148 149 <para>The library header <ulink 150 url="../../include/boost/safe_numerics/exception_policies.hpp"><code><boost/numerics/safe_numerics/exception_policies.hpp> 151 </code></ulink>contains a number of pre-made exception policies:</para> 152 153 <itemizedlist> 154 <listitem> 155 <para><code id="">boost::numeric::loose_exception_policy</code></para> 156 157 <para>Throw on arithmetic errors, ignore other errors. Some 158 applications ignore these issues and still work and we don't want to 159 update them.</para> 160 </listitem> 161 162 <listitem> 163 <para><code 164 id="safe_numerics.exception_policies.loose_trap_policy">boost::numeric::loose_trap_policy</code></para> 165 166 <para>Same as above in that it doesn't check for various undefined 167 behaviors but traps at compile time for hard arithmetic errors. This 168 policy would be suitable for older embedded systems which depend on 169 bit manipulation operations to work.</para> 170 </listitem> 171 172 <listitem> 173 <para><code 174 id="safe_numerics.exception_policies.strict_exception_policy">boost::numeric::strict_exception_policy</code></para> 175 176 <para>Permit just about anything, throw at runtime on any kind of 177 error. Recommended for new code. Check everything at compile time if 178 possible and runtime if necessary. Trap or Throw as appropriate. 179 Should guarantee code to be portable across architectures.</para> 180 </listitem> 181 182 <listitem> 183 <para><code 184 id="safe_numerics.exception_policies.strict_trap_policy">boost::numeric::strict_trap_policy</code></para> 185 186 <para>Same as above but requires code to be written in such a way as 187 to make it impossible for errors to occur. This naturally will require 188 extra coding effort but might be justified for embedded and/or safety 189 critical systems.</para> 190 </listitem> 191 192 <listitem> 193 <para><code 194 id="safe_numerics.exception_policies.default_exception_policy">boost::numeric::default_exception_policy</code></para> 195 196 <para>Alias for <code>strict_exception_policy</code>, One would use 197 this first. After experimentation, one might switch to one of the 198 above policies or perhaps use a custom policy.</para> 199 </listitem> 200 </itemizedlist> 201 </section> 202 203 <section> 204 <title>Header</title> 205 206 <para><ulink 207 url="../../include/boost/safe_numerics/concept/exception_policy.hpp"><code>#include 208 <boost/numeric/safe_numerics/concepts/exception_policy.hpp> 209 </code></ulink></para> 210 </section> 211</section> 212