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_policies.automatic"> 5 <title>automatic</title> 6 7 <section> 8 <title>Description</title> 9 10 <para>This type contains the meta-functions to return a type with 11 sufficient capacity to hold the result of a given binary arithmetic 12 operation.</para> 13 14 <para>The standard C/C++ procedure for executing arithmetic operations on 15 operands of different types is:<itemizedlist> 16 <listitem> 17 <para>Convert operands to some common type using a somewhat 18 elaborate elaborate rules defined in the C++ standard.</para> 19 </listitem> 20 21 <listitem> 22 <para>Execute the operation.</para> 23 </listitem> 24 25 <listitem> 26 <para>If the result of the operation cannot fit in the common type 27 of the operands, discard the high order bits.</para> 28 </listitem> 29 </itemizedlist></para> 30 31 <para>The automatic promotion policy replaces the standard C/C++ procedure 32 for the following one:<itemizedlist> 33 <listitem> 34 <para>Convert operands to some common type using to the following 35 rules.<itemizedlist> 36 <listitem> 37 <para>For addition. If the operands are both unsigned the 38 common type will be unsigned. Otherwise it will be 39 signed.</para> 40 </listitem> 41 42 <listitem> 43 <para>For subtraction, the common type will be signed.</para> 44 </listitem> 45 46 <listitem> 47 <para>For left/right shift, the sign of the result will be the 48 sign of the left operand.</para> 49 </listitem> 50 51 <listitem> 52 <para>For all other types of operants, if both operands are 53 unsigned the common type will be unsigned. Otherwise, it will 54 be signed.</para> 55 </listitem> 56 </itemizedlist></para> 57 </listitem> 58 59 <listitem> 60 <para>Determine the smallest size of the signed or unsigned type 61 which can be guaranteed hold the result.</para> 62 </listitem> 63 64 <listitem> 65 <para>If this size exceeds the maximum size supported by the 66 compiler, use the maximum size supported by the compiler.</para> 67 </listitem> 68 69 <listitem> 70 <para>Execute the operation.<itemizedlist> 71 <listitem> 72 <para>Convert each operand to the common type.</para> 73 </listitem> 74 75 <listitem> 76 <para>If the result cannot be contained in the result type as 77 above, invoke an error procedure.</para> 78 </listitem> 79 80 <listitem> 81 <para>Otherwise, return the result in the common type</para> 82 </listitem> 83 </itemizedlist></para> 84 </listitem> 85 </itemizedlist></para> 86 87 <para>This type promotion policy is applicable only to safe types whose 88 base type is an <link linkend="safe_numerics.integer">Integer</link> 89 type.</para> 90 </section> 91 92 <section> 93 <title>Model of</title> 94 95 <para><link 96 linkend="safe_numerics.promotion_policy">PromotionPolicy</link></para> 97 </section> 98 99 <section> 100 <title>Example of use</title> 101 102 <para>The following example illustrates the <code>automatic</code> type 103 being passed as a template parameter for the type 104 <code>safe<int></code>.</para> 105 106 <programlisting>#include <boost/safe_numerics/safe_integer.hpp> 107#include <boost/safe_numerics/automatic.hpp> 108 109int main(){ 110 using namespace boost::numeric; 111 // use automatic promotion policy where C++ standard arithmetic 112 // might lead to incorrect results 113 using safe_t = safe<std::int8_t, automatic>; 114 115 // In such cases, there is no runtime overhead from using safe types. 116 safe_t x = 127; 117 safe_t y = 2; 118 // z is guaranteed correct without any runtime overhead or exception. 119 auto z = x + y; 120 return 0; 121}</programlisting> 122 </section> 123 124 <section> 125 <title>Header</title> 126 127 <para><code><ulink 128 url="../../include/boost/safe_numerics/automatic.hpp"><code>#include 129 <boost/numeric/safe_numerics/automatic.hpp> 130 </code></ulink></code></para> 131 </section> 132</section> 133