1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN" 3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<section id="safe_numerics.promotion_policy"> 5 <title>PromotionPolicy<PP></title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>In C++, arithmetic operations result in types which may or may not 13 be the same as the constituent types. A promotion policy determines the 14 type of the result of an arithmetic operation. For example, in the 15 following code<programlisting>int x; 16char y; 17auto z = x + y</programlisting>the type of <code>z</code> will be an 18 <code>int</code>. This is a consequence for the standard rules for type 19 promotion for C/C++ arithmetic. A key feature of library permits one to 20 specify his own type promotion rules via a PromotionPolicy class.</para> 21 </section> 22 23 <section> 24 <title>Notation</title> 25 26 <informaltable> 27 <tgroup cols="2" colsep="1" rowsep="1"> 28 <colspec align="left" colwidth="1*"/> 29 30 <colspec align="left" colwidth="4*"/> 31 32 <tbody> 33 <row> 34 <entry><code>PP</code></entry> 35 36 <entry>A type that full fills the requirements of a 37 PromotionPollicy</entry> 38 </row> 39 40 <row> 41 <entry><code>T, U</code></entry> 42 43 <entry>A type that is a model of the Numeric concept</entry> 44 </row> 45 46 <row> 47 <entry><code>R</code></entry> 48 49 <entry>An object of type modeling Numeric which can be used to 50 construct a SafeNumeric type.</entry> 51 </row> 52 </tbody> 53 </tgroup> 54 </informaltable> 55 </section> 56 57 <section> 58 <title>Valid Expressions</title> 59 60 <para>Any operations which result in integers which cannot be represented 61 as some Numeric type will throw an exception.These expressions return a 62 type which can be used as the basis create a SafeNumeric type.</para> 63 64 <para><informaltable> 65 <tgroup cols="2"> 66 <colspec align="left"/> 67 68 <colspec align="left"/> 69 70 <thead> 71 <row> 72 <entry align="left">Expression</entry> 73 74 <entry>Return Value</entry> 75 </row> 76 </thead> 77 78 <tbody> 79 <row> 80 <entry><code>PP::addition_result<T, 81 U>::type</code></entry> 82 83 <entry>unspecified Numeric type</entry> 84 </row> 85 86 <row> 87 <entry><code>PP::subtraction_result<T, 88 U>::type</code></entry> 89 90 <entry>unspecified Numeric type</entry> 91 </row> 92 93 <row> 94 <entry><code>PP::multiplication_result<T, 95 U>::type</code></entry> 96 97 <entry>unspecified Numeric type</entry> 98 </row> 99 100 <row> 101 <entry><code>PP::division_result<T, 102 U>::type</code></entry> 103 104 <entry>unspecified Numeric type</entry> 105 </row> 106 107 <row> 108 <entry><code>PP::modulus_result<T, U>::type</code></entry> 109 110 <entry>unspecified Numeric type</entry> 111 </row> 112 113 <row> 114 <entry><code>PP::comparison_result<T, 115 U>::type</code></entry> 116 117 <entry>bool</entry> 118 </row> 119 120 <row> 121 <entry><code>PP::left_shift_result<T, 122 U>::type</code></entry> 123 124 <entry>unspecified Numeric type</entry> 125 </row> 126 127 <row> 128 <entry><code>PP::right_shift_result<T, 129 u>::type</code></entry> 130 131 <entry>unspecified Numeric type</entry> 132 </row> 133 134 <row> 135 <entry><code>PP::bitwise_or_result<T, 136 U>::type</code></entry> 137 138 <entry>unspecified Numeric type</entry> 139 </row> 140 141 <row> 142 <entry><code>PP::bitwise_and_result<T, 143 U>::type</code></entry> 144 145 <entry>unspecified Numeric type</entry> 146 </row> 147 148 <row> 149 <entry><code>PP::bitwise_xor_result<T, 150 U>::type</code></entry> 151 152 <entry>unspecified Numeric type</entry> 153 </row> 154 </tbody> 155 </tgroup> 156 </informaltable></para> 157 </section> 158 159 <section> 160 <title>Models</title> 161 162 <para>The library contains a number of pre-made promotion policies:</para> 163 164 <itemizedlist> 165 <listitem id="safe_numerics.promotion_policy.models.native"> 166 <para><code>boost::numeric::native</code></para> 167 168 <para>Use the normal C/C++ expression type promotion rules. 169 <programlisting name="cpp">int x; 170char y; 171auto z = x + y; // could result in overflow 172safe<int, native> sx; 173auto sz = sx + y; // standard C++ code which detects errors</programlisting></para> 174 175 <para>Type sz will be a <link 176 linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link> type 177 based on <code>int</code>. If the result exceeds the maximum value 178 that can be stored in an <code>int</code>, an error is 179 detected.</para> 180 181 <para>The <code>native</code> policy is documented in <link 182 linkend="safe_numerics.promotion_policies.native">Promotion Policies - 183 native</link>.</para> 184 </listitem> 185 186 <listitem id="safe_numerics.promotion_policy.models.automatic"> 187 <para><code>boost::numeric::automatic</code></para> 188 189 <para>Use optimizing expression type promotion rules. These rules 190 replace the normal C/C++ type promotion rules with other rules which 191 are designed to result in more efficient computations. Expression 192 types are promoted to the smallest type which can be guaranteed to 193 hold the result without overflow. If there is no such type, the result 194 will be checked for overflow. Consider the following 195 example:<programlisting>int x; 196char y; 197auto z = x + y; // could result in overflow 198safe<int, automatic> sx; 199auto sz = sx + y; 200 // sz is a safe type based on long 201 // hence sz is guaranteed not to overflow. 202safe_unsigned_range<1, 4> a; 203safe_unsigned_range<2, 4> b; 204auto c = a + b; // c will be a safe type with a range [3,8] and cannot overflow 205</programlisting></para> 206 207 <para>Type sz will be a <link 208 linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link> type 209 which is guaranteed to hold he result of x + y. In this case that will 210 be a long int (or perhaps a long long) depending upon the compiler and 211 machine architecture. In this case, there will be no need for any 212 special checking on the result and there can be no overflow.</para> 213 214 <para>Type of c will be a signed character as that type can be 215 guaranteed to hold the sum so no overflow checking is done.</para> 216 217 <para>This policy is documented in <link 218 linkend="safe_numerics.promotion_policies.automatic">Promotion 219 Policies - automatic</link></para> 220 </listitem> 221 222 <listitem> 223 <para>boost::numeric::cpp</para> 224 225 <para>Use expression type promotion rules to emulate another 226 processor. When this policy is used, C++ type for safe integers 227 follows the rules that a compiler on the target processor would use. 228 This permits one to test code destined for a one processor on the 229 another one. One situation there this can be very, very useful is when 230 testing code destined for a micro controller which doesn't have the 231 logging, debugging, input/output facilities of a 232 desktop.<programlisting>// specify a promotion policy to support proper emulation of 233// PIC 18f2520 types on the desktop 234using pic16_promotion = boost::numeric::cpp< 235 8, // char 8 bits 236 16, // short 16 bits 237 16, // int 16 bits 238 16, // long 16 bits 239 32 // long long 32 bits 240>; 241... 242safe<std::uint16_t, pic16_promotion> x, y; 243... 244 245x + y; // detect possible overflow on the pic.</programlisting></para> 246 247 <para>For a complete example see <link 248 linkend="safe_numerics.safety_critical_embedded_controller">Safety 249 Critical Embedded Controller</link>.</para> 250 </listitem> 251 </itemizedlist> 252 </section> 253 254 <section> 255 <title>Header</title> 256 257 <para><ulink 258 url="../../include/boost/safe_numerics/concept/promotion_policy.hpp"><code>#include 259 <boost/numeric/safe_numerics/concepts/promotion_policy.hpp> 260 </code></ulink></para> 261 </section> 262</section> 263