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"> 5 <title>exception</title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>Here we describe the data types used to refer to exceptional 13 conditions which might occur. Note that when we use the word "exception", 14 we don't mean the C++ term which refers to a data type, but rather the 15 colloquial sense of a anomaly, irregularity, deviation, special case, 16 isolated example, peculiarity, abnormality, oddity; misfit, aberration or 17 out of the ordinary occurrence. This concept of "exception" is more 18 complex that one would think and hence is not manifested by a single 19 simple type. A small number of types work together to implement this 20 concept within the library.</para> 21 22 <para>We've leveraged on the <ulink 23 url="http://en.cppreference.com/w/cpp/error/error_code">std::error_code</ulink> 24 which is part of the standard library. We don't use all the facilities 25 that it offers so it's not an exact match, but it's useful and works for 26 our purposes.</para> 27 </section> 28 29 <section id="safe_numerics.safe_numerics_error"> 30 <title>enum class safe_numerics_error</title> 31 32 <para>The following values are those which a numeric result might return. 33 They resemble the standard error codes used by C++ standard exceptions. 34 This resemblance is coincidental and they are wholly unrelated to any 35 codes of similar names. The reason for the resemblance is that the library 36 started it's development using the standard library codes. But as 37 development progressed it became clear that the original codes weren't 38 sufficient so now they stand on their own. Here are a list of error codes. 39 The description of what they mean is</para> 40 41 <para><informaltable> 42 <tgroup cols="2"> 43 <colspec align="left" colwidth="1*"/> 44 45 <colspec align="left" colwidth="3*"/> 46 47 <thead> 48 <row> 49 <entry align="left">Symbol</entry> 50 51 <entry align="left">Description</entry> 52 </row> 53 </thead> 54 55 <tbody> 56 <row> 57 <entry><code>success</code></entry> 58 59 <entry>successful operation - no error returned</entry> 60 </row> 61 62 <row> 63 <entry><code>positive_overflow_error</code></entry> 64 65 <entry>A positive number is too large to be represented by the 66 data type</entry> 67 </row> 68 69 <row> 70 <entry><code>negative_overflow_error</code></entry> 71 72 <entry>The absolute value of a negative number is too large to 73 be represented by the data type.</entry> 74 </row> 75 76 <row> 77 <entry><code>domain_error</code></entry> 78 79 <entry>the result of an operation is outside the legal range of 80 the result.</entry> 81 </row> 82 83 <row> 84 <entry><code>range_error</code></entry> 85 86 <entry>an argument to a function or operator is outside the 87 legal range - e.g. sqrt(-1).</entry> 88 </row> 89 90 <row> 91 <entry><code>precision_overflow_error</code></entry> 92 93 <entry>precision was lost in the course of executing the 94 operation.</entry> 95 </row> 96 97 <row> 98 <entry><code>underflow_error</code></entry> 99 100 <entry>A number is too close to zero to be represented by the 101 data type.</entry> 102 </row> 103 104 <row> 105 <entry><code>uninitialized_value</code></entry> 106 107 <entry>According to the C++ standard, the result may be defined 108 by the application. e.g. 16 >> 10 will result the expected 109 result of 0 on most machines.</entry> 110 </row> 111 </tbody> 112 </tgroup> 113 </informaltable></para> 114 115 <para>The above listed codes can be transformed to a instance of type 116 <ulink 117 url="http://en.cppreference.com/w/cpp/error/error_code"><code>std::error_code</code></ulink> 118 with the function:</para> 119 120 <para><programlisting>std::error_code make_error_code(safe_numerics_error e)</programlisting></para> 121 122 <para>This object can be</para> 123 </section> 124 125 <section> 126 <title>enum class safe_numerics_actions</title> 127 128 <para>The above error codes are classified into groups according to how 129 such exceptions should be handled. The following table shows the possible 130 actions that an error could be mapped to.</para> 131 132 <informaltable> 133 <tgroup cols="2"> 134 <colspec align="left" colwidth="1*"/> 135 136 <colspec align="left" colwidth="3*"/> 137 138 <thead> 139 <row> 140 <entry align="left">Symbol</entry> 141 142 <entry align="left">Description</entry> 143 </row> 144 </thead> 145 146 <tbody> 147 <row> 148 <entry><code>no_action</code></entry> 149 150 <entry>successful operation - no action action required</entry> 151 </row> 152 153 <row> 154 <entry><code>uninitialized_value</code></entry> 155 156 <entry>report attempt to use an uninitialized value - not 157 currently used</entry> 158 </row> 159 160 <row> 161 <entry><code>arithmetic_error</code></entry> 162 163 <entry>report an arithmetic error</entry> 164 </row> 165 166 <row> 167 <entry><code>implementation_defined_behavior</code></entry> 168 169 <entry>report an operation which the C++ standard permits but 170 fails to specify</entry> 171 </row> 172 173 <row> 174 <entry><code>undefined_behavior</code></entry> 175 176 <entry>report an operation whose result is undefined by the C++ 177 standard.</entry> 178 </row> 179 </tbody> 180 </tgroup> 181 </informaltable> 182 183 <para>Translation of a <code>safe_numerics_error</code> into the 184 corresponding <code>safe_numerics_action</code> can be accomplished with 185 the following function:</para> 186 187 <para><programlisting>constexpr enum safe_numerics_actions 188make_safe_numerics_action(const safe_numerics_error & e);</programlisting></para> 189 </section> 190 191 <section> 192 <title>See Also</title> 193 194 <itemizedlist> 195 <listitem> 196 <para><ulink url="http://en.cppreference.com/w/cpp/error">C++ Standard 197 Library version</ulink> The C++ standard error handling 198 utilities.</para> 199 </listitem> 200 201 <listitem> 202 <para><ulink 203 url="http://blog.think-async.com/2010/04/system-error-support-in-c0x-part-1.html">Thinking 204 Asynchronously in C++</ulink> Another essential reference on the 205 design and usage of the error_code</para> 206 </listitem> 207 </itemizedlist> 208 </section> 209 210 <section> 211 <title>Header</title> 212 213 <para><ulink 214 url="../../include/boost/safe_numerics/exception.hpp"><code>#include 215 <boost/numeric/safe_numerics/exception.hpp></code></ulink></para> 216 </section> 217</section> 218