a06d9f7a69
added tests for check result < and == operations correct implementation of some checked result types added constexpr example
123 lines
9.8 KiB
HTML
123 lines
9.8 KiB
HTML
<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>
|