libs/config/doc/cstdint.qbk

   1 [section:cstdint Standard Integer Types]
   2
   3 [section Overview]
   4
   5 The header [^[@../../../../boost/cstdint.hpp <boost/cstdint.hpp>]] provides the typedef's useful
   6 for writing portable code that requires certain integer widths. All typedef's are in namespace boost.
   7
   8 The specifications for these types are based on the ISO/IEC 9899:1999 C Language standard header <stdint.h>.
   9 The 64-bit types required by the C standard are ['not required] in the boost header,
  10 and may not be supplied for all platforms/compilers, because [^long long] is not [yet] included in the C++ standard.
  11
  12 See [@../../test/cstdint_test.cpp cstdint_test.cpp] for a test program.
  13
  14 [endsect]
  15
  16 [section:rationale Rationale]
  17
  18 The organization of the Boost.Integer headers and classes is designed to take advantage of <stdint.h> types from the
  19 1999 C standard without causing undefined behavior in terms of the 1998 C++ standard.
  20 The header <boost/cstdint.hpp> makes the standard integer types safely available in namespace [^boost]
  21 without placing any names in namespace [^std]. The intension is to complement rather than compete
  22 with the C++ Standard Library. Should some future C++ standard include <stdint.h> and <cstdint>,
  23 then <boost/cstdint.hpp> will continue to function, but will become redundant and may be safely deprecated.
  24
  25 Because these are boost headers, their names conform to boost header naming conventions rather than
  26 C++ Standard Library header naming conventions.
  27
  28 [endsect]
  29
  30 [section:ce ['Caveat emptor]]
  31
  32 As an implementation artifact, certain C <limits.h> macro names may possibly be
  33 visible to users of <boost/cstdint.hpp>. Don't use these macros; they are not part of
  34 any Boost-specified interface. Use [^boost::integer_traits<>] or [^std::numeric_limits<>] instead.
  35
  36 As another implementation artifact, certain C <stdint.h> typedef names may possibly be visible
  37 in the global namespace to users of <boost/cstdint.hpp>. Don't use these names, they are not part of
  38 any Boost-specified interface. Use the respective names in namespace [^boost] instead.
  39
  40 [endsect]
  41
  42 [section Exact-width integer types]
  43
  44 The typedef [^int#_t], with # replaced by the width, designates a signed integer type of exactly # bits;
  45 for example [^int8_t] denotes an 8-bit signed integer type. Similarly, the typedef [^uint#_t] designates an unsigned
  46 integer type of exactly # bits.
  47
  48 These types are optional. However, if a platform supports integer types with widths of
  49 8, 16, 32, 64, or any combination thereof, then <boost/cstdint.hpp> does provide the
  50 corresponding typedefs.
  51
  52 The absence of int64_t and uint64_t is indicated by the macro `BOOST_NO_INT64_T`.
  53
  54 [endsect]
  55
  56 [section Minimum-width integer types]
  57
  58 The typedef [^int_least#_t], with # replaced by the width, designates a signed integer type with a width
  59 of at least # bits, such that no signed integer type with lesser size has at least the specified width.
  60 Thus, [^int_least32_t] denotes the smallest signed integer type with a width of at least 32 bits.
  61 Similarly, the typedef name [^uint_least#_t] designates an unsigned integer type with a width of at least # bits,
  62 such that no unsigned integer type with lesser size has at least the specified width.
  63
  64 The following minimum-width integer types are provided for all platforms:
  65
  66 * [^int_least8_t]
  67 * [^int_least16_t]
  68 * [^int_least32_t]
  69 * [^uint_least8_t]
  70 * [^uint_least16_t]
  71 * [^uint_least32_t]
  72
  73 The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:
  74
  75 * [^int_least64_t]
  76 * [^uint_least64_t]
  77
  78
  79 All other minimum-width integer types are optional.
  80
  81 [endsect]
  82
  83 [section Fastest minimum-width integer types]
  84
  85 The typedef [^int_fast#_t], with # replaced by the width, designates the fastest signed integer type
  86 with a width of at least # bits. Similarly, the typedef name [^uint_fast#_t] designates the fastest
  87 unsigned integer type with a width of at least # bits.
  88
  89 There is no guarantee that these types are fastest for all purposes. In any case, however, they satisfy
  90 the signedness and width requirements.
  91
  92 The following fastest minimum-width integer types are provided for all platforms:
  93
  94 * [^int_fast8_t]
  95 * [^int_fast16_t]
  96 * [^int_fast32_t]
  97 * [^uint_fast8_t]
  98 * [^uint_fast16_t]
  99 * [^uint_fast32_t]
 100
 101 The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:
 102
 103 * [^int_fast64_t]
 104 * [^uint_fast64_t]
 105
 106 All other fastest minimum-width integer types are optional.
 107
 108 [endsect]
 109
 110 [section Greatest-width integer types]
 111
 112 The typedef [^intmax_t ]designates a signed integer type capable of representing any value of any signed integer type.
 113
 114 The typedef [^uintmax_t] designates an unsigned integer type capable of representing any value of any unsigned integer type.
 115
 116 These types are provided for all platforms.
 117
 118 [endsect]
 119
 120 [section Integer Constant Macros]
 121
 122 The following macros are always defined after inclusion of this header, these allow
 123 integer constants of at least the specified width to be declared:
 124 INT8_C, UINT8_C, INT16_C, UINT16_C, INT32_C, UINT32_C, INTMAX_C, UINTMAX_C.
 125
 126 The macros INT64_C and UINT64_C are also defined if the the macro BOOST_NO_INT64_T is not defined.
 127
 128 The C99 macro __STDC_CONSTANT_MACROS is also defined as an artifact of the implementation.
 129
 130 For example:
 131
 132    #include <boost/cstdint.hpp>
 133
 134    // Here the constant 0x1FFFFFFFF has the correct suffix applied:
 135    static const boost::uint64_t c = INT64_C(0x1FFFFFFFF);
 136
 137 [endsect]
 138
 139 [endsect]