1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Introduction</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="index.html" title="Safe Numerics"> 10<link rel="next" href="tutorial.html" title="Tutorial and Motivating Examples"> 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="index.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="tutorial.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.introduction"></a>Introduction</h2></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.problem">Problem</a></span></dt> 25<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.solution">Solution</a></span></dt> 26<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.implementation">How It Works</a></span></dt> 27<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.additional_features">Additional Features</a></span></dt> 28<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.requirements">Requirements</a></span></dt> 29<dt><span class="section"><a href="introduction.html#safe_numerics.introduction.scope">Scope</a></span></dt> 30</dl></div> 31<p>This library is intended as a drop-in replacement for all built-in 32 integer types in any program which must:</p> 33<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 34<li class="listitem"><p>be demonstrably and verifiably correct.</p></li> 35<li class="listitem"><p>detect every user error such as input, assignment, etc.</p></li> 36<li class="listitem"><p>be efficient as possible subject to the constraints above.</p></li> 37</ul></div> 38<div class="section"> 39<div class="titlepage"><div><div><h3 class="title"> 40<a name="safe_numerics.introduction.problem"></a>Problem</h3></div></div></div> 41<p>Arithmetic operations in C/C++ are NOT guaranteed to yield a correct 42 mathematical result. This feature is inherited from the early days of C. 43 The behavior of <code class="computeroutput">int</code>, <code class="computeroutput">unsigned int</code> and others 44 were designed to map closely to the underlying hardware. Computer hardware 45 implements these types as a fixed number of bits. When the result of 46 arithmetic operations exceeds this number of bits, the result will not be 47 arithmetically correct. The following example illustrates just one example 48 where this causes problems.</p> 49<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</span><span class="special">{</span> 50 <span class="comment">// this returns an invalid result for some legal values of x and y !</span> 51 <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> 52<span class="special">}</span> 53</pre> 54<p>It is incumbent upon the C/C++ programmer to guarantee that this 55 behavior does not result in incorrect or unexpected operation of the 56 program. There are no language facilities which implement such a 57 guarantee. A programmer needs to examine each expression individually to 58 know that his program will not return an invalid result. There are a 59 number of ways to do this. In the above instance, 60 [<a class="citation" href="bibliography.html#seacord3"><span class="citation">INT32-C</span></a>] seems to recommend the following 61 approach:</p> 62<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</span><span class="special">{</span> 63 <span class="keyword">if</span> <span class="special">(</span><span class="special">(</span><span class="special">(</span><span class="identifier">y</span> <span class="special">></span> <span class="number">0</span><span class="special">)</span> <span class="special">&&</span> <span class="special">(</span><span class="identifier">x</span> <span class="special">></span> <span class="special">(</span><span class="identifier">INT_MAX</span> <span class="special">-</span> <span class="identifier">y</span><span class="special">)</span><span class="special">)</span><span class="special">)</span> 64 <span class="special">||</span> <span class="special">(</span><span class="special">(</span><span class="identifier">y</span> <span class="special"><</span> <span class="number">0</span><span class="special">)</span> <span class="special">&&</span> <span class="special">(</span><span class="identifier">x</span> <span class="special"><</span> <span class="special">(</span><span class="identifier">INT_MIN</span> <span class="special">-</span> <span class="identifier">y</span><span class="special">)</span><span class="special">)</span><span class="special">)</span><span class="special">)</span> <span class="special">{</span> 65 <span class="comment">/* Handle error */</span> 66 <span class="special">}</span> 67 <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> 68<span class="special">}</span> 69</pre> 70<p>This will indeed trap the error. However, it would be tedious and 71 laborious for a programmer to alter his code in this manner. Altering code 72 in this way for all arithmetic operations would likely render the code 73 unreadable and add another source of potential programming errors. This 74 approach is clearly not functional when the expression is even a little 75 more complex as is shown in the following example.</p> 76<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">z</span><span class="special">)</span><span class="special">{</span> 77 <span class="comment">// this returns an invalid result for some legal values of x and y !</span> 78 <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span> <span class="special">*</span> <span class="identifier">z</span><span class="special">;</span> 79<span class="special">}</span> 80</pre> 81<p>This example addresses only the problem of undefined/erroneous 82 behavior related to overflow of the addition operation as applied to the 83 type <code class="computeroutput">int</code>. Similar problems occur with other built-in integer 84 types such as <code class="computeroutput">unsigned</code>, <code class="computeroutput">long</code>, etc. And it also 85 applies to other operations such as subtraction, multiplication etc. . 86 C/C++ often automatically and silently converts some integer types to 87 others in the course of implementing binary operations. Sometimes such 88 conversions can silently change arithmetic values which inject errors. The 89 C/C++ standards designate some behavior such as right shifting a negative 90 number as "implementation defined behavior". These days machines usually 91 do what the programmer expects - but such behavior is not guaranteed. 92 Relying on such behavior will create a program which cannot be guaranteed 93 to be portable. And then there is undefined behavior. In this case, 94 compiler writer is under no obligation to do anything in particular. 95 Sometimes this will unexpectedly break the program. At the very least, the 96 program is rendered non-portable. Finally there is the case of behavior 97 that is arithmetically wrong to begin with - for example divide by zero. 98 Some runtime environments will just terminate the program, others may 99 throw some sort of exception. In any case, the execution has failed in a 100 manner from which there is no recovery.</p> 101<p>All of the above conditions are obstacles to creation of a program 102 which will never fail. The Safe Numerics Library addresses all of these 103 conditions, at least as far as integer operations are concerned.</p> 104<p>Since the problems and their solution are similar, we'll confine the 105 current discussion to just the one example shown above.</p> 106</div> 107<div class="section"> 108<div class="titlepage"><div><div><h3 class="title"> 109<a name="safe_numerics.introduction.solution"></a>Solution</h3></div></div></div> 110<p>This library implements special versions of <code class="computeroutput">int</code>, 111 <code class="computeroutput">unsigned</code>, etc. which behave exactly like the original ones 112 <span class="bold"><strong>except</strong></span> that the results of these 113 operations are guaranteed to be either to be arithmetically correct or 114 invoke an error. Using this library, the above example would be rendered 115 as:</p> 116<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">safe_integer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 117<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">;</span> 118<span class="identifier">safe</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">safe</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">safe</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">y</span><span class="special">)</span><span class="special">{</span> 119 <span class="keyword">return</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// throw exception if correct result cannot be returned</span> 120<span class="special">}</span> 121</pre> 122<div class="note"><table border="0" summary="Note"> 123<tr> 124<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td> 125<th align="left">Note</th> 126</tr> 127<tr><td align="left" valign="top"><p>Library code in this document resides in the namespace 128 <code class="computeroutput">boost::numeric</code>. This namespace has generally been 129 eliminated from text, code and examples in order to improve 130 readability of the text.</p></td></tr> 131</table></div> 132<p>The addition expression is checked at runtime or (if possible) at 133 compile time to trap any possible errors resulting in incorrect arithmetic 134 behavior. Arithmetic expressions will not produce an erroneous result. 135 Instead, one and only one of the following is guaranteed to occur.</p> 136<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 137<li class="listitem"><p>the expression will yield the correct mathematical 138 result</p></li> 139<li class="listitem"><p>the expression will emit a compilation error.</p></li> 140<li class="listitem"><p>the expression will invoke a runtime exception.</p></li> 141</ul></div> 142<p>In other words, the <span class="bold"><strong>library absolutely 143 guarantees that no integer arithmetic expression will yield incorrect 144 results</strong></span>.</p> 145</div> 146<div class="section"> 147<div class="titlepage"><div><div><h3 class="title"> 148<a name="safe_numerics.introduction.implementation"></a>How It Works</h3></div></div></div> 149<p>The library implements special versions of <code class="computeroutput">int</code>, 150 <code class="computeroutput">unsigned</code>, etc. Named <code class="computeroutput">safe<int></code>, 151 <code class="computeroutput">safe<unsigned int></code> etc. These behave exactly like the 152 underlying types <span class="bold"><strong>except</strong></span> that expressions 153 using these types fulfill the above guarantee. These "safe" types are 154 meant to be "drop-in" replacements for the built-in types of the same 155 name. So things which are legal - such as assignment of a 156 <code class="computeroutput">signed</code> to <code class="computeroutput">unsigned</code> value - are not trapped at 157 compile time as they are legal C/C++ code. Instead, they are checked at 158 runtime to trap the case where this (legal) operation would lead to an 159 arithmetically incorrect result.</p> 160<p>Note that the library addresses arithmetical errors generated by 161 straightforward C/C++ expressions. Some of these arithmetic errors are 162 defined as conforming to the C/C++ standards while others are not. So 163 characterizing this library as only addressing undefined behavior of C/C++ 164 numeric expressions would be misleading.</p> 165<p>Facilities particular to C++14 are employed to minimize any runtime 166 overhead. In many cases there is no runtime overhead at all. In other 167 cases, a program using the library can be slightly altered to achieve the 168 above guarantee without any runtime overhead.</p> 169</div> 170<div class="section"> 171<div class="titlepage"><div><div><h3 class="title"> 172<a name="safe_numerics.introduction.additional_features"></a>Additional Features</h3></div></div></div> 173<p>Operation of safe types is determined by template parameters which 174 specify a pair of <a class="link" href="promotion_policies.html" title="Promotion Policies">policy 175 classes</a> which specify the behavior for type promotion and error 176 handling. In addition to the usage serving as a drop-in replacement for 177 standard integer types, users of the library can:</p> 178<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 179<li class="listitem"> 180<p>Select or define an exception policy class to specify handling 181 of exceptions.</p> 182<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 183<li class="listitem"><p>Throw exception on runtime, trap at compile time if 184 possible.</p></li> 185<li class="listitem"><p>Trap at compile time all operations which could possibly 186 fail at runtime.</p></li> 187<li class="listitem"><p>Specify custom functions which should be called in case 188 errors are detected at runtime.</p></li> 189</ul></div> 190</li> 191<li class="listitem"> 192<p>Select or define a promotion policy class to alter the C/C++ 193 type promotion rules. This can be used to </p> 194<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 195<li class="listitem"><p>Use C/C++ native type promotion rules so that, except 196 for throwing/trapping of exceptions on operations resulting in 197 incorrect arithmetic behavior, programs will operate 198 identically when using/not using safe types. This might be 199 used if safe types are only enabled during debug and 200 testing.</p></li> 201<li class="listitem"><p>Replace C/C++ native promotion rules with ones which are 202 arithmetically equivalent but minimize the need for runtime 203 checking of arithmetic results. Such a policy will effectively 204 change the semantics of a C++ program. It's not really C++ any 205 more. The program cannot be expected to function the same as 206 when normal integer types are used.</p></li> 207<li class="listitem"><p>Replace C/C++ native promotion rules with ones which 208 emulate other machine architectures. This is designed to 209 permit the testing of C/C++ code destined to be run on another 210 machine on one's development platform. Such a situation often 211 occurs while developing code for embedded systems.</p></li> 212</ul></div> 213</li> 214<li class="listitem"><p>Enforce other program requirements using bounded integer 215 types. The library includes the types for ranges and literals. 216 Operations which violate these requirements will be trapped at 217 either compile time or runtime and not silently return invalid 218 values. These types can be used to improve program correctness and 219 performance.</p></li> 220</ul></div> 221</div> 222<div class="section"> 223<div class="titlepage"><div><div><h3 class="title"> 224<a name="safe_numerics.introduction.requirements"></a>Requirements</h3></div></div></div> 225<p>This library is composed entirely of C++ Headers. It requires a 226 compiler compatible with the C++14 standard.</p> 227<p>The following Boost Libraries must be installed in order to use this 228 library</p> 229<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 230<li class="listitem"><p>mp11</p></li> 231<li class="listitem"><p>integer</p></li> 232<li class="listitem"><p>config</p></li> 233<li class="listitem"><p>tribool</p></li> 234<li class="listitem"><p>enable_if</p></li> 235</ul></div> 236<p>The Safe Numerics library is delivered with an exhaustive 237 suite of test programs.</p> 238</div> 239<div class="section"> 240<div class="titlepage"><div><div><h3 class="title"> 241<a name="safe_numerics.introduction.scope"></a>Scope</h3></div></div></div> 242<p>This library currently applies only to built-in integer types. 243 Analogous issues arise for floating point types but they are not currently 244 addressed by this version of the library. User or library defined types 245 such as arbitrary precision integers can also have this problem. Extension 246 of this library to these other types is not currently under development 247 but may be addressed in the future. This is one reason why the library 248 name is "safe numeric" rather than "safe integer" library.</p> 249</div> 250</div> 251<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 252<td align="left"></td> 253<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 254 Software License</a></p> 255</div></td> 256</tr></table> 257<hr> 258<div class="spirit-nav"> 259<a accesskey="p" href="index.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="tutorial.html"><img src="images/next.png" alt="Next"></a> 260</div> 261</body> 262</html> 263
