1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>cpp_int</title> 5<link rel="stylesheet" href="../../../multiprecision.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../../index.html" title="Chapter 1. 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"><</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">></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"><</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"><</span><span class="identifier">limb_type</span><span class="special">></span> <span class="special">></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"><</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">></span> 49<span class="keyword">struct</span> <span class="identifier">expression_template_default</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><></span> <span class="special">></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"><</span><span class="identifier">cpp_rational_backend</span><span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_rational_backend</span><span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</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">></span> <span class="special">></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 <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental 271 (built-in)</a> 2's complement types. In might be tempting to use 272 a 127-bit type instead, and indeed this does work, but behaviour is 273 still slightly different from a 2's complement <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental 274 (built-in)</a> type as the minimum and maximum values are identical 275 (apart from the sign), where as they differ by one for a true 2's complement 276 type. That said it should be noted that there's no requirement for 277 fundamental_types to be 2's complement either - it's simply that this 278 is the most common format by far. 279 </li> 280<li class="listitem"> 281 Attempting to print negative values as either an Octal or Hexadecimal 282 string results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code> 283 being thrown, this is a direct consequence of the sign-magnitude representation. 284 </li> 285<li class="listitem"> 286 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 287 support turned off - it seems to make little difference to the performance 288 of these types either way - so we may as well have the faster compile 289 times by turning the feature off. 290 </li> 291<li class="listitem"> 292 Unsigned types support subtraction - the result is "as if" 293 a 2's complement operation had been performed as long as they are not 294 <span class="emphasis"><em>checked-integers</em></span> (see above). In other words they 295 behave pretty much as a <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental 296 (built-in)</a> integer type would in this situation. So for example 297 if we were using <code class="computeroutput"><span class="identifier">uint128_t</span></code> 298 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> 299 would result in the value <code class="computeroutput"><span class="number">0</span><span class="identifier">xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD</span></code> 300 of type <code class="computeroutput"><span class="identifier">uint128_t</span></code>. 301 However, had this operation been performed on <code class="computeroutput"><span class="identifier">checked_uint128_t</span></code> 302 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. 303 </li> 304<li class="listitem"> 305 Unary negation of unsigned types results in a compiler error (static 306 assertion). 307 </li> 308<li class="listitem"> 309 This backend supports rvalue-references and is move-aware, making instantiations 310 of <code class="computeroutput"><span class="identifier">number</span></code> on this backend 311 move aware. 312 </li> 313<li class="listitem"> 314 When used at fixed precision, the size of this type is always one machine 315 word (plus any compiler-applied alignment padding) larger than you 316 would expect for an N-bit integer: the extra word stores both the sign, 317 and how many machine words in the integer are actually in use. The 318 latter is an optimisation for larger fixed precision integers, so that 319 a 1024-bit integer has almost the same performance characteristics 320 as a 128-bit integer, rather than being 4 times slower for addition 321 and 16 times slower for multiplication (assuming the values involved 322 would always fit in 128 bits). Typically this means you can use an 323 integer type wide enough for the "worst case scenario" with 324 only minor performance degradation even if most of the time the arithmetic 325 could in fact be done with a narrower type. Also note that unsigned 326 fixed precision types small enough to fit inside the largest native 327 integer become a simple wrapper around that type, this includes the 328 "checked" variants. Small signed types will always have an 329 extra sign word and so be larger than their native equivalent. 330 </li> 331<li class="listitem"> 332 When used at fixed precision and MaxBits is smaller than the number 333 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" 334 implementation where it is just a thin wrapper around a single integer. 335 Note that it will still be slightly slower than a bare native integer, 336 as it emulates a signed-magnitude representation rather than simply 337 using the platforms native sign representation: this ensures there 338 is no step change in behavior as a cpp_int grows in size. 339 </li> 340<li class="listitem"> 341 Fixed precision <code class="computeroutput"><span class="identifier">cpp_int</span></code>'s 342 have some support for <code class="computeroutput"><span class="keyword">constexpr</span></code> 343 values and user-defined literals, see <a class="link" href="../lits.html" title="Literal Types and constexpr Support">here</a> 344 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 345 with the value 0xffff. This can be used to generate compile-time constants 346 that are too large to fit into any <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental 347 (built-in)</a> number type. 348 </li> 349<li class="listitem"> 350 The <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a> 351 types support constexpr arithmetic, provided it is a fixed-precision 352 type with no allocator. It may also be a checked integer: in which 353 case a compiler error will be generated on overflow or undefined behaviour. 354 In addition the free functions <code class="computeroutput"><span class="identifier">abs</span></code>, 355 <code class="computeroutput"><span class="identifier">swap</span></code>, <code class="computeroutput"><span class="identifier">multiply</span></code>, <code class="computeroutput"><span class="identifier">add</span></code>, 356 <code class="computeroutput"><span class="identifier">subtract</span></code>, <code class="computeroutput"><span class="identifier">divide_qr</span></code>, <code class="computeroutput"><span class="identifier">integer_modulus</span></code>, 357 <code class="computeroutput"><span class="identifier">powm</span></code>, <code class="computeroutput"><span class="identifier">lsb</span></code>, <code class="computeroutput"><span class="identifier">msb</span></code>, 358 <code class="computeroutput"><span class="identifier">bit_test</span></code>, <code class="computeroutput"><span class="identifier">bit_set</span></code>, <code class="computeroutput"><span class="identifier">bit_unset</span></code>, 359 <code class="computeroutput"><span class="identifier">bit_flip</span></code>, <code class="computeroutput"><span class="identifier">sqrt</span></code>, <code class="computeroutput"><span class="identifier">gcd</span></code>, 360 <code class="computeroutput"><span class="identifier">lcm</span></code> are all supported. 361 Use of <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a> 362 in this way requires either a C++2a compiler (one which supports <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">is_constant_evaluated</span><span class="special">()</span></code>), 363 or GCC-6 or later in C++14 mode. Compilers other than GCC and without 364 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">is_constant_evaluated</span><span class="special">()</span></code> 365 will support a very limited set of operations: expect to hit roadblocks 366 rather easily. 367 </li> 368<li class="listitem"> 369 You can import/export the raw bits of a <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a> 370 to and from external storage via the <code class="computeroutput"><span class="identifier">import_bits</span></code> 371 and <code class="computeroutput"><span class="identifier">export_bits</span></code> functions. 372 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 373 on import/export</a>. 374 </li> 375</ul></div> 376<h6> 377<a name="boost_multiprecision.tut.ints.cpp_int.h0"></a> 378 <span class="phrase"><a name="boost_multiprecision.tut.ints.cpp_int.cpp_int_eg"></a></span><a class="link" href="cpp_int.html#boost_multiprecision.tut.ints.cpp_int.cpp_int_eg">Example:</a> 379 </h6> 380<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</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">></span> 381<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 382 383<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 384<span class="special">{</span> 385 <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> 386 387 <span class="identifier">int128_t</span> <span class="identifier">v</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> 388 389 <span class="comment">// Do some fixed precision arithmetic:</span> 390 <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"><=</span> <span class="number">20</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> 391 <span class="identifier">v</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span> 392 393 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">v</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// prints 2432902008176640000 (i.e. 20!)</span> 394 395 <span class="comment">// Repeat at arbitrary precision:</span> 396 <span class="identifier">cpp_int</span> <span class="identifier">u</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> 397 <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"><=</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> 398 <span class="identifier">u</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span> 399 400 <span class="comment">// prints 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000 (i.e. 100!)</span> 401 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">u</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 402 403 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 404<span class="special">}</span> 405</pre> 406</div> 407<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 408<td align="left"></td> 409<td align="right"><div class="copyright-footer">Copyright © 2002-2020 John 410 Maddock and Christopher Kormanyos<p> 411 Distributed under the Boost Software License, Version 1.0. (See accompanying 412 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>) 413 </p> 414</div></td> 415</tr></table> 416<hr> 417<div class="spirit-nav"> 418<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> 419</div> 420</body> 421</html> 422
