]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |