1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>PromotionPolicy<PP></title> 5<link rel="stylesheet" href="boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Safe Numerics"> 8<link rel="up" href="concepts.html" title="Type Requirements"> 9<link rel="prev" href="safe_numeric_concept.html" title="SafeNumeric<T>"> 10<link rel="next" href="exception_policy.html" title="ExceptionPolicy<EP>"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td> 15<td><h2>Safe Numerics</h2></td> 16</tr></table> 17<div class="spirit-nav"> 18<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> 19</div> 20<div class="section"> 21<div class="titlepage"><div><div><h3 class="title"> 22<a name="safe_numerics.promotion_policy"></a>PromotionPolicy<PP></h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="promotion_policy.html#idm130203778896">Description</a></span></dt> 25<dt><span class="section"><a href="promotion_policy.html#idm130203768304">Notation</a></span></dt> 26<dt><span class="section"><a href="promotion_policy.html#idm130203759120">Valid Expressions</a></span></dt> 27<dt><span class="section"><a href="promotion_policy.html#idm130203734208">Models</a></span></dt> 28<dt><span class="section"><a href="promotion_policy.html#idm130203639168">Header</a></span></dt> 29</dl></div> 30<div class="section"> 31<div class="titlepage"><div><div><h4 class="title"> 32<a name="idm130203778896"></a>Description</h4></div></div></div> 33<p>In C++, arithmetic operations result in types which may or may not 34 be the same as the constituent types. A promotion policy determines the 35 type of the result of an arithmetic operation. For example, in the 36 following code</p> 37<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> 38<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span> 39<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> 40<p>the type of <code class="computeroutput">z</code> will be an 41 <code class="computeroutput">int</code>. This is a consequence for the standard rules for type 42 promotion for C/C++ arithmetic. A key feature of library permits one to 43 specify his own type promotion rules via a PromotionPolicy class.</p> 44</div> 45<div class="section"> 46<div class="titlepage"><div><div><h4 class="title"> 47<a name="idm130203768304"></a>Notation</h4></div></div></div> 48<div class="informaltable"><table class="table"> 49<colgroup> 50<col align="left"> 51<col align="left"> 52</colgroup> 53<tbody> 54<tr> 55<td align="left"><code class="computeroutput">PP</code></td> 56<td align="left">A type that full fills the requirements of a 57 PromotionPollicy</td> 58</tr> 59<tr> 60<td align="left"><code class="computeroutput">T, U</code></td> 61<td align="left">A type that is a model of the Numeric concept</td> 62</tr> 63<tr> 64<td align="left"><code class="computeroutput">R</code></td> 65<td align="left">An object of type modeling Numeric which can be used to 66 construct a SafeNumeric type.</td> 67</tr> 68</tbody> 69</table></div> 70</div> 71<div class="section"> 72<div class="titlepage"><div><div><h4 class="title"> 73<a name="idm130203759120"></a>Valid Expressions</h4></div></div></div> 74<p>Any operations which result in integers which cannot be represented 75 as some Numeric type will throw an exception.These expressions return a 76 type which can be used as the basis create a SafeNumeric type.</p> 77<div class="informaltable"><table class="table"> 78<colgroup> 79<col align="left"> 80<col align="left"> 81</colgroup> 82<thead><tr> 83<th align="left">Expression</th> 84<th align="left">Return Value</th> 85</tr></thead> 86<tbody> 87<tr> 88<td align="left"><code class="computeroutput">PP::addition_result<T, 89 U>::type</code></td> 90<td align="left">unspecified Numeric type</td> 91</tr> 92<tr> 93<td align="left"><code class="computeroutput">PP::subtraction_result<T, 94 U>::type</code></td> 95<td align="left">unspecified Numeric type</td> 96</tr> 97<tr> 98<td align="left"><code class="computeroutput">PP::multiplication_result<T, 99 U>::type</code></td> 100<td align="left">unspecified Numeric type</td> 101</tr> 102<tr> 103<td align="left"><code class="computeroutput">PP::division_result<T, 104 U>::type</code></td> 105<td align="left">unspecified Numeric type</td> 106</tr> 107<tr> 108<td align="left"><code class="computeroutput">PP::modulus_result<T, U>::type</code></td> 109<td align="left">unspecified Numeric type</td> 110</tr> 111<tr> 112<td align="left"><code class="computeroutput">PP::comparison_result<T, 113 U>::type</code></td> 114<td align="left">bool</td> 115</tr> 116<tr> 117<td align="left"><code class="computeroutput">PP::left_shift_result<T, 118 U>::type</code></td> 119<td align="left">unspecified Numeric type</td> 120</tr> 121<tr> 122<td align="left"><code class="computeroutput">PP::right_shift_result<T, 123 u>::type</code></td> 124<td align="left">unspecified Numeric type</td> 125</tr> 126<tr> 127<td align="left"><code class="computeroutput">PP::bitwise_or_result<T, 128 U>::type</code></td> 129<td align="left">unspecified Numeric type</td> 130</tr> 131<tr> 132<td align="left"><code class="computeroutput">PP::bitwise_and_result<T, 133 U>::type</code></td> 134<td align="left">unspecified Numeric type</td> 135</tr> 136<tr> 137<td align="left"><code class="computeroutput">PP::bitwise_xor_result<T, 138 U>::type</code></td> 139<td align="left">unspecified Numeric type</td> 140</tr> 141</tbody> 142</table></div> 143</div> 144<div class="section"> 145<div class="titlepage"><div><div><h4 class="title"> 146<a name="idm130203734208"></a>Models</h4></div></div></div> 147<p>The library contains a number of pre-made promotion policies:</p> 148<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 149<li class="listitem"> 150<p><a name="safe_numerics.promotion_policy.models.native"></a><code class="computeroutput">boost::numeric::native</code></p> 151<p>Use the normal C/C++ expression type promotion rules. 152 </p> 153<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> 154<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span> 155<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> 156<span class="identifier">safe</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">native</span><span class="special">></span> <span class="identifier">sx</span><span class="special">;</span> 157<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">// standard C++ code which detects errors</span></pre> 158<p>Type sz will be a <a class="link" href="safe_numeric_concept.html" title="SafeNumeric<T>">SafeNumeric</a> type 159 based on <code class="computeroutput">int</code>. If the result exceeds the maximum value 160 that can be stored in an <code class="computeroutput">int</code>, an error is 161 detected.</p> 162<p>The <code class="computeroutput">native</code> policy is documented in <a class="link" href="promotion_policies/native.html" title="native">Promotion Policies - 163 native</a>.</p> 164</li> 165<li class="listitem"> 166<p><a name="safe_numerics.promotion_policy.models.automatic"></a><code class="computeroutput">boost::numeric::automatic</code></p> 167<p>Use optimizing expression type promotion rules. These rules 168 replace the normal C/C++ type promotion rules with other rules which 169 are designed to result in more efficient computations. Expression 170 types are promoted to the smallest type which can be guaranteed to 171 hold the result without overflow. If there is no such type, the result 172 will be checked for overflow. Consider the following 173 example:</p> 174<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> 175<span class="keyword">char</span> <span class="identifier">y</span><span class="special">;</span> 176<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> 177<span class="identifier">safe</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">automatic</span><span class="special">></span> <span class="identifier">sx</span><span class="special">;</span> 178<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> 179 <span class="comment">// sz is a safe type based on long</span> 180 <span class="comment">// hence sz is guaranteed not to overflow.</span> 181<span class="identifier">safe_unsigned_range</span><span class="special"><</span><span class="number">1</span><span class="special">,</span> <span class="number">4</span><span class="special">></span> <span class="identifier">a</span><span class="special">;</span> 182<span class="identifier">safe_unsigned_range</span><span class="special"><</span><span class="number">2</span><span class="special">,</span> <span class="number">4</span><span class="special">></span> <span class="identifier">b</span><span class="special">;</span> 183<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 a safe type with a range [3,8] and cannot overflow</span> 184</pre> 185<p>Type sz will be a <a class="link" href="safe_numeric_concept.html" title="SafeNumeric<T>">SafeNumeric</a> type 186 which is guaranteed to hold he result of x + y. In this case that will 187 be a long int (or perhaps a long long) depending upon the compiler and 188 machine architecture. In this case, there will be no need for any 189 special checking on the result and there can be no overflow.</p> 190<p>Type of c will be a signed character as that type can be 191 guaranteed to hold the sum so no overflow checking is done.</p> 192<p>This policy is documented in <a class="link" href="promotion_policies/automatic.html" title="automatic">Promotion 193 Policies - automatic</a></p> 194</li> 195<li class="listitem"> 196<p>boost::numeric::cpp</p> 197<p>Use expression type promotion rules to emulate another 198 processor. When this policy is used, C++ type for safe integers 199 follows the rules that a compiler on the target processor would use. 200 This permits one to test code destined for a one processor on the 201 another one. One situation there this can be very, very useful is when 202 testing code destined for a micro controller which doesn't have the 203 logging, debugging, input/output facilities of a 204 desktop.</p> 205<pre class="programlisting"><span class="comment">// specify a promotion policy to support proper emulation of </span> 206<span class="comment">// PIC 18f2520 types on the desktop</span> 207<span class="keyword">using</span> <span class="identifier">pic16_promotion</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">cpp</span><span class="special"><</span> 208 <span class="number">8</span><span class="special">,</span> <span class="comment">// char 8 bits</span> 209 <span class="number">16</span><span class="special">,</span> <span class="comment">// short 16 bits</span> 210 <span class="number">16</span><span class="special">,</span> <span class="comment">// int 16 bits</span> 211 <span class="number">16</span><span class="special">,</span> <span class="comment">// long 16 bits</span> 212 <span class="number">32</span> <span class="comment">// long long 32 bits</span> 213<span class="special">></span><span class="special">;</span> 214<span class="special">...</span> 215<span class="identifier">safe</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">uint16_t</span><span class="special">,</span> <span class="identifier">pic16_promotion</span><span class="special">></span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">;</span> 216<span class="special">...</span> 217 218<span class="identifier">x</span> <span class="special">+</span> <span class="identifier">y</span><span class="special">;</span> <span class="comment">// detect possible overflow on the pic.</span></pre> 219<p>For a complete example see <a class="link" href="safety_critical_embedded_controller.html" title="Safety Critical Embedded Controller">Safety 220 Critical Embedded Controller</a>.</p> 221</li> 222</ul></div> 223</div> 224<div class="section"> 225<div class="titlepage"><div><div><h4 class="title"> 226<a name="idm130203639168"></a>Header</h4></div></div></div> 227<p><a href="../../include/concept/promotion_policy.hpp" target="_top"><code class="computeroutput">#include 228 <boost/numeric/safe_numerics/concepts/promotion_policy.hpp> 229 </code></a></p> 230</div> 231</div> 232<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 233<td align="left"></td> 234<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 235 Software License</a></p> 236</div></td> 237</tr></table> 238<hr> 239<div class="spirit-nav"> 240<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> 241</div> 242</body> 243</html> 244
