...one of the most highly
regarded and expertly designed C++ library projects in the
world.

— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards

The <boost/integer.hpp> type selection templates allow integer types to be selected based on desired characteristics such as number of bits or maximum value. This facility is particularly useful for solving generic programming problems.

- Contents
- Synopsis
- Easiest-to-Manipulate Types
- Sized Types
- Example
- Demonstration Program
- Rationale
- Alternative
- Credits

namespace boost { // fast integers from least integers template< typename LeastInt > struct int_fast_t { typedefimplementation_suppliedfast; }; // signed template< int Bits > struct int_t { typedefimplementation_suppliedleast; typedef int_fast_t<least>::fast fast; }; // unsigned template< int Bits > struct uint_t { typedefimplementation_suppliedleast; typedef int_fast_t<least>::fast fast; }; // signed template< long MaxValue > struct int_max_value_t { typedefimplementation_suppliedleast; typedef int_fast_t<least>::fast fast; }; template< long MinValue > struct int_min_value_t { typedefimplementation_suppliedleast; typedef int_fast_t<least>::fast fast; }; // unsigned template< unsigned long Value > struct uint_value_t { typedefimplementation_suppliedleast; typedef int_fast_t<least>::fast fast; }; } // namespace boost

The `int_fast_t`

class template maps its input type to the
next-largest type that the processor can manipulate the easiest, or to
itself if the input type is already an easy-to-manipulate type. For
instance, processing a bunch of `char`

objects may go faster
if they were converted to `int`

objects before processing.
The input type, passed as the only template parameter, must be a
built-in integral type, except `bool`

. Unsigned integral
types can be used, as well as signed integral types, despite the name.
The output type is given as the class member `fast`

.

**Implementation Notes**

By default, the output type is identical to the input type. Eventually,
this code's implementation should be conditionalized for each platform
to give accurate mappings between the built-in types and the
easiest-to-manipulate built-in types. Also, there is no guarantee that
the output type actually is easier to manipulate than the input
type.

The `int_t`

, `uint_t`

,
`int_max_value_t`

, `int_min_value_t`

, and
`uint_value_t`

class templates find the most appropiate
built-in integral type for the given template parameter. This type is
given by the class member `least`

. The easiest-to-manipulate
version of that type is given by the class member `fast`

.
The following table describes each template's criteria.

Class Template | Template Parameter Mapping |
---|---|

`boost::int_t` |
The smallest built-in signed integral type with at least the
given number of bits, including the sign bit. The parameter
should be a positive number. A compile-time error results if
the parameter is larger than the number of bits in a
`long` . |

`boost::uint_t` |
The smallest built-in unsigned integral type with at least
the given number of bits. The parameter should be a positive
number. A compile-time error results if the parameter is
larger than the number of bits in an ```
unsigned
long
``` . |

`boost::int_max_value_t` |
The smallest built-in signed integral type that supports the given value as a maximum. The parameter should be a positive number. |

`boost::int_min_value_t` |
The smallest built-in signed integral type that supports the given value as a minimum. The parameter should be a negative number. |

`boost::uint_value_t` |
The smallest built-in unsigned integral type that supports the given value as a maximum. The parameter should be a positive number. |

#include <boost/integer.hpp> //... int main() { boost::int_t<24>::least my_var; //... }

The program integer_test.cpp is a simplistic demonstration of the results from instantiating various examples of the sized type class templates.

The rationale for the design of the templates in this header includes:

- Avoid recursion because of concern about C++'s limited guaranteed recursion depth (17).
- Avoid macros on general principles.
- Try to keep the design as simple as possible.

If the number of bits required is known beforehand, it may be more appropriate to use the types supplied in <boost/cstdint.hpp>.

The author of most of the Boost integer type choosing templates is Beman Dawes. He gives thanks to Valentin Bonnard and Kevlin Henney for sharing their designs for similar templates. Daryle Walker designed the value-based sized templates.

Revised May 20, 2001

© Copyright Beman Dawes 1999. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.