1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN" 3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<library dirname="safe_numerics" id="safe_numerics" last-revision="$Date" 5 name="Safe Numerics"> 6 <title>Safe Numerics</title> 7 8 <libraryinfo last-revision="January 29, 2015"> 9 <author> 10 <firstname>Robert</firstname> 11 12 <surname>Ramey</surname> 13 </author> 14 15 <copyright> 16 <year>2012-2018</year> 17 18 <holder>Robert Ramey</holder> 19 </copyright> 20 21 <legalnotice> 22 <para><ulink url="http://www.boost.org/LICENSE_1_0.txt">Subject to Boost 23 Software License</ulink></para> 24 </legalnotice> 25 26 <librarypurpose>Safe integer operations</librarypurpose> 27 28 <librarycategory name="Numerics">Numerics</librarycategory> 29 </libraryinfo> 30 31 <xi:include href="safe_introduction.xml" xpointer="element(/1)" 32 xmlns:xi="http://www.w3.org/2001/XInclude"/> 33 34 <xi:include href="tutorial.xml" xpointer="element(/1)" 35 xmlns:xi="http://www.w3.org/2001/XInclude"/> 36 37 <xi:include href="eliminate_runtime_penalty.xml" xpointer="element(/1)" 38 xmlns:xi="http://www.w3.org/2001/XInclude"/> 39 40 <section id="safe_numerics.case_studies"> 41 <title>Case Studies</title> 42 43 <xi:include href="rational.xml" xpointer="element(/1)" 44 xmlns:xi="http://www.w3.org/2001/XInclude"/> 45 46 <xi:include href="motor.xml" xpointer="element(/1)" 47 xmlns:xi="http://www.w3.org/2001/XInclude"/> 48 </section> 49 50 <xi:include href="notes.xml" xpointer="element(/1)" 51 xmlns:xi="http://www.w3.org/2001/XInclude"/> 52 53 <section id="safe_numerics.concepts"> 54 <title>Type Requirements</title> 55 56 <xi:include href="numeric_concept.xml" xpointer="element(/1)" 57 xmlns:xi="http://www.w3.org/2001/XInclude"/> 58 59 <xi:include href="integer_concept.xml" xpointer="element(/1)" 60 xmlns:xi="http://www.w3.org/2001/XInclude"/> 61 62 <xi:include href="safe_numeric_concept.xml" xpointer="element(/1)" 63 xmlns:xi="http://www.w3.org/2001/XInclude"/> 64 65 <xi:include href="promotion_policy_concept.xml" xpointer="element(/1)" 66 xmlns:xi="http://www.w3.org/2001/XInclude"/> 67 68 <xi:include href="exception_policy_concept.xml" xpointer="element(/1)" 69 xmlns:xi="http://www.w3.org/2001/XInclude"/> 70 </section> 71 72 <section id="safe_numerics.types"> 73 <title>Types</title> 74 75 <xi:include href="safe.xml" xpointer="element(/1)" 76 xmlns:xi="http://www.w3.org/2001/XInclude"/> 77 78 <xi:include href="safe_range.xml" xpointer="element(/1)" 79 xmlns:xi="http://www.w3.org/2001/XInclude"/> 80 81 <xi:include href="safe_literal.xml" xpointer="element(/1)" 82 xmlns:xi="http://www.w3.org/2001/XInclude"/> 83 84 <xi:include href="exception.xml" xpointer="element(/1)" 85 xmlns:xi="http://www.w3.org/2001/XInclude"/> 86 87 <xi:include href="exception_policy.xml" xpointer="element(/1)" 88 xmlns:xi="http://www.w3.org/2001/XInclude"/> 89 90 <section id="safe_numerics.promotion_policies"> 91 <title>Promotion Policies</title> 92 93 <xi:include href="native.xml" xpointer="element(/1)" 94 xmlns:xi="http://www.w3.org/2001/XInclude"/> 95 96 <xi:include href="automatic.xml" xpointer="element(/1)" 97 xmlns:xi="http://www.w3.org/2001/XInclude"/> 98 99 <xi:include href="cpp.xml" xpointer="element(/1)" 100 xmlns:xi="http://www.w3.org/2001/XInclude"/> 101 </section> 102 </section> 103 104 <section id="safe_numerics.exception_safety"> 105 <title>Exception Safety</title> 106 107 <para>All operations in this library are exception safe and meet the 108 strong guarantee.</para> 109 </section> 110 111 <section id="safe_numerics.library_implementation"> 112 <title>Library Implementation</title> 113 114 <para>This library should compile and run correctly on any conforming 115 C++14 compiler.</para> 116 117 <para>The Safe Numerics library is implemented in terms of some more 118 fundamental software components described here. It is not necessary to 119 know about these components to use the library. This information has been 120 included to help those who want to understand how the library works so 121 they can extend it, correct bugs in it, or understand its limitations. 122 These components are also interesting and likely useful in their own 123 right. For all these reasons, they are documented here.</para> 124 125 <para>In general terms, the library works in the following manner:</para> 126 127 <para>At compile time:</para> 128 129 <itemizedlist> 130 <listitem> 131 <para>The library defines "safe" versions of C++ primitive arithmetic 132 types such as <code>int</code>, <code>unsigned int</code>, etc.</para> 133 </listitem> 134 135 <listitem> 136 <para>Arithmetic operators are defined for these "safe" types. These 137 operators are enhanced versions of the standard C/C++ implementations. 138 These operators are declared and implemented in the files "<ulink 139 url="../../include/boost/safe_numerics/safe_base.hpp">safe_base.hpp</ulink>" 140 and "<ulink 141 url="../../include/boost/safe_numerics/safe_base_operations.hpp">safe_base_operations.hpp</ulink>".</para> 142 </listitem> 143 144 <listitem> 145 <para>For binary operators, verify that both operands have the same 146 promotion and and exception handling policies. If they don't, invoke 147 compilation error.</para> 148 </listitem> 149 150 <listitem> 151 <para>Invoke the promotion policy to determine the result type R of 152 the operation.</para> 153 </listitem> 154 155 <listitem> 156 <para>For each operand of type T retrieve the range of values from 157 <code>std::numeric_limits<T>::min()</code> and 158 <code>std::numeric_limits<T>::max()</code>. A range is a pair of 159 values representing a closed interval with a minimum and maximum 160 value.</para> 161 </listitem> 162 163 <listitem> 164 <para>These ranges are cast to equivalent values of the result type, 165 R. It's possible that values cannot be cast to the result type so the 166 result of the cast is returned as a variant type, <link 167 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>. 168 <link 169 linkend="safenumerics.checked_result"><code>checked_result<R></code></link> 170 may hold either a value of type R or a <link 171 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link> 172 value indicating why the cast could not be accomplished. Ranges are 173 represented as a pair of values of the type <link 174 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>.</para> 175 </listitem> 176 177 <listitem> 178 <para><link 179 linkend="safenumerics.checked_result"><code>checked_result<R></code></link> 180 can be considered enhanced versions of the underlying type R. 181 Operations which are legal on values of type R such as +, -, ... are 182 also legal on values of <link 183 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>. 184 The difference is that the latter can record operation failures and 185 propagate such failures to subsequent operations.<link 186 linkend="safenumerics.checked_result"><code>checked_result<R></code></link> 187 is implemented in the header file "<ulink 188 url="../../include/boost/safe_numerics/checked_result.hpp">checked_result.hpp</ulink>". 189 Operations on such types are implemented in "<ulink 190 url="../../include/boost/safe_numerics/checked_result_operations.hpp">checked_result_operations.hpp</ulink>".</para> 191 </listitem> 192 193 <listitem> 194 <para>Given the ranges of the operands, determine the range of the 195 result of the operation using compile-time interval arithmetic. The 196 <code>constexpr</code> facility of C++14 permits the range of the 197 result to be calculated at compile time. Interval arithmetic is 198 implemented in the header file "<ulink 199 url="../../include/boost/safe_numerics/interval.hpp">interval.hpp</ulink>". 200 The range of the result is also represented as a pair of values of the 201 type <link 202 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>.</para> 203 </listitem> 204 205 <listitem> 206 <para>Operations on primitives are implemented via free standing 207 functions described as <link 208 linkend="safe_numerics.checked_arithmetic">checked arithmetic</link>. 209 These operations will return instances of <link 210 linkend="safenumerics.checked_result"><code>checked_result<R></code></link> 211 .</para> 212 </listitem> 213 </itemizedlist> 214 215 <para>At run time:</para> 216 217 <itemizedlist> 218 <listitem> 219 <para>If the range of the result type includes only arithmetically 220 valid values, the operation is guaranteed to produce an arithmetically 221 correct result and no runtime checking is necessary. The operation 222 invokes the original built-in C/C++ operation and returns the result 223 value.</para> 224 </listitem> 225 226 <listitem> 227 <para>Otherwise, operands are cast to the result type, R, according to 228 the selected promotion policy. These "checked" cast operations return 229 values of type <link 230 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>.</para> 231 </listitem> 232 233 <listitem> 234 <para>If either of the casting operations fails, an exception is 235 handled in accordance with the exception policy.</para> 236 </listitem> 237 238 <listitem> 239 <para>Otherwise, the operation is performed using "<link 240 linkend="safe_numerics.checked_arithmetic">checked arithmetic</link>". 241 These free functions mirror the normal operators +, -, *, ... except 242 that rather than returning values of type R, they return values of the 243 type <link 244 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>. 245 They are defined in files "<ulink 246 url="../../include/boost/safe_numerics/checked_default.hpp">checked_default.hpp</ulink>", 247 "<ulink 248 url="../../include/boost/safe_numerics/checked_integer.hpp">checked_integer.hpp</ulink>" 249 ,"<ulink 250 url="../../include/boost/safe_numerics/checked_float.hpp">checked_float.hpp</ulink>".</para> 251 </listitem> 252 253 <listitem> 254 <para>If the operation is not successful, the designated exception 255 policy function is invoked.</para> 256 </listitem> 257 258 <listitem> 259 <para>Otherwise, the result value is returned as a 260 <code>safe<R></code> type with the above calculated result 261 range.</para> 262 </listitem> 263 </itemizedlist> 264 265 <para>The following components realize the design described here.</para> 266 267 <xi:include href="checked_result.xml" xpointer="element(/1)" 268 xmlns:xi="http://www.w3.org/2001/XInclude"/> 269 270 <xi:include href="checked.xml" xpointer="element(/1)" 271 xmlns:xi="http://www.w3.org/2001/XInclude"/> 272 273 <xi:include href="interval.xml" xpointer="element(/1)" 274 xmlns:xi="http://www.w3.org/2001/XInclude"/> 275 276 <xi:include href="safe_compare.xml" xpointer="element(/1)" 277 xmlns:xi="http://www.w3.org/2001/XInclude"/> 278 </section> 279 280 <section id="safe_numerics.performance_tests"> 281 <title>Performance Tests</title> 282 283 <para>Our goal is to create facilities which make it possible to write 284 programs known to be correct. But we also want programmers to actually use 285 the facilities we provide here. This won't happen if using these 286 facilities impacts performance to a significant degree. Although we've 287 taken precautions to avoid doing this, the only real way to know is to 288 create and run some tests.</para> 289 290 <para>So far we've only run one explicit performance test - 291 <filename><ulink 292 url="../../test/test_performance.cpp">test_performance.cpp</ulink></filename>. 293 This runs a test from the Boost Multiprecision library to count prime 294 numbers and uses on integer arithmetic. We've run the tests with 295 <code>unsigned</code> integers and with <code>safe<unsigned></code> 296 on two different compilers.. No other change was made to the program. We 297 list the results without further comment.</para> 298 299 <screen>g++ (GCC) 6.2.0 300Testing type unsigned: 301time = 17.6215 302count = 1857858 303Testing type safe<unsigned>: 304time = 22.4226 305count = 1857858 306 307clang-802.0.41 308Testing type unsigned: 309time = 16.9174 310count = 1857858 311Testing type safe<unsigned>: 312time = 36.5166 313count = 1857858 314</screen> 315 </section> 316 317 <xi:include href="faq.xml" xpointer="element(/1)" 318 xmlns:xi="http://www.w3.org/2001/XInclude"/> 319 320 <xi:include href="pending.xml" xpointer="element(/1)" 321 xmlns:xi="http://www.w3.org/2001/XInclude"/> 322 323 <xi:include href="acknowledgements.xml" xpointer="element(/1)" 324 xmlns:xi="http://www.w3.org/2001/XInclude"/> 325 326 <section id="safe_numerics.change_log"> 327 <title>Release Log</title> 328 329 <para>This is the third version.</para> 330 331 <para><revhistory> 332 <revision> 333 <revnumber>1.69</revnumber> 334 335 <date>29 September 2018</date> 336 337 <revdescription> 338 <para>First Boost Release</para> 339 </revdescription> 340 </revision> 341 342 <revision> 343 <revnumber>1.70</revnumber> 344 345 <date>9 March 2019</date> 346 347 <revdescription> 348 <para>Fixed Exception Policies for <code>trap</code> and 349 <code>ignore</code>.</para> 350 </revdescription> 351 </revision> 352 </revhistory></para> 353 </section> 354 355 <xi:include href="bibliography.xml" xpointer="element(/1)" 356 xmlns:xi="http://www.w3.org/2001/XInclude"/> 357</library> 358