townforge/safe_numerics
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
97100f96fe
safe_numerics/doc/html/promotion_policy.html

193 lines
12 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>PromotionPolicy&lt;PP&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="safe_numeric_concept.html" title="SafeNumeric&lt;T&gt;">
<link rel="next" href="exception_policy.html" title="ExceptionPolicy&lt;EP&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="safe_numeric_concept.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="exception_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.promotion_policy"></a>PromotionPolicy&lt;PP&gt;</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="promotion_policy.html#idm541779204208">Description</a></span></dt>
<dt><span class="section"><a href="promotion_policy.html#idm541779193616">Notation</a></span></dt>
<dt><span class="section"><a href="promotion_policy.html#idm541779184736">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="promotion_policy.html#idm541779165632">Header</a></span></dt>
<dt><span class="section"><a href="promotion_policy.html#idm541779163376">Models</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm541779204208"></a>Description</h4></div></div></div>
<p>In C++, arithmetic operations result in types which may or may not
be the same as the constituent types. A promotion policy determines the
type of the result of an arithmetic operation. For example, in the
following code</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span></pre>
<p>the type of <code class="computeroutput">z</code> will be an
<code class="computeroutput">int</code>. This is a consequence for the standard rules for type
promotion for C/C++ arithmetic. A key feature of library permits one to
specify his own type promotion rules via a PromotionPolicy class.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm541779193616"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<tbody>
<tr>
<td align="left"><code class="computeroutput">PP</code></td>
<td align="left">A type that full fills the requirements of a
PromotionPollicy</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">T, U, V</code></td>
<td align="left">A type that is a model of the Numeric concept</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t, u, v</code></td>
<td align="left">An object of type modeling Numeric</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm541779184736"></a>Valid Expressions</h4></div></div></div>
<p>Any operations which result in integers which cannot be represented
as some Numeric type will throw an exception.</p>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Return Value</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">PP::addition_result&lt;T,
U&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::subtraction_result&lt;T,
U&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::multiplication_result&lt;T,
U&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::division_result&lt;T,
U&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::modulus_result&lt;T, U&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::left_shift_result&lt;T&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::right_shift_result&lt;T&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
<tr>
<td align="left"><code class="computeroutput">PP::bitwise_result&lt;T&gt;::type</code></td>
<td align="left">unspecified Numeric type</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm541779165632"></a>Header</h4></div></div></div>
<p><a href="../../include/concept/promotion_policy.hpp" target="_top"><code class="computeroutput">#include
&lt;safe_numerics/include/concepts/promotion_policy.hpp&gt;
</code></a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm541779163376"></a>Models</h4></div></div></div>
<p>The library contains a number of pre-made promotion policies:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><a name="safe_numerics.promotion_policy.models.native"></a><code class="computeroutput">boost::numeric::native</code></p>
<p>Use the normal C/C++ expression type promotion rules.
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// could result in overflow</span>
<span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">sx</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">sz</span> <span class="special">=</span> <span class="identifier">sx</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// includes code which traps overflows at runtime</span></pre>
<p>The type of sz will be safe&lt; type of z &gt;.</p>
<p>This policy is documented in <a class="link" href="promotion_policies/native.html" title="native">Promotion Policies -
native</a>.</p>
</li>
<li class="listitem">
<p><a name="safe_numerics.promotion_policy.models.automatic"></a><code class="computeroutput">boost::numeric::automatic</code></p>
<p>Use optimizing expression type promotion rules. These rules
replace the normal C/C++ type promotion rules with other rules which
are designed to result in more efficient computations. Expression
types are promoted to the smallest type which can be guaranteed to
hold the result without overflow. If there is no such type, the result
will be checked for overflow. Consider the following
example:</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">z</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// could result in overflow</span>
<span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">sx</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">sz</span> <span class="special">=</span> <span class="identifier">sx</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// promotes expression type to a safe&lt;long int&gt; which requires no result checking</span>
<span class="identifier">is</span> <span class="identifier">guaranteed</span> <span class="identifier">not</span> <span class="identifier">to</span> <span class="identifier">overflow</span><span class="special">.</span>
<span class="identifier">safe_unsigned_range</span><span class="special">&lt;</span><span class="number">1</span><span class="special">,</span> <span class="number">4</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">;</span>
<span class="identifier">safe_unsigned_range</span><span class="special">&lt;</span><span class="number">2</span><span class="special">,</span> <span class="number">4</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">;</span>
<span class="keyword">auto</span> <span class="identifier">c</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// c will be of type safe_unsigned_range&lt;3, 8&gt; and cannot overflow</span></pre>
<p>Type sz will be a <a class="link" href="safe_numeric_concept.html" title="SafeNumeric&lt;T&gt;">SafeNumeric</a> type
which is guaranteed to hold he result of x + y. In this case that will
be a long int (or perhaps a long long) depending upon the compiler and
machine architecture. In this case, there will be no need for any
special checking on the result and there can be no overflow.</p>
<p>Type of c will be a signed character as that type can be
guaranteed to hold the sum so no overflow checking is done.</p>
<p>This policy is documented in <a class="link" href="promotion_policies/automatic.html" title="automatic">Promotion Policies -
automatic</a></p>
</li>
</ul></div>
</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="safe_numeric_concept.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="exception_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink