123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122 |
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
- <title>Library Implementation</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="exception_safety.html" title="Exception Safety">
- <link rel="next" href="checked_result.html" title="checked_result<R>">
- </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="exception_safety.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="checked_result.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.library_implementation"></a>Library Implementation</h2></div></div></div>
- <div class="toc"><dl class="toc">
- <dt><span class="section"><a href="checked_result.html">checked_result<R></a></span></dt>
- <dt><span class="section"><a href="checked_arithmetic.html">Checked Arithmetic</a></span></dt>
- <dt><span class="section"><a href="interval.html">interval<R></a></span></dt>
- <dt><span class="section"><a href="checked_integer_arithmetic.html">safe_compare<T, U></a></span></dt>
- </dl></div>
- <p>This library should compile and run correctly on any conforming
- C++14 compiler.</p>
- <p>The Safe Numerics library is implemented in terms of some more
- fundamental software components described here. It is not necessary to
- know about these components to use the library. This information has been
- included to help those who want to understand how the library works so
- they can extend it, correct bugs in it, or understand its limitations.
- These components are also interesting and likely useful in their own
- right. For all these reasons, they are documented here.</p>
- <p>In general terms, the library works in the following manner:</p>
- <p>At compile time:</p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem"><p>The library defines "safe" versions of C++ primitive arithmetic
- types such as <code class="computeroutput">int</code>, <code class="computeroutput">unsigned int</code>, etc.</p></li>
- <li class="listitem"><p>Arithmetic operators are defined for these "safe" types. These
- operators are enhanced versions of the standard C/C++ implementations.
- These operators are declared and implemented in the files "<a href="../../include/boost/safe_numerics/safe_base.hpp" target="_top">safe_base.hpp</a>"
- and "<a href="../../include/boost/safe_numerics/safe_base_operations.hpp" target="_top">safe_base_operations.hpp</a>".</p></li>
- <li class="listitem"><p>For binary operators, verify that both operands have the same
- promotion and and exception handling policies. If they don't, invoke
- compilation error.</p></li>
- <li class="listitem"><p>Invoke the promotion policy to determine the result type R of
- the operation.</p></li>
- <li class="listitem"><p>For each operand of type T retrieve the range of values from
- <code class="computeroutput">std::numeric_limits<T>::min()</code> and
- <code class="computeroutput">std::numeric_limits<T>::max()</code>. A range is a pair of
- values representing a closed interval with a minimum and maximum
- value.</p></li>
- <li class="listitem"><p>These ranges are cast to equivalent values of the result type,
- R. It's possible that values cannot be cast to the result type so the
- result of the cast is returned as a variant type, <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.
- <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>
- may hold either a value of type R or a <a class="link" href="exception.html#safe_numerics.safe_numerics_error" title="enum class safe_numerics_error"><code class="computeroutput">safe_numerics_error</code></a>
- value indicating why the cast could not be accomplished. Ranges are
- represented as a pair of values of the type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li>
- <li class="listitem"><p><a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>
- can be considered enhanced versions of the underlying type R.
- Operations which are legal on values of type R such as +, -, ... are
- also legal on values of <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.
- The difference is that the latter can record operation failures and
- propagate such failures to subsequent operations.<a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>
- is implemented in the header file "<a href="../../include/boost/safe_numerics/checked_result.hpp" target="_top">checked_result.hpp</a>".
- Operations on such types are implemented in "<a href="../../include/boost/safe_numerics/checked_result_operations.hpp" target="_top">checked_result_operations.hpp</a>".</p></li>
- <li class="listitem"><p>Given the ranges of the operands, determine the range of the
- result of the operation using compile-time interval arithmetic. The
- <code class="computeroutput">constexpr</code> facility of C++14 permits the range of the
- result to be calculated at compile time. Interval arithmetic is
- implemented in the header file "<a href="../../include/boost/safe_numerics/interval.hpp" target="_top">interval.hpp</a>".
- The range of the result is also represented as a pair of values of the
- type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li>
- <li class="listitem"><p>Operations on primitives are implemented via free standing
- functions described as <a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>.
- These operations will return instances of <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>
- .</p></li>
- </ul></div>
- <p>At run time:</p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem"><p>If the range of the result type includes only arithmetically
- valid values, the operation is guaranteed to produce an arithmetically
- correct result and no runtime checking is necessary. The operation
- invokes the original built-in C/C++ operation and returns the result
- value.</p></li>
- <li class="listitem"><p>Otherwise, operands are cast to the result type, R, according to
- the selected promotion policy. These "checked" cast operations return
- values of type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.</p></li>
- <li class="listitem"><p>If either of the casting operations fails, an exception is
- handled in accordance with the exception policy.</p></li>
- <li class="listitem"><p>Otherwise, the operation is performed using "<a class="link" href="checked_arithmetic.html" title="Checked Arithmetic">checked arithmetic</a>".
- These free functions mirror the normal operators +, -, *, ... except
- that rather than returning values of type R, they return values of the
- type <a class="link" href="checked_result.html" title="checked_result<R>"><code class="computeroutput">checked_result<R></code></a>.
- They are defined in files "<a href="../../include/boost/safe_numerics/checked_default.hpp" target="_top">checked_default.hpp</a>",
- "<a href="../../include/boost/safe_numerics/checked_integer.hpp" target="_top">checked_integer.hpp</a>"
- ,"<a href="../../include/boost/safe_numerics/checked_float.hpp" target="_top">checked_float.hpp</a>".</p></li>
- <li class="listitem"><p>If the operation is not successful, the designated exception
- policy function is invoked.</p></li>
- <li class="listitem"><p>Otherwise, the result value is returned as a
- <code class="computeroutput">safe<R></code> type with the above calculated result
- range.</p></li>
- </ul></div>
- <p>The following components realize the design described here.</p>
- </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="exception_safety.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="checked_result.html"><img src="images/next.png" alt="Next"></a>
- </div>
- </body>
- </html>
|