safe_numerics/doc/html/rationale.html

440 lines
25 KiB
HTML

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Rationale and FAQ</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="index.html" title="Safe Numerics">
<link rel="prev" href="performance_tests.html" title="Performance Tests">
<link rel="next" href="pending_issues.html" title="Pending Issues">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="safe_numerics.rationale"></a>Rationale and FAQ</h2></div></div></div>
<div class="qandaset">
<a name="idm130201785536"></a><dl>
<dt>1. <a href="rationale.html#idm130201785040">Is this really necessary? If I'm writing the program with the
requisite care and competence, problems noted in the introduction will
never arise. Should they arise, they should be fixed "at the source"
and not with a "band aid" to cover up bad practice.</a>
</dt>
<dt>2. <a href="rationale.html#idm130201781536">Can safe types be used as drop-in replacements for built-in
types?</a>
</dt>
<dt>3. <a href="rationale.html#idm130201779216">Why are there special types for literal such as
safe_signed_literal&lt;42&gt;? Why not just use
std::integral_const&lt;int, 42&gt;?</a>
</dt>
<dt>4. <a href="rationale.html#idm130201774080">Why is safe...literal needed at all? What's the matter with
const safe&lt;int&gt;(42)?</a>
</dt>
<dt>5. <a href="rationale.html#idm130201769008">Are safe type operations constexpr? That is, can
they be invoked at compile time?</a>
</dt>
<dt>6. <a href="rationale.html#idm130201764592">Why define safe_literal?
Isn't it effectively the same as
std::integral_constant?</a>
</dt>
<dt>7. <a href="rationale.html#idm130201752160">Why is Boost.Convert not used?</a>
</dt>
<dt>8. <a href="rationale.html#idm130201750128">Why is the library named "safe ..." rather than something like
"checked ..." ?</a>
</dt>
<dt>9. <a href="rationale.html#idm130201747760">Given that the library is called "numerics" why is floating
point arithmetic not addressed?</a>
</dt>
<dt>10. <a href="rationale.html#idm130201743024">Isn't putting a defensive check just before any potential
undefined behavior often considered a bad practice?</a>
</dt>
<dt>11. <a href="rationale.html#idm130201740432">It looks like the implementation presumes two's complement
arithmetic at the hardware level. So this library is not portable -
correct? What about other hardware architectures?</a>
</dt>
<dt>12. <a href="rationale.html#idm130201738112">According to C/C++ standards, unsigned integers
cannot overflow - they are modular integers which "wrap around". Yet
the safe numerics library detects and traps this behavior as errors.
Why is that?</a>
</dt>
<dt>13. <a href="rationale.html#idm130201731888">Why does the library require C++14?</a>
</dt>
<dt>14. <a href="rationale.html#idm130201726016">This is a C++ library - yet you refer to C/C++. Which is
it?</a>
</dt>
<dt>15. <a href="rationale.html#idm130201653984">Some compilers (including gcc and clang) include builtin
functions for checked addition, multiplication, etc. Does this library
use these intrinsics?</a>
</dt>
<dt>16. <a href="rationale.html#idm130201650208">Some compilers (including gcc and clang) included a builtin
function for detecting constants. This seemed attractive to eliminate
the requirement for the safe_literal type. Alas, these builtin
functions are defined as macros. Constants passed through functions
down into the safe numerics library cannot be detected as constants.
So the opportunity to make the library even more efficient by moving
more operations to compile time doesn't exist - contrary to my hopes
and expections.</a>
</dt>
</dl>
<table border="0" style="width: 100%;">
<colgroup>
<col align="left" width="1%">
<col>
</colgroup>
<tbody>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201785040"></a><a name="idm130201784784"></a><p><b>1.</b></p>
</td>
<td align="left" valign="top"><p>Is this really necessary? If I'm writing the program with the
requisite care and competence, problems noted in the introduction will
never arise. Should they arise, they should be fixed "at the source"
and not with a "band aid" to cover up bad practice.</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>This surprised me when it was first raised. But some of the
feedback I've received makes me think that it's a widely held view.
The best answer is to consider the examples in the <a class="link" href="tutorial.html" title="Tutorial and Motivating Examples">Tutorials and Motivating
Examples</a> section of the library documentation. I believe they
convincingly demonstrate that any program which does not use this
library must be assumed to contain arithmetic errors.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201781536"></a><a name="idm130201781280"></a><p><b>2.</b></p>
</td>
<td align="left" valign="top"><p>Can safe types be used as drop-in replacements for built-in
types?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>Almost. Replacing all built-in types with their safe
counterparts should result in a program that will compile and run as
expected. Occasionally compile time errors will occur and adjustments
to the source code will be required. Typically these will result in
code which is more correct.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201779216"></a><a name="idm130201778960"></a><p><b>3.</b></p>
</td>
<td align="left" valign="top"><p>Why are there special types for literal such as
<code class="computeroutput">safe_signed_literal&lt;42&gt;</code>? Why not just use
std::integral_const&lt;int, 42&gt;?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>By defining our own "special" type we can simplify the
interface. Using <code class="computeroutput">std::integral_const</code> requires one to
specify both the type <span class="emphasis"><em>and</em></span> the value. Using
<code class="computeroutput">safe_signed_literal&lt;42&gt;</code> doesn't require a parameter
for the type. So the library can select the best type to hold the
specified value. It also means that one won't have the opportunity to
specify a type-value pair which are inconsistent.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201774080"></a><a name="idm130201773824"></a><p><b>4.</b></p>
</td>
<td align="left" valign="top"><p>Why is safe...literal needed at all? What's the matter with
<code class="computeroutput">const safe&lt;int&gt;(42)</code>?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p><code class="computeroutput">const safe&lt;int&gt;(42)</code> looks like it might be
what we want: An immutable value which invokes the "safe" operators
when used in an expression. But there is one problem. The
<code class="computeroutput">std::numeric_limits&lt;safe&lt;int&gt;&gt;</code> is a range
from INTMIN to INTMAX even though the value is fixed to 42 at compile
time. It is this range which is used at compile time to calculate the
range of the result of the operation.</p>
<p>So when an operation is performed, the range of the result is
calculated from [INTMIN, INTMAX] rather than from [42,42].</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201769008"></a><a name="idm130201768752"></a><p><b>5.</b></p>
</td>
<td align="left" valign="top"><p>Are safe type operations <code class="computeroutput">constexpr</code>? That is, can
they be invoked at compile time?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>Yes. safe type construction and calculations are all
<code class="computeroutput">constexpr</code>. Note that to get maximum benefit, you'll have
to use <code class="computeroutput">safe...literal</code> to specify the primitive values at
compile time.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201764592"></a><a name="idm130201764336"></a><p><b>6.</b></p>
</td>
<td align="left" valign="top"><p>Why define <a class="link" href="safe_literal.html" title="safe_signed_literal&lt;Value, PP , EP&gt; and safe_unsigned_literal&lt;Value, PP, EP&gt;"><code class="computeroutput">safe_literal</code></a>?
Isn't it effectively the same as
<code class="computeroutput">std::integral_constant</code>?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>Almost, but there are still good reasons to create a different
type.</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="computeroutput">std::integral_constant&lt;int, 42&gt;</code>
requires specification of type as well as value so it's less
convenient than safe_signed_literal which maps to the smallest
type required to hold the value.</p></li>
<li class="listitem"><p><code class="computeroutput">std::numeric_limits&lt;std::integral_constant&lt;int,
42&gt;&gt;::is_integer</code> returns <code class="computeroutput">false</code>. This
would complicate implementation of the library</p></li>
<li class="listitem"><p>type trait <code class="computeroutput">is_safe&lt;std::integral_constant&lt;int,
42&gt;&gt;</code> would have to be defined to return
<code class="computeroutput">true</code>.</p></li>
<li class="listitem"><p>But globally altering the traits of
<code class="computeroutput">std::integral_constant</code> might have unintended
side-effects related to other code. These might well be
surprises which are create errors which are hard to find and
hard to work around.</p></li>
</ul></div>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201752160"></a><a name="idm130201751904"></a><p><b>7.</b></p>
</td>
<td align="left" valign="top"><p>Why is Boost.Convert not used?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>I couldn't figure out how to use it from the
documentation.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201750128"></a><a name="idm130201749872"></a><p><b>8.</b></p>
</td>
<td align="left" valign="top"><p>Why is the library named "safe ..." rather than something like
"checked ..." ?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>I used "safe" in large part because this is what has been used
by other similar libraries. Maybe a better word might have been
"correct" but that would raise similar concerns. I'm not inclined to
change this. I've tried to make it clear in the documentation what the
problem that the library addressed is.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201747760"></a><a name="idm130201747504"></a><p><b>9.</b></p>
</td>
<td align="left" valign="top"><p>Given that the library is called "numerics" why is floating
point arithmetic not addressed?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>Actually, I believe that this can/should be applied to any type
T which satisfies the type requirement <code class="computeroutput">Numeric</code> type as
defined in the documentation. So there should be specializations
<code class="computeroutput">safe&lt;float&gt;</code> and related types as well as new types
like <code class="computeroutput">safe&lt;fixed_decimal&gt;</code> etc. But the current
version of the library only addresses integer types. Hopefully the
library will evolve to match the promise implied by its name.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201743024"></a><a name="idm130201742768"></a><p><b>10.</b></p>
</td>
<td align="left" valign="top"><p>Isn't putting a defensive check just before any potential
undefined behavior often considered a bad practice?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>By whom? Is leaving code which can produce incorrect results
better? Note that the documentation contains references to various
sources which recommend exactly this approach to mitigate the problems
created by this C/C++ behavior. See
[<a class="citation" href="bibliography.html#seacord1"><span class="citation">Seacord</span></a>]</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201740432"></a><a name="idm130201740176"></a><p><b>11.</b></p>
</td>
<td align="left" valign="top"><p>It looks like the implementation presumes two's complement
arithmetic at the hardware level. So this library is not portable -
correct? What about other hardware architectures?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>As far as is known as of this writing, the library does not
presume that the underlying hardware is two's complement. However,
this has yet to be verified in any rigorous way.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201738112"></a><a name="idm130201737856"></a><p><b>12.</b></p>
</td>
<td align="left" valign="top"><p>According to C/C++ standards, <code class="computeroutput">unsigned integers</code>
cannot overflow - they are modular integers which "wrap around". Yet
the safe numerics library detects and traps this behavior as errors.
Why is that?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>The guiding purpose of the library is to trap incorrect
arithmetic behavior - not just undefined behavior. Although a savvy
user may understand and keep present in his mind that an unsigned
integer is really a modular type, the plain reading of an arithmetic
expression conveys the idea that all operands are common integers.
Also in many cases, <code class="computeroutput">unsigned integers</code> are used in cases
where modular arithmetic is not intended, such as array indices.
Finally, the modulus for such an integer would vary depending upon the
machine architecture. For these reasons, in the context of this
library, an <code class="computeroutput">unsigned integer</code> is considered to be a
representation of a subset of integers. Note that this decision is
consistent with [<a class="citation" href="bibliography.html#seacord2"><span class="citation">INT30-C</span></a>], &#8220;Ensure that unsigned
integer operations do not wrap&#8221; in the CERT C Secure Coding Standard
[<a class="citation" href="bibliography.html#seacord1"><span class="citation">Seacord</span></a>].</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201731888"></a><a name="idm130201731632"></a><p><b>13.</b></p>
</td>
<td align="left" valign="top"><p>Why does the library require C++14?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>The original version of the library used C++11. Feedback from
CPPCon, <a href="http://www.blincubator.com" target="_top">Boost Library
Incubator</a> and Boost developer's mailing list convinced me that
I had to address the issue of run-time penalty much more seriously. I
resolved to eliminate or minimize it. This led to more elaborate
meta-programming. But this wasn't enough. It became apparent that the
only way to really minimize run-time penalty was to implement
compile-time integer range arithmetic - a pretty elaborate sub
library. By doing range arithmetic at compile-time, I could skip
runtime checking on many/most integer operations. While C++11
<code class="computeroutput">constexpr</code> wasn't quite powerful enough to do the job,
C++14 <code class="computeroutput">constexpr</code> is. The library currently relies very
heavily on C++14 <code class="computeroutput">constexpr</code>. I think that those who delve
into the library will be very surprised at the extent that minor
changes in user code can produce guaranteed correct integer code with
zero run-time penalty.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201726016"></a><a name="idm130201725760"></a><p><b>14.</b></p>
</td>
<td align="left" valign="top"><p>This is a C++ library - yet you refer to C/C++. Which is
it?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>C++ has evolved way beyond the original C language. But C++ is
still (mostly) compatible with C. So most C programs can be compiled
with a C++ compiler. The problems of incorrect arithmetic afflict both
C and C++. Suppose we have a legacy C program designed for some
embedded system.</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>Replace all <code class="computeroutput">int</code> declarations with
<code class="computeroutput">int16_t</code> and all <code class="computeroutput">long</code> declarations with
<code class="computeroutput">int32_t</code>.</p></li>
<li class="listitem">
<p>Create a file containing something like the following and
include it at the beginning of every source file.</p>
<pre class="programlisting"><span class="preprocessor">#ifdef</span> <span class="identifier">TEST</span>
<span class="comment">// using C++ on test platform</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstdint</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cpp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<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">&lt;</span>
<span class="number">8</span><span class="special">,</span> <span class="comment">// char</span>
<span class="number">8</span><span class="special">,</span> <span class="comment">// short</span>
<span class="number">8</span><span class="special">,</span> <span class="comment">// int</span>
<span class="number">16</span><span class="special">,</span> <span class="comment">// long</span>
<span class="number">32</span> <span class="comment">// long long</span>
<span class="special">&gt;</span><span class="special">;</span>
<span class="comment">// define safe types used in the desktop version of the program.</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="comment">// T is char, int, etc data type</span>
<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">&lt;</span>
<span class="identifier">T</span><span class="special">,</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">default_exception_policy</span> <span class="comment">// use for compiling and running tests</span>
<span class="special">&gt;</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">safe_t</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">int_least16_t</span><span class="special">&gt;</span> <span class="identifier">int16_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">safe_t</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">int_least32_t</span><span class="special">&gt;</span> <span class="identifier">int32_t</span><span class="special">;</span>
<span class="preprocessor">#else</span>
<span class="comment">/* using C on embedded platform */</span>
<span class="keyword">typedef</span> <span class="keyword">int</span> <span class="identifier">int_least16_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">long</span> <span class="identifier">int_least16_t</span><span class="special">;</span>
<span class="preprocessor">#endif</span>
</pre>
</li>
<li class="listitem"><p>Compile tests on the desktop with a C++14 compiler and
with the macro TEST defined.</p></li>
<li class="listitem"><p>Run the tests and change the code to address any thrown
exceptions.</p></li>
<li class="listitem"><p>Compile for the target C platform with the macro TEST
undefined.</p></li>
</ul></div>
<p>This example illustrates how this library, implemented with
C++14 can be useful in the development of correct code for programs
written in C.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201653984"></a><a name="idm130201653728"></a><p><b>15.</b></p>
</td>
<td align="left" valign="top"><p>Some compilers (including gcc and clang) include builtin
functions for checked addition, multiplication, etc. Does this library
use these intrinsics?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>No. I attempted to use these but they are currently not
<code class="computeroutput">constexpr</code>. So I couldn't use these without breaking
<code class="computeroutput">constexpr</code> compatibility for the safe numerics
primitives.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm130201650208"></a><a name="idm130201649952"></a><p><b>16.</b></p>
</td>
<td align="left" valign="top"><p>Some compilers (including gcc and clang) included a builtin
function for detecting constants. This seemed attractive to eliminate
the requirement for the safe_literal type. Alas, these builtin
functions are defined as macros. Constants passed through functions
down into the safe numerics library cannot be detected as constants.
So the opportunity to make the library even more efficient by moving
more operations to compile time doesn't exist - contrary to my hopes
and expections.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>