1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Integer Type Selection</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Integer"> 8<link rel="up" href="../index.html" title="Boost.Integer"> 9<link rel="prev" href="traits.html" title="Integer Traits"> 10<link rel="next" href="gcd_lcm.html" title="Greatest Common Divisor and Least Common Multiple"> 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="traits.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="gcd_lcm.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_integer.integer"></a><a class="link" href="integer.html" title="Integer Type Selection">Integer Type Selection</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="integer.html#boost_integer.integer.synopsis">Synopsis</a></span></dt> 31<dt><span class="section"><a href="integer.html#boost_integer.integer.easiest">Easiest-to-Manipulate 32 Types</a></span></dt> 33<dt><span class="section"><a href="integer.html#boost_integer.integer.sized">Sized Types</a></span></dt> 34<dt><span class="section"><a href="integer.html#boost_integer.integer.example">Example</a></span></dt> 35<dt><span class="section"><a href="integer.html#boost_integer.integer.demonstration_program">Demonstration 36 Program</a></span></dt> 37<dt><span class="section"><a href="integer.html#boost_integer.integer.rationale">Rationale</a></span></dt> 38<dt><span class="section"><a href="integer.html#boost_integer.integer.alternative">Alternative</a></span></dt> 39<dt><span class="section"><a href="integer.html#boost_integer.integer.credits">Credits</a></span></dt> 40</dl></div> 41<p> 42 The <a href="../../../../../boost/integer.hpp" target="_top"><boost/integer.hpp></a> 43 type selection templates allow integer types to be selected based on desired 44 characteristics such as number of bits or maximum value. This facility is particularly 45 useful for solving generic programming problems. 46 </p> 47<div class="section"> 48<div class="titlepage"><div><div><h3 class="title"> 49<a name="boost_integer.integer.synopsis"></a><a class="link" href="integer.html#boost_integer.integer.synopsis" title="Synopsis">Synopsis</a> 50</h3></div></div></div> 51<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> 52<span class="special">{</span> 53 <span class="comment">// fast integers from least integers</span> 54 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">LeastInt</span><span class="special">></span> 55 <span class="keyword">struct</span> <span class="identifier">int_fast_t</span> 56 <span class="special">{</span> 57 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">type</span><span class="special">;</span> 58 <span class="special">};</span> 59 60 <span class="comment">// signed</span> 61 <span class="keyword">template</span><span class="special"><</span><span class="keyword">int</span> <span class="identifier">Bits</span><span class="special">></span> 62 <span class="keyword">struct</span> <span class="identifier">int_t</span> 63 <span class="special">{</span> 64 <span class="comment">/* Member exact may or may not be defined depending upon Bits */</span> 65 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">exact</span><span class="special">;</span> 66 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">least</span><span class="special">;</span> 67 <span class="keyword">typedef</span> <span class="identifier">int_fast_t</span><span class="special"><</span><span class="identifier">least</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">fast</span><span class="special">;</span> 68 <span class="special">};</span> 69 70 <span class="comment">// unsigned</span> 71 <span class="keyword">template</span><span class="special"><</span><span class="keyword">int</span> <span class="identifier">Bits</span><span class="special">></span> 72 <span class="keyword">struct</span> <span class="identifier">uint_t</span> 73 <span class="special">{</span> 74 <span class="comment">/* Member exact may or may not be defined depending upon Bits */</span> 75 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">exact</span><span class="special">;</span> 76 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">least</span><span class="special">;</span> 77 <span class="keyword">typedef</span> <span class="identifier">int_fast_t</span><span class="special"><</span><span class="identifier">least</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">fast</span><span class="special">;</span> 78 <span class="special">};</span> 79 80 <span class="comment">// signed</span> 81 <span class="keyword">template</span><span class="special"><</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">MaxValue</span><span class="special">></span> 82 <span class="keyword">struct</span> <span class="identifier">int_max_value_t</span> 83 <span class="special">{</span> 84 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">least</span><span class="special">;</span> 85 <span class="keyword">typedef</span> <span class="identifier">int_fast_t</span><span class="special"><</span><span class="identifier">least</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">fast</span><span class="special">;</span> 86 <span class="special">};</span> 87 88 <span class="keyword">template</span><span class="special"><</span><span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">MinValue</span><span class="special">></span> 89 <span class="keyword">struct</span> <span class="identifier">int_min_value_t</span> 90 <span class="special">{</span> 91 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">least</span><span class="special">;</span> 92 <span class="keyword">typedef</span> <span class="identifier">int_fast_t</span><span class="special"><</span><span class="identifier">least</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">fast</span><span class="special">;</span> 93 <span class="special">};</span> 94 95 <span class="comment">// unsigned</span> 96 <span class="keyword">template</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">Value</span><span class="special">></span> 97 <span class="keyword">struct</span> <span class="identifier">uint_value_t</span> 98 <span class="special">{</span> 99 <span class="keyword">typedef</span> <span class="emphasis"><em>implementation-defined-type</em></span> <span class="identifier">least</span><span class="special">;</span> 100 <span class="keyword">typedef</span> <span class="identifier">int_fast_t</span><span class="special"><</span><span class="identifier">least</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">fast</span><span class="special">;</span> 101 <span class="special">};</span> 102<span class="special">}</span> <span class="comment">// namespace boost</span> 103</pre> 104</div> 105<div class="section"> 106<div class="titlepage"><div><div><h3 class="title"> 107<a name="boost_integer.integer.easiest"></a><a class="link" href="integer.html#boost_integer.integer.easiest" title="Easiest-to-Manipulate Types">Easiest-to-Manipulate 108 Types</a> 109</h3></div></div></div> 110<p> 111 The <code class="literal">int_fast_t</code> class template maps its input type to the 112 next-largest type that the processor can manipulate the easiest, or to itself 113 if the input type is already an easy-to-manipulate type. For instance, processing 114 a bunch of <code class="literal">char</code> objects may go faster if they were converted 115 to <code class="literal">int</code> objects before processing. The input type, passed 116 as the only template parameter, must be a built-in integral type, except 117 <code class="literal">bool</code>. Unsigned integral types can be used, as well as 118 signed integral types. The output type is given as the nested type <code class="literal">fast</code>. 119 </p> 120<p> 121 <span class="bold"><strong>Implementation Notes:</strong></span> By default, the output 122 type is identical to the input type. Eventually, this code's implementation 123 should be customized for each platform to give accurate mappings between 124 the built-in types and the easiest-to-manipulate built-in types. Also, there 125 is no guarantee that the output type actually is easier to manipulate than 126 the input type. 127 </p> 128</div> 129<div class="section"> 130<div class="titlepage"><div><div><h3 class="title"> 131<a name="boost_integer.integer.sized"></a><a class="link" href="integer.html#boost_integer.integer.sized" title="Sized Types">Sized Types</a> 132</h3></div></div></div> 133<p> 134 The <code class="literal">int_t</code>, <code class="literal">uint_t</code>, <code class="literal">int_max_value_t</code>, 135 <code class="literal">int_min_value_t</code>, and <code class="literal">uint_value_t</code> class 136 templates find the most appropiate built-in integral type for the given template 137 parameter. This type is given by the nested type <code class="literal">least</code>. 138 The easiest-to-manipulate version of that type is given by the nested type 139 <code class="literal">fast</code>. The following table describes each template's criteria. 140 </p> 141<div class="table"> 142<a name="boost_integer.integer.sized.criteria_for_the_sized_type_class_templates"></a><p class="title"><b>Table 1. Criteria for the Sized Type Class Templates</b></p> 143<div class="table-contents"><table class="table" summary="Criteria for the Sized Type Class Templates"> 144<colgroup> 145<col> 146<col> 147</colgroup> 148<thead><tr> 149<th> 150 <p> 151 Class Template 152 </p> 153 </th> 154<th> 155 <p> 156 Template Parameter Mapping 157 </p> 158 </th> 159</tr></thead> 160<tbody> 161<tr> 162<td> 163 <p> 164 <code class="literal">boost::int_t<N>::least</code> 165 </p> 166 </td> 167<td> 168 <p> 169 The smallest, built-in, signed integral type with at least <span class="emphasis"><em>N</em></span> 170 bits, including the sign bit. The parameter should be a positive 171 number. A compile-time error results if the parameter is larger 172 than the number of bits in the largest integer type. 173 </p> 174 </td> 175</tr> 176<tr> 177<td> 178 <p> 179 <code class="literal">boost::int_t<N>::fast</code> 180 </p> 181 </td> 182<td> 183 <p> 184 The easiest-to-manipulate, built-in, signed integral type with 185 at least <span class="emphasis"><em>N</em></span> bits, including the sign bit. The 186 parameter should be a positive number. A compile-time error results 187 if the parameter is larger than the number of bits in the largest 188 integer type. 189 </p> 190 </td> 191</tr> 192<tr> 193<td> 194 <p> 195 <code class="literal">boost::int_t<N>::exact</code> 196 </p> 197 </td> 198<td> 199 <p> 200 A built-in, signed integral type with exactly <span class="emphasis"><em>N</em></span> 201 bits, including the sign bit. The parameter should be a positive 202 number. Note that the member <span class="emphasis"><em>exact</em></span> is defined 203 <span class="bold"><strong>only</strong></span> if there exists a type with 204 exactly <span class="emphasis"><em>N</em></span> bits. 205 </p> 206 </td> 207</tr> 208<tr> 209<td> 210 <p> 211 <code class="literal">boost::uint_t<N>::least</code> 212 </p> 213 </td> 214<td> 215 <p> 216 The smallest, built-in, unsigned integral type with at least <span class="emphasis"><em>N</em></span> 217 bits. The parameter should be a positive number. A compile-time 218 error results if the parameter is larger than the number of bits 219 in the largest integer type. 220 </p> 221 </td> 222</tr> 223<tr> 224<td> 225 <p> 226 <code class="literal">boost::uint_t<N>::fast</code> 227 </p> 228 </td> 229<td> 230 <p> 231 The easiest-to-manipulate, built-in, unsigned integral type with 232 at least <span class="emphasis"><em>N</em></span> bits. The parameter should be a 233 positive number. A compile-time error results if the parameter 234 is larger than the number of bits in the largest integer type. 235 </p> 236 </td> 237</tr> 238<tr> 239<td> 240 <p> 241 <code class="literal">boost::uint_t<N>::exact</code> 242 </p> 243 </td> 244<td> 245 <p> 246 A built-in, unsigned integral type with exactly <span class="emphasis"><em>N</em></span> 247 bits. The parameter should be a positive number. A compile-time 248 error results if the parameter is larger than the number of bits 249 in the largest integer type. Note that the member <span class="emphasis"><em>exact</em></span> 250 is defined <span class="bold"><strong>only</strong></span> if there exists 251 a type with exactly N bits. 252 </p> 253 </td> 254</tr> 255<tr> 256<td> 257 <p> 258 <code class="literal">boost::int_max_value_t<V>::last</code> 259 </p> 260 </td> 261<td> 262 <p> 263 The smallest, built-in, signed integral type that can hold all 264 the values in the inclusive range <span class="emphasis"><em>0 - V</em></span>. The 265 parameter should be a positive number. 266 </p> 267 </td> 268</tr> 269<tr> 270<td> 271 <p> 272 <code class="literal">boost::int_max_value_t<V>::fast</code> 273 </p> 274 </td> 275<td> 276 <p> 277 The easiest-to-manipulate, built-in, signed integral type that 278 can hold all the values in the inclusive range <span class="emphasis"><em>0 - V</em></span>. 279 The parameter should be a positive number. 280 </p> 281 </td> 282</tr> 283<tr> 284<td> 285 <p> 286 <code class="literal">boost::int_min_value_t<V>::least</code> 287 </p> 288 </td> 289<td> 290 <p> 291 The smallest, built-in, signed integral type that can hold all 292 the values in the inclusive range <span class="emphasis"><em>V - 0</em></span>. The 293 parameter should be a negative number. 294 </p> 295 </td> 296</tr> 297<tr> 298<td> 299 <p> 300 <code class="literal">boost::int_min_value_t<V>::fast</code> 301 </p> 302 </td> 303<td> 304 <p> 305 The easiest-to-manipulate, built-in, signed integral type that 306 can hold all the values in the inclusive range <span class="emphasis"><em>V - 0</em></span>. 307 The parameter should be a negative number. 308 </p> 309 </td> 310</tr> 311<tr> 312<td> 313 <p> 314 <code class="literal">boost::uint_value_t<V>::least</code> 315 </p> 316 </td> 317<td> 318 <p> 319 The smallest, built-in, unsigned integral type that can hold all 320 positive values up to and including <span class="emphasis"><em>V</em></span>. The 321 parameter should be a positive number. 322 </p> 323 </td> 324</tr> 325<tr> 326<td> 327 <p> 328 <code class="literal">boost::uint_value_t<V>::fast</code> 329 </p> 330 </td> 331<td> 332 <p> 333 The easiest-to-manipulate, built-in, unsigned integral type that 334 can hold all positive values up to and including <span class="emphasis"><em>V</em></span>. 335 The parameter should be a positive number. 336 </p> 337 </td> 338</tr> 339</tbody> 340</table></div> 341</div> 342<br class="table-break"> 343</div> 344<div class="section"> 345<div class="titlepage"><div><div><h3 class="title"> 346<a name="boost_integer.integer.example"></a><a class="link" href="integer.html#boost_integer.integer.example" title="Example">Example</a> 347</h3></div></div></div> 348<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">integer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 349 350<span class="comment">//...</span> 351 352<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 353<span class="special">{</span> 354 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int_t</span><span class="special"><</span><span class="number">24</span><span class="special">>::</span><span class="identifier">least</span> <span class="identifier">my_var</span><span class="special">;</span> <span class="comment">// my_var has at least 24-bits</span> 355 <span class="comment">//...</span> 356 <span class="comment">// This one is guaranteed not to be truncated:</span> 357 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int_max_value_t</span><span class="special"><</span><span class="number">1000</span><span class="special">>::</span><span class="identifier">least</span> <span class="identifier">my1000</span> <span class="special">=</span> <span class="number">1000</span><span class="special">;</span> 358 <span class="comment">//...</span> 359 <span class="comment">// This one is guaranteed not to be truncated, and as fast</span> 360 <span class="comment">// to manipulate as possible, its size may be greater than</span> 361 <span class="comment">// that of my1000:</span> 362 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">int_max_value_t</span><span class="special"><</span><span class="number">1000</span><span class="special">>::</span><span class="identifier">fast</span> <span class="identifier">my_fast1000</span> <span class="special">=</span> <span class="number">1000</span><span class="special">;</span> 363<span class="special">}</span> 364</pre> 365</div> 366<div class="section"> 367<div class="titlepage"><div><div><h3 class="title"> 368<a name="boost_integer.integer.demonstration_program"></a><a class="link" href="integer.html#boost_integer.integer.demonstration_program" title="Demonstration Program">Demonstration 369 Program</a> 370</h3></div></div></div> 371<p> 372 The program <a href="../../../test/integer_test.cpp" target="_top">integer_test.cpp</a> 373 is a simplistic demonstration of the results from instantiating various examples 374 of the sized type class templates. 375 </p> 376</div> 377<div class="section"> 378<div class="titlepage"><div><div><h3 class="title"> 379<a name="boost_integer.integer.rationale"></a><a class="link" href="integer.html#boost_integer.integer.rationale" title="Rationale">Rationale</a> 380</h3></div></div></div> 381<p> 382 The rationale for the design of the templates in this header includes: 383 </p> 384<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 385<li class="listitem"> 386 Avoid recursion because of concern about C++'s limited guaranteed recursion 387 depth (17). 388 </li> 389<li class="listitem"> 390 Avoid macros on general principles. 391 </li> 392<li class="listitem"> 393 Try to keep the design as simple as possible. 394 </li> 395</ul></div> 396</div> 397<div class="section"> 398<div class="titlepage"><div><div><h3 class="title"> 399<a name="boost_integer.integer.alternative"></a><a class="link" href="integer.html#boost_integer.integer.alternative" title="Alternative">Alternative</a> 400</h3></div></div></div> 401<p> 402 If the number of bits required is known beforehand, it may be more appropriate 403 to use the types supplied in <a href="../../../../../boost/cstdint.hpp" target="_top"><boost/cstdint.hpp></a>. 404 </p> 405</div> 406<div class="section"> 407<div class="titlepage"><div><div><h3 class="title"> 408<a name="boost_integer.integer.credits"></a><a class="link" href="integer.html#boost_integer.integer.credits" title="Credits">Credits</a> 409</h3></div></div></div> 410<p> 411 The author of most of the Boost integer type choosing templates is <a href="http://www.boost.org/people/beman_dawes.html" target="_top">Beman Dawes</a>. He 412 gives thanks to Valentin Bonnard and <a href="http://www.boost.org/people/kevlin_henney.htm" target="_top">Kevlin 413 Henney</a> for sharing their designs for similar templates. <a href="http://www.boost.org/people/daryle_walker.html" target="_top">Daryle 414 Walker</a> designed the value-based sized templates. 415 </p> 416</div> 417</div> 418<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 419<td align="left"></td> 420<td align="right"><div class="copyright-footer">Copyright © 2001-2009 Beman 421 Dawes, Daryle Walker, Gennaro Prota, John Maddock<p> 422 Distributed under the Boost Software License, Version 1.0. (See accompanying 423 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>) 424 </p> 425</div></td> 426</tr></table> 427<hr> 428<div class="spirit-nav"> 429<a accesskey="p" href="traits.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="gcd_lcm.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 430</div> 431</body> 432</html> 433
