123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439 |
- <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<42>? Why not just use
- std::integral_const<int, 42>?</a>
- </dt>
- <dt>4. <a href="rationale.html#idm130201774080">Why is safe...literal needed at all? What's the matter with
- const safe<int>(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<42></code>? Why not just use
- std::integral_const<int, 42>?</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<42></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<int>(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<int>(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<safe<int>></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<Value, PP , EP> and safe_unsigned_literal<Value, PP, EP>"><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<int, 42></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<std::integral_constant<int,
- 42>>::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<std::integral_constant<int,
- 42>></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<float></code> and related types as well as new types
- like <code class="computeroutput">safe<fixed_decimal></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>], “Ensure that unsigned
- integer operations do not wrap” 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"><</span><span class="identifier">cstdint</span><span class="special">></span>
- <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>
- <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>
- <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>
- <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">></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"><</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>
- <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>
- <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">></span><span class="special">;</span>
- <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>
- <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>
- <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 © 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>
|