Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Standard Integer Types

Overview
Rationale
Caveat emptor
Exact-width integer types
Minimum-width integer types
Fastest minimum-width integer types
Greatest-width integer types
Integer Constant Macros
Integers for Storing Pointers

The header <boost/cstdint.hpp> provides the typedef's useful for writing portable code that requires certain integer widths. All typedef's are in namespace boost.

The specifications for these types are based on the ISO/IEC 9899:1999 C Language standard header <stdint.h>. The 64-bit types required by the C standard are not required in the boost header, and may not be supplied for all platforms/compilers, because long long is not [yet] included in the C++ standard.

See cstdint_test.cpp for a test program.

The organization of the Boost.Integer headers and classes is designed to take advantage of <stdint.h> types from the 1999 C standard without causing undefined behavior in terms of the 1998 C++ standard. The header <boost/cstdint.hpp> makes the standard integer types safely available in namespace boost without placing any names in namespace std. The intension is to complement rather than compete with the C++ Standard Library. Should some future C++ standard include <stdint.h> and <cstdint>, then <boost/cstdint.hpp> will continue to function, but will become redundant and may be safely deprecated.

Because these are boost headers, their names conform to boost header naming conventions rather than C++ Standard Library header naming conventions.

As an implementation artifact, certain C <limits.h> macro names may possibly be visible to users of <boost/cstdint.hpp>. Don't use these macros; they are not part of any Boost-specified interface. Use boost::integer_traits<> or std::numeric_limits<> instead.

As another implementation artifact, certain C <stdint.h> typedef names may possibly be visible in the global namespace to users of <boost/cstdint.hpp>. Don't use these names, they are not part of any Boost-specified interface. Use the respective names in namespace boost instead.

The typedef int#_t, with # replaced by the width, designates a signed integer type of exactly # bits; for example int8_t denotes an 8-bit signed integer type. Similarly, the typedef uint#_t designates an unsigned integer type of exactly # bits.

These types are optional. However, if a platform supports integer types with widths of 8, 16, 32, 64, or any combination thereof, then <boost/cstdint.hpp> does provide the corresponding typedefs.

The absence of int64_t and uint64_t is indicated by the macro BOOST_NO_INT64_T.

The typedef int_least#_t, with # replaced by the width, designates a signed integer type with a width of at least # bits, such that no signed integer type with lesser size has at least the specified width. Thus, int_least32_t denotes the smallest signed integer type with a width of at least 32 bits. Similarly, the typedef name uint_least#_t designates an unsigned integer type with a width of at least # bits, such that no unsigned integer type with lesser size has at least the specified width.

The following minimum-width integer types are provided for all platforms:

  • int_least8_t
  • int_least16_t
  • int_least32_t
  • uint_least8_t
  • uint_least16_t
  • uint_least32_t

The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:

  • int_least64_t
  • uint_least64_t

All other minimum-width integer types are optional.

The typedef int_fast#_t, with # replaced by the width, designates the fastest signed integer type with a width of at least # bits. Similarly, the typedef name uint_fast#_t designates the fastest unsigned integer type with a width of at least # bits.

There is no guarantee that these types are fastest for all purposes. In any case, however, they satisfy the signedness and width requirements.

The following fastest minimum-width integer types are provided for all platforms:

  • int_fast8_t
  • int_fast16_t
  • int_fast32_t
  • uint_fast8_t
  • uint_fast16_t
  • uint_fast32_t

The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:

  • int_fast64_t
  • uint_fast64_t

All other fastest minimum-width integer types are optional.

The typedef intmax_t designates a signed integer type capable of representing any value of any signed integer type.

The typedef uintmax_t designates an unsigned integer type capable of representing any value of any unsigned integer type.

These types are provided for all platforms.

The following macros are always defined after inclusion of this header, these allow integer constants of at least the specified width to be declared: INT8_C, UINT8_C, INT16_C, UINT16_C, INT32_C, UINT32_C, INTMAX_C, UINTMAX_C.

The macros INT64_C and UINT64_C are also defined if the the macro BOOST_NO_INT64_T is not defined.

The C99 macro __STDC_CONSTANT_MACROS is also defined as an artifact of the implementation.

For example:

#include <boost/cstdint.hpp>

// Here the constant 0x1FFFFFFFF has the correct suffix applied:
static const boost::uint64_t c = INT64_C(0x1FFFFFFFF);

The typedefs intptr_t and uintptr_t defined signed and unsigned integers respectively each capable of storing a pointer. The macro BOOST_HAS_INTPTR_T is set when these types are available.


PrevUpHomeNext