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_numeric.exception_policies"> 5 <title>exception_policy<AE, IDB, UB, UV></title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>Create a valid exception policy from 4 function objects. This 13 specifies the actions to be taken for different types of invalid 14 results.</para> 15 </section> 16 17 <section> 18 <title>Template Parameters</title> 19 20 <informaltable> 21 <tgroup cols="3"> 22 <colspec align="left" colwidth="1*"/> 23 24 <colspec align="left" colwidth="6*"/> 25 26 <colspec align="left" colwidth="9*"/> 27 28 <thead> 29 <row> 30 <entry align="left">Parameter</entry> 31 32 <entry align="left">Type Requirements</entry> 33 34 <entry>Invoked when:</entry> 35 </row> 36 </thead> 37 38 <tbody> 39 <row> 40 <entry><code>AE</code></entry> 41 42 <entry>Function object callable with the expression AE(e, 43 message)</entry> 44 45 <entry><para>The operation cannot produce valid arithmetic result 46 such as overflows, divide by zero, etc.</para></entry> 47 </row> 48 49 <row> 50 <entry><code>UB</code></entry> 51 52 <entry>Function object callable with the expression UB(e, 53 message)</entry> 54 55 <entry><para>The result is undefined by the C++ 56 standard</para></entry> 57 </row> 58 59 <row> 60 <entry><code>IDB</code></entry> 61 62 <entry>Function object callable with the expression IDB(e,</entry> 63 64 <entry><para>The result depends upon implementation defined 65 behavior according to the C++ standard</para></entry> 66 </row> 67 68 <row> 69 <entry><code>UV</code></entry> 70 71 <entry>Function object callable with the expression UV(e, 72 message)</entry> 73 74 <entry><para>A variable is not initialized</para></entry> 75 </row> 76 </tbody> 77 </tgroup> 78 </informaltable> 79 </section> 80 81 <section> 82 <title>Model of</title> 83 84 <para><link 85 linkend="safe_numerics.promotion_policy">ExceptionPolicy</link></para> 86 </section> 87 88 <section> 89 <title>Inherited Valid Expressions</title> 90 91 <para>This class implements all the valid operations from the type 92 requirements <link 93 linkend="safe_numerics.promotion_policy">ExceptionPolicy</link>. Aside 94 from these, there are no other operations implemented.</para> 95 </section> 96 97 <section> 98 <title>Function Objects</title> 99 100 <para>In order to create an exception policy, one needs some function 101 objects. The library includes some appropriate examples of these:</para> 102 103 <informaltable> 104 <tgroup cols="2"> 105 <colspec align="left" colwidth="1*"/> 106 107 <colspec align="left" colwidth="3*"/> 108 109 <thead> 110 <row> 111 <entry align="left">Name</entry> 112 113 <entry align="left">Description</entry> 114 </row> 115 </thead> 116 117 <tbody> 118 <row> 119 <entry><code>ignore_exception</code></entry> 120 121 <entry>Ignore any runtime exception and just return - thus 122 propagating the error. This is what would happen with unsafe data 123 types</entry> 124 </row> 125 126 <row> 127 <entry><code>throw_exception</code></entry> 128 129 <entry>throw an exception of type std::system_error</entry> 130 </row> 131 132 <row> 133 <entry><code>trap_exception</code></entry> 134 135 <entry>Invoke a function which is undefined. Compilers will 136 include this function if and only if there is a possibility of a 137 runtime error. Conversely, This will create a compile time error 138 if there is any possibility that the operation will fail at 139 runtime. Use the action to guarantee that your application will 140 never produce an invalid result. Any operation invoke</entry> 141 </row> 142 </tbody> 143 </tgroup> 144 </informaltable> 145 146 <para>But of course one is free to provide his own. Here is an example of 147 a function object which would could be used exception conditions.</para> 148 149 <programlisting>// log an exception condition but continue processing as though nothing has happened 150// this would emulate the behavior of an unsafe type. 151struct log_runtime_exception { 152 log_runtime_exception(const safe_numerics_error & e, const char * message){ 153 std::cout << "Caught system_error with code " << e.code() 154 << " meaning " << e.what() << '\n'; 155 } 156}; 157</programlisting> 158 </section> 159 160 <section> 161 <title>Policies Provided by the library</title> 162 163 <para>The above function object can be composed into an exception policy 164 by this class. The library provides common policies all ready to use. In 165 the table below, the word "loose" is used to indicate that implementation 166 defined and undefined behavior is not considered an exceptional condition, 167 while "strict" means the opposite. The word "exception" means that a 168 runtime exception will be thrown. The word "trap" means that the mere 169 possibility of an error condition will result in a compile time 170 error.</para> 171 172 <para><informaltable> 173 <tgroup cols="2"> 174 <colspec align="left" colwidth="1*"/> 175 176 <colspec align="left" colwidth="3*"/> 177 178 <thead> 179 <row> 180 <entry align="left">Name</entry> 181 182 <entry align="left">Description</entry> 183 </row> 184 </thead> 185 186 <tbody> 187 <row> 188 <entry 189 id="safe_numerics.exception_policies.loose_exception_policy"><link 190 linkend="safe_numerics.exception_policies.loose_exception_policy">loose_exception_policy</link></entry> 191 192 <entry>Throws runtime exception on any arithmetic error. 193 Undefined and implementation defined behavior is permitted as 194 long as it does not produce an arithmetic error.</entry> 195 </row> 196 197 <row> 198 <entry 199 id="safe_numerics.exception_policies.loose_trap_policy"><code><link 200 linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy</link></code></entry> 201 202 <entry>Invoke a compile time error in any case where it's 203 possible to result in an arithmetic error.</entry> 204 </row> 205 206 <row> 207 <entry 208 id="safe_numerics.exception_policies.strict_exception_policy"><code><link 209 linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry> 210 211 <entry>Throws runtime exception on any arithmetic error. Any 212 undefined or implementation defined behavior also results in 213 throwing an exception.</entry> 214 </row> 215 216 <row> 217 <entry 218 id="safe_numerics.exception_policies.strict_trap_policy"><code><link 219 linkend="safe_numerics.exception_policies.strict_trap_policy">strict_trap_policy</link></code></entry> 220 221 <entry>Invoke a compile time error in any case where it's 222 possible to result in an arithmetic error, undefined behavior or 223 implementation defined behavior</entry> 224 </row> 225 226 <row> 227 <entry 228 id="safe_numerics.exception_policies.default_exception_policy"><code><link 229 linkend="safe_numerics.exception_policies.default_exception_policy">default_exception_policy</link></code></entry> 230 231 <entry>an alias for <code><link 232 linkend="safe_numerics.exception_policies.strict_exception_policy">strict_exception_policy</link></code></entry> 233 </row> 234 </tbody> 235 </tgroup> 236 </informaltable>If none of the above suit your needs, you're free to 237 create your own. Here is one where use the logging function object defined 238 above as a component in a loose exception policy which logs any arithmetic 239 errors and ignores any other types of errors.</para> 240 241 <para><programlisting>// logging policy 242// log arithmetic errors but ignore them and continue to execute 243// implementation defined and undefined behavior is just executed 244// without logging. 245 246using logging_exception_policy = exception_policy< 247 log_runtime_exception, // arithmetic error 248 ignore_exception, // implementation defined behavior 249 ignore_exception, // undefined behavior 250 ignore_exception // uninitialized value 251>; 252</programlisting></para> 253 </section> 254 255 <section> 256 <title>Header</title> 257 258 <para><ulink 259 url="../../include/boost/safe_numerics/concept/exception_policy.hpp"><code>#include 260 <boost/numeric/safe_numerics/concept/exception_policy.hpp></code></ulink></para> 261 </section> 262</section> 263