ceph/src/boost/libs/multiprecision/doc/html/boost_multiprecision/tut/ints/cpp_int.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>cpp_int</title>
   5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../../index.html" title="Chapter&#160;1.&#160;Boost.Multiprecision">
   8 <link rel="up" href="../ints.html" title="Integer Types">
   9 <link rel="prev" href="../ints.html" title="Integer Types">
  10 <link rel="next" href="gmp_int.html" title="gmp_int">
  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 alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../ints.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ints.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gmp_int.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="boost_multiprecision.tut.ints.cpp_int"></a><a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
  28 </h4></div></div></div>
  29 <p>
  30           <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_int</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
  31         </p>
  32 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">multiprecision</span><span class="special">{</span>
  33
  34 <span class="keyword">typedef</span> <span class="identifier">unspecified</span><span class="special">-</span><span class="identifier">type</span> <span class="identifier">limb_type</span><span class="special">;</span>
  35
  36 <span class="keyword">enum</span> <span class="identifier">cpp_integer_type</span>    <span class="special">{</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span> <span class="special">};</span>
  37 <span class="keyword">enum</span> <span class="identifier">cpp_int_check_type</span>  <span class="special">{</span> <span class="identifier">checked</span><span class="special">,</span> <span class="identifier">unchecked</span> <span class="special">};</span>
  38
  39 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span>
  40           <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span>
  41           <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span> <span class="special">=</span> <span class="identifier">signed_magnitude</span><span class="special">,</span>
  42           <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span> <span class="special">=</span> <span class="identifier">unchecked</span><span class="special">,</span>
  43           <span class="keyword">class</span> <span class="identifier">Allocator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="identifier">limb_type</span><span class="special">&gt;</span> <span class="special">&gt;</span>
  44 <span class="keyword">class</span> <span class="identifier">cpp_int_backend</span><span class="special">;</span>
  45 <span class="comment">//</span>
  46 <span class="comment">// Expression templates default to et_off if there is no allocator:</span>
  47 <span class="comment">//</span>
  48 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">&gt;</span>
  49 <span class="keyword">struct</span> <span class="identifier">expression_template_default</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>
  50 <span class="special">{</span> <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">expression_template_option</span> <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">et_off</span><span class="special">;</span> <span class="special">};</span>
  51
  52 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>              <span class="identifier">cpp_int</span><span class="special">;</span>    <span class="comment">// arbitrary precision integer</span>
  53 <span class="keyword">typedef</span> <span class="identifier">rational_adaptor</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>    <span class="identifier">cpp_rational_backend</span><span class="special">;</span>
  54 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_rational_backend</span><span class="special">&gt;</span>            <span class="identifier">cpp_rational</span><span class="special">;</span> <span class="comment">// arbitrary precision rational number</span>
  55
  56 <span class="comment">// Fixed precision unsigned types:</span>
  57 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint128_t</span><span class="special">;</span>
  58 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint256_t</span><span class="special">;</span>
  59 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint512_t</span><span class="special">;</span>
  60 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">uint1024_t</span><span class="special">;</span>
  61
  62 <span class="comment">// Fixed precision signed types:</span>
  63 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int128_t</span><span class="special">;</span>
  64 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int256_t</span><span class="special">;</span>
  65 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int512_t</span><span class="special">;</span>
  66 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">int1024_t</span><span class="special">;</span>
  67
  68 <span class="comment">// Over again, but with checking enabled this time:</span>
  69 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">&gt;</span> <span class="special">&gt;</span>                 <span class="identifier">checked_cpp_int</span><span class="special">;</span>
  70 <span class="keyword">typedef</span> <span class="identifier">rational_adaptor</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_cpp_rational_backend</span><span class="special">;</span>
  71 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_rational_backend</span><span class="special">&gt;</span>                                              <span class="identifier">checked_cpp_rational</span><span class="special">;</span>
  72
  73 <span class="comment">// Checked fixed precision unsigned types:</span>
  74 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint128_t</span><span class="special">;</span>
  75 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint256_t</span><span class="special">;</span>
  76 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint512_t</span><span class="special">;</span>
  77 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">checked_uint1024_t</span><span class="special">;</span>
  78
  79 <span class="comment">// Fixed precision signed types:</span>
  80 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int128_t</span><span class="special">;</span>
  81 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int256_t</span><span class="special">;</span>
  82 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int512_t</span><span class="special">;</span>
  83 <span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_int1024_t</span><span class="special">;</span>
  84
  85 <span class="special">}}</span> <span class="comment">// namespaces</span>
  86 </pre>
  87 <p>
  88           The <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code> type
  89           is normally used via one of the convenience typedefs given above.
  90         </p>
  91 <p>
  92           This back-end is the "Swiss Army Knife" of integer types as it
  93           can represent both fixed and <a href="http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic" target="_top">arbitrary
  94           precision</a> integer types, and both signed and unsigned types. There
  95           are five template arguments:
  96         </p>
  97 <div class="variablelist">
  98 <p class="title"><b></b></p>
  99 <dl class="variablelist">
 100 <dt><span class="term">MinBits</span></dt>
 101 <dd><p>
 102                 Determines the number of Bits to store directly within the object
 103                 before resorting to dynamic memory allocation. When zero, this field
 104                 is determined automatically based on how many bits can be stored
 105                 in union with the dynamic storage header: setting a larger value
 106                 may improve performance as larger integer values will be stored internally
 107                 before memory allocation is required.
 108               </p></dd>
 109 <dt><span class="term">MaxBits</span></dt>
 110 <dd><p>
 111                 Determines the maximum number of bits to be stored in the type: resulting
 112                 in a fixed precision type. When this value is the same as MinBits,
 113                 then the Allocator parameter is ignored, as no dynamic memory allocation
 114                 will ever be performed: in this situation the Allocator parameter
 115                 should be set to type <code class="computeroutput"><span class="keyword">void</span></code>.
 116                 Note that this parameter should not be used simply to prevent large
 117                 memory allocations, not only is that role better performed by the
 118                 allocator, but fixed precision integers have a tendency to allocate
 119                 all of MaxBits of storage more often than one would expect.
 120               </p></dd>
 121 <dt><span class="term">SignType</span></dt>
 122 <dd><p>
 123                 Determines whether the resulting type is signed or not. Note that
 124                 for <a href="http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic" target="_top">arbitrary
 125                 precision</a> types this parameter must be <code class="computeroutput"><span class="identifier">signed_magnitude</span></code>.
 126                 For fixed precision types then this type may be either <code class="computeroutput"><span class="identifier">signed_magnitude</span></code> or <code class="computeroutput"><span class="identifier">unsigned_magnitude</span></code>.
 127               </p></dd>
 128 <dt><span class="term">Checked</span></dt>
 129 <dd><p>
 130                 This parameter has two values: <code class="computeroutput"><span class="identifier">checked</span></code>
 131                 or <code class="computeroutput"><span class="identifier">unchecked</span></code>. See
 132                 below.
 133               </p></dd>
 134 <dt><span class="term">Allocator</span></dt>
 135 <dd><p>
 136                 The allocator to use for dynamic memory allocation, or type <code class="computeroutput"><span class="keyword">void</span></code> if MaxBits == MinBits.
 137               </p></dd>
 138 </dl>
 139 </div>
 140 <p>
 141           When the template parameter Checked is set to <code class="computeroutput"><span class="identifier">checked</span></code>
 142           then the result is a <span class="emphasis"><em>checked-integer</em></span>, checked and
 143           unchecked integers have the following properties:
 144         </p>
 145 <div class="informaltable"><table class="table">
 146 <colgroup>
 147 <col>
 148 <col>
 149 <col>
 150 </colgroup>
 151 <thead><tr>
 152 <th>
 153                   <p>
 154                     Condition
 155                   </p>
 156                 </th>
 157 <th>
 158                   <p>
 159                     Checked-Integer
 160                   </p>
 161                 </th>
 162 <th>
 163                   <p>
 164                     Unchecked-Integer
 165                   </p>
 166                 </th>
 167 </tr></thead>
 168 <tbody>
 169 <tr>
 170 <td>
 171                   <p>
 172                     Numeric overflow in fixed precision arithmetic
 173                   </p>
 174                 </td>
 175 <td>
 176                   <p>
 177                     Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>.
 178                   </p>
 179                 </td>
 180 <td>
 181                   <p>
 182                     Performs arithmetic modulo 2<sup>MaxBits</sup>
 183                   </p>
 184                 </td>
 185 </tr>
 186 <tr>
 187 <td>
 188                   <p>
 189                     Constructing an integer from a value that can not be represented
 190                     in the target type
 191                   </p>
 192                 </td>
 193 <td>
 194                   <p>
 195                     Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>.
 196                   </p>
 197                 </td>
 198 <td>
 199                   <p>
 200                     Converts the value modulo 2<sup>MaxBits</sup>, signed to unsigned conversions
 201                     extract the last MaxBits bits of the 2's complement representation
 202                     of the input value.
 203                   </p>
 204                 </td>
 205 </tr>
 206 <tr>
 207 <td>
 208                   <p>
 209                     Unsigned subtraction yielding a negative value.
 210                   </p>
 211                 </td>
 212 <td>
 213                   <p>
 214                     Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>.
 215                   </p>
 216                 </td>
 217 <td>
 218                   <p>
 219                     Yields the value that would result from treating the unsigned
 220                     type as a 2's complement signed type.
 221                   </p>
 222                 </td>
 223 </tr>
 224 <tr>
 225 <td>
 226                   <p>
 227                     Attempting a bitwise operation on a negative value.
 228                   </p>
 229                 </td>
 230 <td>
 231                   <p>
 232                     Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>
 233                   </p>
 234                 </td>
 235 <td>
 236                   <p>
 237                     Yields the value, but not the bit pattern, that would result
 238                     from performing the operation on a 2's complement integer type.
 239                   </p>
 240                 </td>
 241 </tr>
 242 </tbody>
 243 </table></div>
 244 <p>
 245           Things you should know when using this type:
 246         </p>
 247 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 248 <li class="listitem">
 249               Default constructed <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code>s
 250               have the value zero.
 251             </li>
 252 <li class="listitem">
 253               Division by zero results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>
 254               being thrown.
 255             </li>
 256 <li class="listitem">
 257               Construction from a string that contains invalid non-numeric characters
 258               results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code> being thrown.
 259             </li>
 260 <li class="listitem">
 261               Since the precision of <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code>
 262               is necessarily limited when the allocator parameter is void, care should
 263               be taken to avoid numeric overflow when using this type unless you
 264               actually want modulo-arithmetic behavior.
 265             </li>
 266 <li class="listitem">
 267               The type uses a sign-magnitude representation internally, so type
 268               <code class="computeroutput"><span class="identifier">int128_t</span></code> has 128-bits
 269               of precision plus an extra sign bit. In this respect the behaviour
 270               of these types differs from built-in 2's complement types. In might
 271               be tempting to use a 127-bit type instead, and indeed this does work,
 272               but behaviour is still slightly different from a 2's complement built-in
 273               type as the min and max values are identical (apart from the sign),
 274               where as they differ by one for a true 2's complement type. That said
 275               it should be noted that there's no requirement for built-in types to
 276               be 2's complement either - it's simply that this is the most common
 277               format by far.
 278             </li>
 279 <li class="listitem">
 280               Attempting to print negative values as either an Octal or Hexadecimal
 281               string results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
 282               being thrown, this is a direct consequence of the sign-magnitude representation.
 283             </li>
 284 <li class="listitem">
 285               The fixed precision types <code class="computeroutput"><span class="special">[</span><span class="identifier">checked_</span><span class="special">][</span><span class="identifier">u</span><span class="special">]</span><span class="identifier">intXXX_t</span></code> have expression template
 286               support turned off - it seems to make little difference to the performance
 287               of these types either way - so we may as well have the faster compile
 288               times by turning the feature off.
 289             </li>
 290 <li class="listitem">
 291               Unsigned types support subtraction - the result is "as if"
 292               a 2's complement operation had been performed as long as they are not
 293               <span class="emphasis"><em>checked-integers</em></span> (see above). In other words they
 294               behave pretty much as a built in integer type would in this situation.
 295               So for example if we were using <code class="computeroutput"><span class="identifier">uint128_t</span></code>
 296               then <code class="computeroutput"><span class="identifier">uint128_t</span><span class="special">(</span><span class="number">1</span><span class="special">)-</span><span class="number">4</span></code>
 297               would result in the value <code class="computeroutput"><span class="number">0</span><span class="identifier">xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD</span></code>
 298               of type <code class="computeroutput"><span class="identifier">uint128_t</span></code>.
 299               However, had this operation been performed on <code class="computeroutput"><span class="identifier">checked_uint128_t</span></code>
 300               then a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code> would have been thrown.
 301             </li>
 302 <li class="listitem">
 303               Unary negation of unsigned types results in a compiler error (static
 304               assertion).
 305             </li>
 306 <li class="listitem">
 307               This backend supports rvalue-references and is move-aware, making instantiations
 308               of <code class="computeroutput"><span class="identifier">number</span></code> on this backend
 309               move aware.
 310             </li>
 311 <li class="listitem">
 312               When used at fixed precision, the size of this type is always one machine
 313               word larger than you would expect for an N-bit integer: the extra word
 314               stores both the sign, and how many machine words in the integer are
 315               actually in use. The latter is an optimisation for larger fixed precision
 316               integers, so that a 1024-bit integer has almost the same performance
 317               characteristics as a 128-bit integer, rather than being 4 times slower
 318               for addition and 16 times slower for multiplication (assuming the values
 319               involved would always fit in 128 bits). Typically this means you can
 320               use an integer type wide enough for the "worst case scenario"
 321               with only minor performance degradation even if most of the time the
 322               arithmetic could in fact be done with a narrower type.
 323             </li>
 324 <li class="listitem">
 325               When used at fixed precision and MaxBits is smaller than the number
 326               of bits in the largest native integer type, then internally <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code> switches to a "trivial"
 327               implementation where it is just a thin wrapper around a single integer.
 328               Note that it will still be slightly slower than a bare native integer,
 329               as it emulates a signed-magnitude representation rather than simply
 330               using the platforms native sign representation: this ensures there
 331               is no step change in behavior as a cpp_int grows in size.
 332             </li>
 333 <li class="listitem">
 334               Fixed precision <code class="computeroutput"><span class="identifier">cpp_int</span></code>'s
 335               have some support for <code class="computeroutput"><span class="keyword">constexpr</span></code>
 336               values and user-defined literals, see <a class="link" href="../lits.html" title="Literal Types and constexpr Support">here</a>
 337               for the full description. For example <code class="computeroutput"><span class="number">0xfffff</span><span class="identifier">_cppi1024</span></code> specifies a 1024-bit integer
 338               with the value 0xffff. This can be used to generate compile time constants
 339               that are too large to fit into any built in number type.
 340             </li>
 341 <li class="listitem">
 342               You can import/export the raw bits of a <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
 343               to and from external storage via the <code class="computeroutput"><span class="identifier">import_bits</span></code>
 344               and <code class="computeroutput"><span class="identifier">export_bits</span></code> functions.
 345               More information is in the <a class="link" href="../import_export.html" title="Importing and Exporting Data to and from cpp_int and cpp_bin_float">section
 346               on import/export</a>.
 347             </li>
 348 </ul></div>
 349 <h6>
 350 <a name="boost_multiprecision.tut.ints.cpp_int.h0"></a>
 351           <span class="phrase"><a name="boost_multiprecision.tut.ints.cpp_int.example"></a></span><a class="link" href="cpp_int.html#boost_multiprecision.tut.ints.cpp_int.example">Example:</a>
 352         </h6>
 353 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_int</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 354 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 355
 356 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 357 <span class="special">{</span>
 358    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">;</span>
 359
 360    <span class="identifier">int128_t</span> <span class="identifier">v</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
 361
 362    <span class="comment">// Do some fixed precision arithmetic:</span>
 363    <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;=</span> <span class="number">20</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
 364       <span class="identifier">v</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span>
 365
 366    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</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="comment">// prints 20!</span>
 367
 368    <span class="comment">// Repeat at arbitrary precision:</span>
 369    <span class="identifier">cpp_int</span> <span class="identifier">u</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
 370    <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;=</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
 371       <span class="identifier">u</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span>
 372
 373    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">u</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="comment">// prints 100!</span>
 374
 375    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 376 <span class="special">}</span>
 377 </pre>
 378 </div>
 379 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 380 <td align="left"></td>
 381 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2013 John Maddock and Christopher Kormanyos<p>
 382         Distributed under the Boost Software License, Version 1.0. (See accompanying
 383         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 384       </p>
 385 </div></td>
 386 </tr></table>
 387 <hr>
 388 <div class="spirit-nav">
 389 <a accesskey="p" href="../ints.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ints.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gmp_int.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 390 </div>
 391 </body>
 392 </html>