boost/safe_numerics
2
0
Fork 0
mirror of https://github.com/boostorg/safe_numerics.git synced 2026-02-22 03:32:24 +00:00
Code Issues Projects Releases Wiki Activity
Files
e709c9ead4f2ece711a76a7188024c551b65a146
safe_numerics/doc/html/native_policy.html
Robert Ramey 63dd89210e Enabled Boost Book syntax highlighting 
improved TOC and chunking.  This is complicated by the fact we that we desire different depths.
put copies of boost logo in subdirectories
2016-02-07 14:38:06 -08:00

116 lines
11 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>native</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="promotion_policies.html" title="Promotion Policies">
<link rel="prev" href="promotion_policies.html" title="Promotion Policies">
<link rel="next" href="automatic_policy.html" title="automatic">
</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="promotion_policies.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="promotion_policies.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="automatic_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="safe_numerics.native_policy"></a>native</h4></div></div></div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm291788576048"></a>Description</h5></div></div></div>
<p>This type contains the functions to return a safe type corresponding
to the C++ type resulting for a given arithmetic operation.</p>
<p>Usage of this policy with safe types will produce the exact same
arithmetic results that using normal unsafe integer types will. Hence this
policy is suitable as a drop-in replacement for these unsafe types. It's
main function is to trap incorrect arithmetic results when using C++ for
integer arithmetic.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm291788574016"></a>Model of</h5></div></div></div>
<p><a class="link" href="promotion_policy.html" title="PromotionPolicy&lt;PP&gt;">PromotionPolicy</a></p>
<p>As an example of how this works consider C++ rules from section 5 of
the standard - "usual arithmetic conversions".</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">y</span><span class="special">)</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">// z will be of type "int"</span>
<span class="keyword">return</span> <span class="identifier">z</span><span class="special">;</span>
<span class="special">}</span></pre>
<p>According to these rules, z will be of type int. Depending on the
values of x and y, z may or may not contain the correct arithmetic result
of the operation x + y.</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">safe_int</span> <span class="special">=</span> <span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">native</span><span class="special">&gt;</span><span class="special">;</span>
<span class="keyword">void</span> <span class="keyword">int</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">safe_int</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">safe_int</span> <span class="identifier">y</span><span class="special">)</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">// z will be of type "safe_int"</span>
<span class="keyword">return</span> <span class="identifier">z</span><span class="special">;</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm291788537632"></a>Header</h5></div></div></div>
<p><code class="computeroutput"><a href="../../include/native.hpp" target="_top"><code class="computeroutput">#include
&lt;boost/safe_numerics/include/native.hpp&gt;
</code></a></code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm291788535056"></a>Example of use</h5></div></div></div>
<p>The following example illustrates the <code class="computeroutput">native</code> type being
passed as a template parameter for the type <code class="computeroutput">safe&lt;int&gt;</code>.
This example is slightly contrived in that <code class="computeroutput">safe&lt;int&gt;</code>
has <code class="computeroutput">native</code> as it's default promotion parameter so explicitly
using <code class="computeroutput">native</code> is not necessary.</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</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">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">native</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</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">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">;</span>
<span class="comment">// use native promotion policy where C++ standard arithmetic might lead to incorrect results</span>
<span class="keyword">using</span> <span class="identifier">safe_int8</span> <span class="special">=</span> <span class="identifier">safe</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">int8_t</span><span class="special">,</span> <span class="identifier">native</span><span class="special">&gt;</span><span class="special">;</span>
<span class="keyword">try</span><span class="special">{</span>
<span class="identifier">safe_int8</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">127</span><span class="special">;</span>
<span class="identifier">safe_int8</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
<span class="identifier">safe_int8</span> <span class="identifier">z</span><span class="special">;</span>
<span class="comment">// rather than producing and invalid result an exception is thrown</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="identifier">assert</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span><span class="special">;</span> <span class="comment">// never arrive here</span>
<span class="special">}</span>
<span class="keyword">catch</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span><span class="special">{</span>
<span class="comment">// which can catch here</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">(</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="special">}</span>
<span class="comment">// When result is an int, C++ promotion rules guarentee that there will be no incorrect result.</span>
<span class="comment">// In such cases, there is no runtime overhead from using safe types.</span>
<span class="identifier">safe_int8</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">127</span><span class="special">;</span>
<span class="identifier">safe_int8</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
<span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">native</span><span class="special">&gt;</span> <span class="identifier">z</span><span class="special">;</span> <span class="comment">// z can now hold the result of the addition of any two 8 bit numbers</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">// is guarenteed correct without any runtime overhead or interrupt.</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="idm291788452800"></a>Notes</h5></div></div></div>
<p>See Chapter 5, Expressions, C++ Standard</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 &#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="promotion_policies.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="promotion_policies.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="automatic_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink