generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
main
boost/libs/safe_numerics/doc/html/safe_numeric_concept.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

325 lines
16 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SafeNumeric&lt;T&gt;</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="concepts.html" title="Type Requirements">
<link rel="prev" href="integer.html" title="Integer&lt;T&gt;">
<link rel="next" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;">
</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="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.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="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.safe_numeric_concept"></a>SafeNumeric&lt;T&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720563920">Description</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720562464">Refinement of</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720560112">Notation</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720542640">Associated Types</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720533984">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720454272">Invariants</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720452672">Models</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm488720448336">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720563920"></a>Description</h4></div></div></div>
<p>This holds an arithmetic value which can be used as a replacement
for built-in C++ arithmetic values. These types differ from their built-in
counter parts in that the are guaranteed not to produce invalid arithmetic
results. These operations return safe types rather than built-in
types.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720562464"></a>Refinement of</h4></div></div></div>
<p><a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a> or <a class="link" href="integer.html" title="Integer&lt;T&gt;">Integer</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720560112"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">T, U</code></td>
<td align="left">Types fulfilling <a class="link" href="numeric.html" title="Numeric&lt;T&gt;">Numeric</a> or <a class="link" href="integer.html" title="Integer&lt;T&gt;">Integer</a> type
requirements.</td>
</tr>
<tr>
<td align="left">t, u</td>
<td align="left">objects of types T, U</td>
</tr>
<tr>
<td align="left">S</td>
<td align="left">A type fulfilling SafeNumeric type requirements</td>
</tr>
<tr>
<td align="left">s, s1, s2</td>
<td align="left">objects of types S</td>
</tr>
<tr>
<td align="left">op</td>
<td align="left">C++ infix operator supported by underlying type T</td>
</tr>
<tr>
<td align="left">prefix_op</td>
<td align="left">C++ prefix operator: -, +, ~, ++, -- supported by
underlying type T</td>
</tr>
<tr>
<td align="left">postfix_op</td>
<td align="left">C++ postfix operator:++, -- supported by underlying type
T</td>
</tr>
<tr>
<td align="left">assign_op</td>
<td align="left">C++ assignment operator</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720542640"></a>Associated Types</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><a class="link" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;"><code class="computeroutput">PromotionPolicy</code></a></td>
<td align="left">In C++ expressions, arguments must be of the same type. If
they are not, all arguments are converted to a common type in
accordance with rules of the C++ standard. For some applications
of the safe numerics library, we might want conversions which are
different than the standard ones. This class type implements the
conversion functions that are to be used with the safe numeric
type being instantiated.</td>
</tr>
<tr>
<td align="left"><a class="link" href="exception_policy.html" title="ExceptionPolicy&lt;EP&gt;"><code class="computeroutput">ExceptionPolicy</code></a></td>
<td align="left">The exception policy specifies what is to occur when a safe
operation cannot return a valid result. A type is an
ExceptionPolicy if it has specific functions for handling
exceptional events that occur in the course of safe numeric
operations.</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720533984"></a>Valid Expressions</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Result Type</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">s op t</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t op s</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s1 op s2</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">prefix_op S</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">prefix_op</code> and
return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S postfix_op</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">postfix_op</code> and
return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s assign_op t</code></td>
<td align="left">S &amp;</td>
<td align="left"><p>convert t to type S and assign it to s.
</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t assign_op s</code></td>
<td align="left">T &amp;</td>
<td align="left"><p>convert s to type T and assign it to s. If the
value t cannot be represented as an instance of type S, it is an
error.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S(t)</code></td>
<td align="left">S</td>
<td align="left"><p>construct an instance of S from a value of type T.
In this case, T is referred to as the base type of S. If the
value t cannot be represented as an instance of type S, it is an
exception condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S</code></td>
<td align="left">S</td>
<td align="left"><p>construct an uninitialized instance of
S.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">T(s)</code></td>
<td align="left">T</td>
<td align="left"><p>implicit conversion of the value of s to type T. If
the value of s cannot be correctly represented as a type T, an
exception condition is invoked.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast&lt;T&gt;(s)</code></td>
<td align="left">T</td>
<td align="left"><p>convert the value of s to type T. If the value of s
cannot be correctly represented as a type T, an exception
condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">is_safe&lt;S&gt;</code></td>
<td align="left"><code class="computeroutput">std::true_type</code></td>
<td align="left"><p>type trait to query whether any type S fulfills the
requirements for a SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">get_promotion_policy&lt;S&gt;</code></td>
<td align="left">S</td>
<td align="left"><p>Retrieve the <a class="link" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;"><code class="computeroutput">PromotionPolicy</code></a><code class="computeroutput">
which is used by the specified safe type</code>.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">get_exception_policy&lt;S&gt;</code></td>
<td align="left">S</td>
<td align="left"><p>Retrieve the <a class="link" href="exception_policy.html" title="ExceptionPolicy&lt;EP&gt;"><code class="computeroutput">ExceptionPolicy</code></a>
which is used by the specified safe type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_type&lt;S&gt;::type</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the base type of a given safe
type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_value(s)</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the value of an instance of a safe type.
This is equivalent to
<code class="computeroutput">static_cast&lt;base_type&lt;S&gt;&gt;(s)</code>.</p></td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The result of any binary operation where one or both of the
operands is a SafeNumeric type is also a SafeNumeric type. The
specific type is determined by the promotion rules implement in the
PromotionPolicy returned by get_promotion_policy&lt;S&gt; where S is
the result type.</p></li>
<li class="listitem"><p>All the expressions in the above table are
<code class="computeroutput">constexpr</code> expressions.</p></li>
<li class="listitem"><p>Binary expressions which are not assignments and whose operands
are both safe types require that promotion and exception policies of
the operands be identical.</p></li>
<li class="listitem"><p><code class="computeroutput">Operations on safe types are supported if and only if the
same operation is supported on the underlying types. For example, the
binary operations |</code>, <code class="computeroutput">&amp;</code>, <code class="computeroutput">^</code> and
<code class="computeroutput">~</code> operations defined for safe unsigned integer types. But
they are not defined for floating point types. Currently the are also
defined for signed integer types. It's not clear that this is the
correct decision. On one hand, usage of these operators on signed
types is almost certainly an error in program logic. But trapping this
as an error conflicts with the goal of making safe types "drop-in"
replacements for the corresponding built-in types. In light of this,
these operators are currently supported as they are for normal
built-in types.</p></li>
<li class="listitem">
<p>Safe Numeric types will be implicitly converted to built-in
types when appropriate. Here's an example:</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span>
<span class="keyword">long</span> <span class="identifier">x</span><span class="special">;</span>
<span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span><span class="special">;</span> <span class="comment">// OK - builtin implicit version</span>
<span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">y</span><span class="special">;</span>
<span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span></pre>
<p>This behavior supports the concept of
<code class="computeroutput">safe&lt;T&gt;</code> as being a "drop-in" replacement for a
<code class="computeroutput">T</code>.</p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720454272"></a>Invariants</h4></div></div></div>
<p>The fundamental requirement of a SafeNumeric type is that it
implements all C++ operations permitted on its base type in a way the
prevents the return of an incorrect arithmetic result. Various
implementations of this concept may handle circumstances which produce
such results differently (throw exception, compile time trap, etc..). But
no implementation should return an arithmetically incorrect result.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720452672"></a>Models</h4></div></div></div>
<p><code class="computeroutput">safe&lt;T&gt;</code></p>
<p><code class="computeroutput">safe_signed_range&lt;-11, 11&gt;</code></p>
<p><code class="computeroutput">safe_unsigned_range&lt;0, 11&gt;</code></p>
<p><code class="computeroutput">safe_signed_literal&lt;4&gt;</code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm488720448336"></a>Header</h4></div></div></div>
<p><a href="../../include/boost/safe_numerics/concept/safe_numeric.hpp" target="_top"><code class="computeroutput">#include
&lt;boost/safe_numerics/concepts/safe_numeric.hpp&gt;</code></a></p>
</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="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.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="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink