1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Rationale and FAQ</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="performance_tests.html" title="Performance Tests"> 10<link rel="next" href="pending_issues.html" title="Pending Issues"> 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="performance_tests.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="pending_issues.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.rationale"></a>Rationale and FAQ</h2></div></div></div> 23<div class="qandaset"> 24<a name="idm130201785536"></a><dl> 25<dt>1. <a href="rationale.html#idm130201785040">Is this really necessary? If I'm writing the program with the 26 requisite care and competence, problems noted in the introduction will 27 never arise. Should they arise, they should be fixed "at the source" 28 and not with a "band aid" to cover up bad practice.</a> 29</dt> 30<dt>2. <a href="rationale.html#idm130201781536">Can safe types be used as drop-in replacements for built-in 31 types?</a> 32</dt> 33<dt>3. <a href="rationale.html#idm130201779216">Why are there special types for literal such as 34 safe_signed_literal<42>? Why not just use 35 std::integral_const<int, 42>?</a> 36</dt> 37<dt>4. <a href="rationale.html#idm130201774080">Why is safe...literal needed at all? What's the matter with 38 const safe<int>(42)?</a> 39</dt> 40<dt>5. <a href="rationale.html#idm130201769008">Are safe type operations constexpr? That is, can 41 they be invoked at compile time?</a> 42</dt> 43<dt>6. <a href="rationale.html#idm130201764592">Why define safe_literal? 44 Isn't it effectively the same as 45 std::integral_constant?</a> 46</dt> 47<dt>7. <a href="rationale.html#idm130201752160">Why is Boost.Convert not used?</a> 48</dt> 49<dt>8. <a href="rationale.html#idm130201750128">Why is the library named "safe ..." rather than something like 50 "checked ..." ?</a> 51</dt> 52<dt>9. <a href="rationale.html#idm130201747760">Given that the library is called "numerics" why is floating 53 point arithmetic not addressed?</a> 54</dt> 55<dt>10. <a href="rationale.html#idm130201743024">Isn't putting a defensive check just before any potential 56 undefined behavior often considered a bad practice?</a> 57</dt> 58<dt>11. <a href="rationale.html#idm130201740432">It looks like the implementation presumes two's complement 59 arithmetic at the hardware level. So this library is not portable - 60 correct? What about other hardware architectures?</a> 61</dt> 62<dt>12. <a href="rationale.html#idm130201738112">According to C/C++ standards, unsigned integers 63 cannot overflow - they are modular integers which "wrap around". Yet 64 the safe numerics library detects and traps this behavior as errors. 65 Why is that?</a> 66</dt> 67<dt>13. <a href="rationale.html#idm130201731888">Why does the library require C++14?</a> 68</dt> 69<dt>14. <a href="rationale.html#idm130201726016">This is a C++ library - yet you refer to C/C++. Which is 70 it?</a> 71</dt> 72<dt>15. <a href="rationale.html#idm130201653984">Some compilers (including gcc and clang) include builtin 73 functions for checked addition, multiplication, etc. Does this library 74 use these intrinsics?</a> 75</dt> 76<dt>16. <a href="rationale.html#idm130201650208">Some compilers (including gcc and clang) included a builtin 77 function for detecting constants. This seemed attractive to eliminate 78 the requirement for the safe_literal type. Alas, these builtin 79 functions are defined as macros. Constants passed through functions 80 down into the safe numerics library cannot be detected as constants. 81 So the opportunity to make the library even more efficient by moving 82 more operations to compile time doesn't exist - contrary to my hopes 83 and expections.</a> 84</dt> 85</dl> 86<table border="0" style="width: 100%;"> 87<colgroup> 88<col align="left" width="1%"> 89<col> 90</colgroup> 91<tbody> 92<tr class="question"> 93<td align="left" valign="top"> 94<a name="idm130201785040"></a><a name="idm130201784784"></a><p><b>1.</b></p> 95</td> 96<td align="left" valign="top"><p>Is this really necessary? If I'm writing the program with the 97 requisite care and competence, problems noted in the introduction will 98 never arise. Should they arise, they should be fixed "at the source" 99 and not with a "band aid" to cover up bad practice.</p></td> 100</tr> 101<tr class="answer"> 102<td align="left" valign="top"></td> 103<td align="left" valign="top"><p>This surprised me when it was first raised. But some of the 104 feedback I've received makes me think that it's a widely held view. 105 The best answer is to consider the examples in the <a class="link" href="tutorial.html" title="Tutorial and Motivating Examples">Tutorials and Motivating 106 Examples</a> section of the library documentation. I believe they 107 convincingly demonstrate that any program which does not use this 108 library must be assumed to contain arithmetic errors.</p></td> 109</tr> 110<tr class="question"> 111<td align="left" valign="top"> 112<a name="idm130201781536"></a><a name="idm130201781280"></a><p><b>2.</b></p> 113</td> 114<td align="left" valign="top"><p>Can safe types be used as drop-in replacements for built-in 115 types?</p></td> 116</tr> 117<tr class="answer"> 118<td align="left" valign="top"></td> 119<td align="left" valign="top"><p>Almost. Replacing all built-in types with their safe 120 counterparts should result in a program that will compile and run as 121 expected. Occasionally compile time errors will occur and adjustments 122 to the source code will be required. Typically these will result in 123 code which is more correct.</p></td> 124</tr> 125<tr class="question"> 126<td align="left" valign="top"> 127<a name="idm130201779216"></a><a name="idm130201778960"></a><p><b>3.</b></p> 128</td> 129<td align="left" valign="top"><p>Why are there special types for literal such as 130 <code class="computeroutput">safe_signed_literal<42></code>? Why not just use 131 std::integral_const<int, 42>?</p></td> 132</tr> 133<tr class="answer"> 134<td align="left" valign="top"></td> 135<td align="left" valign="top"><p>By defining our own "special" type we can simplify the 136 interface. Using <code class="computeroutput">std::integral_const</code> requires one to 137 specify both the type <span class="emphasis"><em>and</em></span> the value. Using 138 <code class="computeroutput">safe_signed_literal<42></code> doesn't require a parameter 139 for the type. So the library can select the best type to hold the 140 specified value. It also means that one won't have the opportunity to 141 specify a type-value pair which are inconsistent.</p></td> 142</tr> 143<tr class="question"> 144<td align="left" valign="top"> 145<a name="idm130201774080"></a><a name="idm130201773824"></a><p><b>4.</b></p> 146</td> 147<td align="left" valign="top"><p>Why is safe...literal needed at all? What's the matter with 148 <code class="computeroutput">const safe<int>(42)</code>?</p></td> 149</tr> 150<tr class="answer"> 151<td align="left" valign="top"></td> 152<td align="left" valign="top"> 153<p><code class="computeroutput">const safe<int>(42)</code> looks like it might be 154 what we want: An immutable value which invokes the "safe" operators 155 when used in an expression. But there is one problem. The 156 <code class="computeroutput">std::numeric_limits<safe<int>></code> is a range 157 from INTMIN to INTMAX even though the value is fixed to 42 at compile 158 time. It is this range which is used at compile time to calculate the 159 range of the result of the operation.</p> 160<p>So when an operation is performed, the range of the result is 161 calculated from [INTMIN, INTMAX] rather than from [42,42].</p> 162</td> 163</tr> 164<tr class="question"> 165<td align="left" valign="top"> 166<a name="idm130201769008"></a><a name="idm130201768752"></a><p><b>5.</b></p> 167</td> 168<td align="left" valign="top"><p>Are safe type operations <code class="computeroutput">constexpr</code>? That is, can 169 they be invoked at compile time?</p></td> 170</tr> 171<tr class="answer"> 172<td align="left" valign="top"></td> 173<td align="left" valign="top"><p>Yes. safe type construction and calculations are all 174 <code class="computeroutput">constexpr</code>. Note that to get maximum benefit, you'll have 175 to use <code class="computeroutput">safe...literal</code> to specify the primitive values at 176 compile time.</p></td> 177</tr> 178<tr class="question"> 179<td align="left" valign="top"> 180<a name="idm130201764592"></a><a name="idm130201764336"></a><p><b>6.</b></p> 181</td> 182<td align="left" valign="top"><p>Why define <a class="link" href="safe_literal.html" title="safe_signed_literal<Value, PP , EP> and safe_unsigned_literal<Value, PP, EP>"><code class="computeroutput">safe_literal</code></a>? 183 Isn't it effectively the same as 184 <code class="computeroutput">std::integral_constant</code>?</p></td> 185</tr> 186<tr class="answer"> 187<td align="left" valign="top"></td> 188<td align="left" valign="top"> 189<p>Almost, but there are still good reasons to create a different 190 type.</p> 191<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 192<li class="listitem"><p><code class="computeroutput">std::integral_constant<int, 42></code> 193 requires specification of type as well as value so it's less 194 convenient than safe_signed_literal which maps to the smallest 195 type required to hold the value.</p></li> 196<li class="listitem"><p><code class="computeroutput">std::numeric_limits<std::integral_constant<int, 197 42>>::is_integer</code> returns <code class="computeroutput">false</code>. This 198 would complicate implementation of the library</p></li> 199<li class="listitem"><p>type trait <code class="computeroutput">is_safe<std::integral_constant<int, 200 42>></code> would have to be defined to return 201 <code class="computeroutput">true</code>.</p></li> 202<li class="listitem"><p>But globally altering the traits of 203 <code class="computeroutput">std::integral_constant</code> might have unintended 204 side-effects related to other code. These might well be 205 surprises which are create errors which are hard to find and 206 hard to work around.</p></li> 207</ul></div> 208</td> 209</tr> 210<tr class="question"> 211<td align="left" valign="top"> 212<a name="idm130201752160"></a><a name="idm130201751904"></a><p><b>7.</b></p> 213</td> 214<td align="left" valign="top"><p>Why is Boost.Convert not used?</p></td> 215</tr> 216<tr class="answer"> 217<td align="left" valign="top"></td> 218<td align="left" valign="top"><p>I couldn't figure out how to use it from the 219 documentation.</p></td> 220</tr> 221<tr class="question"> 222<td align="left" valign="top"> 223<a name="idm130201750128"></a><a name="idm130201749872"></a><p><b>8.</b></p> 224</td> 225<td align="left" valign="top"><p>Why is the library named "safe ..." rather than something like 226 "checked ..." ?</p></td> 227</tr> 228<tr class="answer"> 229<td align="left" valign="top"></td> 230<td align="left" valign="top"><p>I used "safe" in large part because this is what has been used 231 by other similar libraries. Maybe a better word might have been 232 "correct" but that would raise similar concerns. I'm not inclined to 233 change this. I've tried to make it clear in the documentation what the 234 problem that the library addressed is.</p></td> 235</tr> 236<tr class="question"> 237<td align="left" valign="top"> 238<a name="idm130201747760"></a><a name="idm130201747504"></a><p><b>9.</b></p> 239</td> 240<td align="left" valign="top"><p>Given that the library is called "numerics" why is floating 241 point arithmetic not addressed?</p></td> 242</tr> 243<tr class="answer"> 244<td align="left" valign="top"></td> 245<td align="left" valign="top"><p>Actually, I believe that this can/should be applied to any type 246 T which satisfies the type requirement <code class="computeroutput">Numeric</code> type as 247 defined in the documentation. So there should be specializations 248 <code class="computeroutput">safe<float></code> and related types as well as new types 249 like <code class="computeroutput">safe<fixed_decimal></code> etc. But the current 250 version of the library only addresses integer types. Hopefully the 251 library will evolve to match the promise implied by its name.</p></td> 252</tr> 253<tr class="question"> 254<td align="left" valign="top"> 255<a name="idm130201743024"></a><a name="idm130201742768"></a><p><b>10.</b></p> 256</td> 257<td align="left" valign="top"><p>Isn't putting a defensive check just before any potential 258 undefined behavior often considered a bad practice?</p></td> 259</tr> 260<tr class="answer"> 261<td align="left" valign="top"></td> 262<td align="left" valign="top"><p>By whom? Is leaving code which can produce incorrect results 263 better? Note that the documentation contains references to various 264 sources which recommend exactly this approach to mitigate the problems 265 created by this C/C++ behavior. See 266 [<a class="citation" href="bibliography.html#seacord1"><span class="citation">Seacord</span></a>]</p></td> 267</tr> 268<tr class="question"> 269<td align="left" valign="top"> 270<a name="idm130201740432"></a><a name="idm130201740176"></a><p><b>11.</b></p> 271</td> 272<td align="left" valign="top"><p>It looks like the implementation presumes two's complement 273 arithmetic at the hardware level. So this library is not portable - 274 correct? What about other hardware architectures?</p></td> 275</tr> 276<tr class="answer"> 277<td align="left" valign="top"></td> 278<td align="left" valign="top"><p>As far as is known as of this writing, the library does not 279 presume that the underlying hardware is two's complement. However, 280 this has yet to be verified in any rigorous way.</p></td> 281</tr> 282<tr class="question"> 283<td align="left" valign="top"> 284<a name="idm130201738112"></a><a name="idm130201737856"></a><p><b>12.</b></p> 285</td> 286<td align="left" valign="top"><p>According to C/C++ standards, <code class="computeroutput">unsigned integers</code> 287 cannot overflow - they are modular integers which "wrap around". Yet 288 the safe numerics library detects and traps this behavior as errors. 289 Why is that?</p></td> 290</tr> 291<tr class="answer"> 292<td align="left" valign="top"></td> 293<td align="left" valign="top"><p>The guiding purpose of the library is to trap incorrect 294 arithmetic behavior - not just undefined behavior. Although a savvy 295 user may understand and keep present in his mind that an unsigned 296 integer is really a modular type, the plain reading of an arithmetic 297 expression conveys the idea that all operands are common integers. 298 Also in many cases, <code class="computeroutput">unsigned integers</code> are used in cases 299 where modular arithmetic is not intended, such as array indices. 300 Finally, the modulus for such an integer would vary depending upon the 301 machine architecture. For these reasons, in the context of this 302 library, an <code class="computeroutput">unsigned integer</code> is considered to be a 303 representation of a subset of integers. Note that this decision is 304 consistent with [<a class="citation" href="bibliography.html#seacord2"><span class="citation">INT30-C</span></a>], “Ensure that unsigned 305 integer operations do not wrap” in the CERT C Secure Coding Standard 306 [<a class="citation" href="bibliography.html#seacord1"><span class="citation">Seacord</span></a>].</p></td> 307</tr> 308<tr class="question"> 309<td align="left" valign="top"> 310<a name="idm130201731888"></a><a name="idm130201731632"></a><p><b>13.</b></p> 311</td> 312<td align="left" valign="top"><p>Why does the library require C++14?</p></td> 313</tr> 314<tr class="answer"> 315<td align="left" valign="top"></td> 316<td align="left" valign="top"><p>The original version of the library used C++11. Feedback from 317 CPPCon, <a href="http://www.blincubator.com" target="_top">Boost Library 318 Incubator</a> and Boost developer's mailing list convinced me that 319 I had to address the issue of run-time penalty much more seriously. I 320 resolved to eliminate or minimize it. This led to more elaborate 321 meta-programming. But this wasn't enough. It became apparent that the 322 only way to really minimize run-time penalty was to implement 323 compile-time integer range arithmetic - a pretty elaborate sub 324 library. By doing range arithmetic at compile-time, I could skip 325 runtime checking on many/most integer operations. While C++11 326 <code class="computeroutput">constexpr</code> wasn't quite powerful enough to do the job, 327 C++14 <code class="computeroutput">constexpr</code> is. The library currently relies very 328 heavily on C++14 <code class="computeroutput">constexpr</code>. I think that those who delve 329 into the library will be very surprised at the extent that minor 330 changes in user code can produce guaranteed correct integer code with 331 zero run-time penalty.</p></td> 332</tr> 333<tr class="question"> 334<td align="left" valign="top"> 335<a name="idm130201726016"></a><a name="idm130201725760"></a><p><b>14.</b></p> 336</td> 337<td align="left" valign="top"><p>This is a C++ library - yet you refer to C/C++. Which is 338 it?</p></td> 339</tr> 340<tr class="answer"> 341<td align="left" valign="top"></td> 342<td align="left" valign="top"> 343<p>C++ has evolved way beyond the original C language. But C++ is 344 still (mostly) compatible with C. So most C programs can be compiled 345 with a C++ compiler. The problems of incorrect arithmetic afflict both 346 C and C++. Suppose we have a legacy C program designed for some 347 embedded system.</p> 348<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 349<li class="listitem"><p>Replace all <code class="computeroutput">int</code> declarations with 350 <code class="computeroutput">int16_t</code> and all <code class="computeroutput">long</code> declarations with 351 <code class="computeroutput">int32_t</code>.</p></li> 352<li class="listitem"> 353<p>Create a file containing something like the following and 354 include it at the beginning of every source file.</p> 355<pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">TEST</span> 356<span class="comment">// using C++ on test platform</span> 357<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstdint</span><span class="special">></span> 358<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">numeric</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> 359<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cpp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 360<span class="keyword">using</span> <span class="identifier">pic16_promotion</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">cpp</span><span class="special"><</span> 361 <span class="number">8</span><span class="special">,</span> <span class="comment">// char</span> 362 <span class="number">8</span><span class="special">,</span> <span class="comment">// short</span> 363 <span class="number">8</span><span class="special">,</span> <span class="comment">// int</span> 364 <span class="number">16</span><span class="special">,</span> <span class="comment">// long</span> 365 <span class="number">32</span> <span class="comment">// long long</span> 366<span class="special">></span><span class="special">;</span> 367<span class="comment">// define safe types used in the desktop version of the program.</span> 368<span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">></span> <span class="comment">// T is char, int, etc data type</span> 369<span class="keyword">using</span> <span class="identifier">safe_t</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">safe</span><span class="special"><</span> 370 <span class="identifier">T</span><span class="special">,</span> 371 <span class="identifier">pic16_promotion</span><span class="special">,</span> 372 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">default_exception_policy</span> <span class="comment">// use for compiling and running tests</span> 373<span class="special">></span><span class="special">;</span> 374<span class="keyword">typedef</span> <span class="identifier">safe_t</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">int_least16_t</span><span class="special">></span> <span class="identifier">int16_t</span><span class="special">;</span> 375<span class="keyword">typedef</span> <span class="identifier">safe_t</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">int_least32_t</span><span class="special">></span> <span class="identifier">int32_t</span><span class="special">;</span> 376<span class="preprocessor">#else</span> 377<span class="comment">/* using C on embedded platform */</span> 378<span class="keyword">typedef</span> <span class="keyword">int</span> <span class="identifier">int_least16_t</span><span class="special">;</span> 379<span class="keyword">typedef</span> <span class="keyword">long</span> <span class="identifier">int_least16_t</span><span class="special">;</span> 380<span class="preprocessor">#endif</span> 381 382</pre> 383</li> 384<li class="listitem"><p>Compile tests on the desktop with a C++14 compiler and 385 with the macro TEST defined.</p></li> 386<li class="listitem"><p>Run the tests and change the code to address any thrown 387 exceptions.</p></li> 388<li class="listitem"><p>Compile for the target C platform with the macro TEST 389 undefined.</p></li> 390</ul></div> 391<p>This example illustrates how this library, implemented with 392 C++14 can be useful in the development of correct code for programs 393 written in C.</p> 394</td> 395</tr> 396<tr class="question"> 397<td align="left" valign="top"> 398<a name="idm130201653984"></a><a name="idm130201653728"></a><p><b>15.</b></p> 399</td> 400<td align="left" valign="top"><p>Some compilers (including gcc and clang) include builtin 401 functions for checked addition, multiplication, etc. Does this library 402 use these intrinsics?</p></td> 403</tr> 404<tr class="answer"> 405<td align="left" valign="top"></td> 406<td align="left" valign="top"><p>No. I attempted to use these but they are currently not 407 <code class="computeroutput">constexpr</code>. So I couldn't use these without breaking 408 <code class="computeroutput">constexpr</code> compatibility for the safe numerics 409 primitives.</p></td> 410</tr> 411<tr class="question"> 412<td align="left" valign="top"> 413<a name="idm130201650208"></a><a name="idm130201649952"></a><p><b>16.</b></p> 414</td> 415<td align="left" valign="top"><p>Some compilers (including gcc and clang) included a builtin 416 function for detecting constants. This seemed attractive to eliminate 417 the requirement for the safe_literal type. Alas, these builtin 418 functions are defined as macros. Constants passed through functions 419 down into the safe numerics library cannot be detected as constants. 420 So the opportunity to make the library even more efficient by moving 421 more operations to compile time doesn't exist - contrary to my hopes 422 and expections.</p></td> 423</tr> 424</tbody> 425</table> 426</div> 427</div> 428<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 429<td align="left"></td> 430<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 431 Software License</a></p> 432</div></td> 433</tr></table> 434<hr> 435<div class="spirit-nav"> 436<a accesskey="p" href="performance_tests.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="pending_issues.html"><img src="images/next.png" alt="Next"></a> 437</div> 438</body> 439</html> 440
