1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Library Implementation</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="index.html" title="Safe Numerics"> 9<link rel="prev" href="exception_safety.html" title="Exception Safety"> 10<link rel="next" href="checked_result.html" title="checked_result<R>"> 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="exception_safety.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.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="checked_result.html"><img src="images/next.png" alt="Next"></a> 19</div> 20<div class="section"> 21<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 22<a name="safe_numerics.library_implementation"></a>Library Implementation</h2></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="checked_result.html">checked_result<R></a></span></dt> 25<dt><span class="section"><a href="checked_arithmetic.html">Checked Arithmetic</a></span></dt> 26<dt><span class="section"><a href="interval.html">interval<R></a></span></dt> 27<dt><span class="section"><a href="checked_integer_arithmetic.html">safe_compare<T, U></a></span></dt> 28</dl></div> 29<p>This library should compile and run correctly on any conforming 30 C++14 compiler.</p> 31<p>The Safe Numerics library is implemented in terms of some more 32 fundamental software components described here. It is not necessary to 33 know about these components to use the library. This information has been 34 included to help those who want to understand how the library works so 35 they can extend it, correct bugs in it, or understand its limitations. 36 These components are also interesting and likely useful in their own 37 right. For all these reasons, they are documented here.</p> 38<p>In general terms, the library works in the following manner:</p> 39<p>At compile time:</p> 40<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 41<li class="listitem"><p>The library defines "safe" versions of C++ primitive arithmetic 42 types such as <code class="computeroutput">int</code>, <code class="computeroutput">unsigned int</code>, etc.</p></li> 43<li class="listitem"><p>Arithmetic operators are defined for these "safe" types. These 44 operators are enhanced versions of the standard C/C++ implementations. 45 These operators are declared and implemented in the files "<a href="../../include/boost/safe_numerics/safe_base.hpp" target="_top">safe_base.hpp</a>" 46 and "<a href="../../include/boost/safe_numerics/safe_base_operations.hpp" target="_top">safe_base_operations.hpp</a>".</p></li> 47<li class="listitem"><p>For binary operators, verify that both operands have the same 48 promotion and and exception handling policies. If they don't, invoke 49 compilation error.</p></li> 50<li class="listitem"><p>Invoke the promotion policy to determine the result type R of 51 the operation.</p></li> 52<li class="listitem"><p>For each operand of type T retrieve the range of values from 53 <code class="computeroutput">std::numeric_limits<T>::min()</code> and 54 <code class="computeroutput">std::numeric_limits<T>::max()</code>. A range is a pair of 55 values representing a closed interval with a minimum and maximum 56 value.</p></li> 57<li class="listitem"><p>These ranges are cast to equivalent values of the result type, 58 R. It's possible that values cannot be cast to the result type so the 59 result of the cast is returned as a variant type, <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>. 60 <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a> 61 may hold either a value of type R or a <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> 62 value indicating why the cast could not be accomplished. Ranges are 63 represented as a pair of values of the type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li> 64<li class="listitem"><p><a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a> 65 can be considered enhanced versions of the underlying type R. 66 Operations which are legal on values of type R such as +, -, ... are 67 also legal on values of <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>. 68 The difference is that the latter can record operation failures and 69 propagate such failures to subsequent operations.<a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a> 70 is implemented in the header file "<a href="../../include/boost/safe_numerics/checked_result.hpp" target="_top">checked_result.hpp</a>". 71 Operations on such types are implemented in "<a href="../../include/boost/safe_numerics/checked_result_operations.hpp" target="_top">checked_result_operations.hpp</a>".</p></li> 72<li class="listitem"><p>Given the ranges of the operands, determine the range of the 73 result of the operation using compile-time interval arithmetic. The 74 <code class="computeroutput">constexpr</code> facility of C++14 permits the range of the 75 result to be calculated at compile time. Interval arithmetic is 76 implemented in the header file "<a href="../../include/boost/safe_numerics/interval.hpp" target="_top">interval.hpp</a>". 77 The range of the result is also represented as a pair of values of the 78 type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li> 79<li class="listitem"><p>Operations on primitives are implemented via free standing 80 functions described as <a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>. 81 These operations will return instances of <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a> 82 .</p></li> 83</ul></div> 84<p>At run time:</p> 85<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 86<li class="listitem"><p>If the range of the result type includes only arithmetically 87 valid values, the operation is guaranteed to produce an arithmetically 88 correct result and no runtime checking is necessary. The operation 89 invokes the original built-in C/C++ operation and returns the result 90 value.</p></li> 91<li class="listitem"><p>Otherwise, operands are cast to the result type, R, according to 92 the selected promotion policy. These "checked" cast operations return 93 values of type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li> 94<li class="listitem"><p>If either of the casting operations fails, an exception is 95 handled in accordance with the exception policy.</p></li> 96<li class="listitem"><p>Otherwise, the operation is performed using "<a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>". 97 These free functions mirror the normal operators +, -, *, ... except 98 that rather than returning values of type R, they return values of the 99 type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>. 100 They are defined in files "<a href="../../include/boost/safe_numerics/checked_default.hpp" target="_top">checked_default.hpp</a>", 101 "<a href="../../include/boost/safe_numerics/checked_integer.hpp" target="_top">checked_integer.hpp</a>" 102 ,"<a href="../../include/boost/safe_numerics/checked_float.hpp" target="_top">checked_float.hpp</a>".</p></li> 103<li class="listitem"><p>If the operation is not successful, the designated exception 104 policy function is invoked.</p></li> 105<li class="listitem"><p>Otherwise, the result value is returned as a 106 <code class="computeroutput">safe<R></code> type with the above calculated result 107 range.</p></li> 108</ul></div> 109<p>The following components realize the design described here.</p> 110</div> 111<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 112<td align="left"></td> 113<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 114 Software License</a></p> 115</div></td> 116</tr></table> 117<hr> 118<div class="spirit-nav"> 119<a accesskey="p" href="exception_safety.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="index.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="checked_result.html"><img src="images/next.png" alt="Next"></a> 120</div> 121</body> 122</html> 123
