...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.
namespace boost { // fast integers from least integers template<typename LeastInt> struct int_fast_t { typedef implementation-defined-type type; }; // signed template<int Bits> struct int_t { /* Member exact may or may not be defined depending upon Bits */ typedef implementation-defined-type exact; typedef implementation-defined-type least; typedef int_fast_t<least>::fast fast; }; // unsigned template<int Bits> struct uint_t { /* Member exact may or may not be defined depending upon Bits */ typedef implementation-defined-type exact; typedef implementation-defined-type least; typedef int_fast_t<least>::fast fast; }; // signed template<long long MaxValue> struct int_max_value_t { typedef implementation-defined-type least; typedef int_fast_t<least>::fast fast; }; template<long long MinValue> struct int_min_value_t { typedef implementation-defined-type least; typedef int_fast_t<least>::fast fast; }; // unsigned template<unsigned long long Value> struct uint_value_t { typedef implementation-defined-type least; 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. The output type is given as the nested type fast
.
Implementation Notes: By default, the output type is identical to the input type. Eventually, this code's implementation should be customized 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 nested type least
.
The easiest-to-manipulate version of that type is given by the nested type
fast
. The following table describes each template's criteria.
Table 1. Criteria for the Sized Type Class Templates
Class Template |
Template Parameter Mapping |
---|---|
|
The smallest, built-in, signed integral type with at least N 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 the largest integer type. |
|
The easiest-to-manipulate, built-in, signed integral type with at least N 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 the largest integer type. |
|
A built-in, signed integral type with exactly N bits, including the sign bit. The parameter should be a positive number. Note that the member exact is defined only if there exists a type with exactly N bits. |
|
The smallest, built-in, unsigned integral type with at least N bits. The parameter should be a positive number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type. |
|
The easiest-to-manipulate, built-in, unsigned integral type with at least N bits. The parameter should be a positive number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type. |
|
A built-in, unsigned integral type with exactly N bits. The parameter should be a positive number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type. Note that the member exact is defined only if there exists a type with exactly N bits. |
|
The smallest, built-in, signed integral type that can hold all the values in the inclusive range 0 - V. The parameter should be a positive number. |
|
The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range 0 - V. The parameter should be a positive number. |
|
The smallest, built-in, signed integral type that can hold all the values in the inclusive range V - 0. The parameter should be a negative number. |
|
The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range V - 0. The parameter should be a negative number. |
|
The smallest, built-in, unsigned integral type that can hold all positive values up to and including V. The parameter should be a positive number. |
|
The easiest-to-manipulate, built-in, unsigned integral type that can hold all positive values up to and including V. The parameter should be a positive number. |
#include <boost/integer.hpp> //... int main() { boost::int_t<24>::least my_var; // my_var has at least 24-bits //... // This one is guarenteed not to be truncated: boost::int_max_value_t<1000>::least my1000 = 1000; //... // This one is guarenteed not to be truncated, and as fast // to manipulate as possible, its size may be greater than // that of my1000: boost::int_max_value_t<1000>::fast my_fast1000 = 1000; }
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:
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.