boost/safe_numerics
2
0
Fork 0
mirror of https://github.com/boostorg/safe_numerics.git synced 2026-02-21 15:22:14 +00:00
Code Issues Projects Releases Wiki Activity
Files
6f0710109c93bb18dfd3344857588bee5399d056
safe_numerics/doc/html/rationale.html
Robert Ramey d0ca1634fc documentation updates inspired by ACCU Overload
2017-02-03 14:24:05 -08:00

311 lines
18 KiB
HTML
Raw Blame History

<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="idm50877785888"></a><dl>
<dt>1. <a href="rationale.html#idm50877785392">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#idm50877782032">Can safe types be used as drop-in replacement for built-in
types?</a>
</dt>
<dt>3. <a href="rationale.html#idm50877779696">Why is Boost.Convert not used?</a>
</dt>
<dt>4. <a href="rationale.html#idm50877777696">Why is the library named "safe ..." rather than something like
"checked ..." ?</a>
</dt>
<dt>5. <a href="rationale.html#idm50877775344">Given that the library is called "numerics" why is floating
point arithmetic not addressed?</a>
</dt>
<dt>6. <a href="rationale.html#idm50877771312">Isn't putting a defensive check just before any potential
undefined behavior is often considered a bad practice?</a>
</dt>
<dt>7. <a href="rationale.html#idm50877768736">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>8. <a href="rationale.html#idm50877766416">Why do you specialize numeric_limits for "safe"
types? Do you need it?</a>
</dt>
<dt>9. <a href="rationale.html#idm50877759872">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>10. <a href="rationale.html#idm50877755888">Why does the library require C++14?</a>
</dt>
<dt>11. <a href="rationale.html#idm50877752240">This is a C++ library - yet you refer to C/C++. Which is
it?</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="idm50877785392"></a><a name="idm50877785136"></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 thing 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.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm50877782032"></a><a name="idm50877781776"></a><p><b>2.</b></p>
</td>
<td align="left" valign="top"><p>Can safe types be used as drop-in replacement 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. In some cases 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="idm50877779696"></a><a name="idm50877779440"></a><p><b>3.</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="idm50877777696"></a><a name="idm50877777440"></a><p><b>4.</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 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="idm50877775344"></a><a name="idm50877775088"></a><p><b>5.</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 "Numeric" 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="idm50877771312"></a><a name="idm50877771056"></a><p><b>6.</b></p>
</td>
<td align="left" valign="top"><p>Isn't putting a defensive check just before any potential
undefined behavior is 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="idm50877768736"></a><a name="idm50877768480"></a><p><b>7.</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 compliment. However,
this has yet to be verified in a rigorous way.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm50877766416"></a><a name="idm50877766160"></a><p><b>8.</b></p>
</td>
<td align="left" valign="top"><p>Why do you specialize <code class="computeroutput">numeric_limits</code> for "safe"
types? Do you need it?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p><code class="computeroutput">safe&lt;T&gt;</code> behaves like a "number" just as int
does. It has max, min, etc Any code which uses numeric limits to test
a type <code class="computeroutput">T</code> should works with <code class="computeroutput">safe&lt;T&gt;</code>.
<code class="computeroutput">safe&lt;T&gt;</code> is a drop-in replacement for <code class="computeroutput">T</code>
so it has to implement all the operations.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="idm50877759872"></a><a name="idm50877759616"></a><p><b>9.</b></p>
</td>
<td align="left" valign="top"><p>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?</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 integers. Also in
many cases, unsigned integers are used in cases where modular
arithmetic is not intended, such as array indexes. Finally, the
modulus for such an integer would vary depending upon the machine
architecture. For these reasons, in the context of this library, an
unsigned integer is considered to 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="idm50877755888"></a><a name="idm50877755632"></a><p><b>10.</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 compiler-time, I could skip
runtime checking on many/most integer operations. C++11 constexpr
wasn't quite enough to do the job. C++14 constexpr can do the job. The
library currently relies very heavily on C++14 constexpr. 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="idm50877752240"></a><a name="idm50877751984"></a><p><b>11.</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++ it's
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">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 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">throw_exception</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">int16_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">int32_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">int16_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="keyword">long</span> <span class="identifier">int32_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 code to address any thrown
exceptions.</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>
</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 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>
Reference in New Issue View Git Blame Copy Permalink