boostorg/integer
1
0
Fork 1
mirror of https://github.com/boostorg/integer.git synced 2025-07-15 21:52:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

Fix issues in docs.

Browse Source 
[SVN r58008]
This commit is contained in:
John Maddock
2009-11-28 17:08:31 +00:00
parent 6a497ee263
commit 05c1f88324
9 changed files with 288 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
doc/integer.qbk
View File

@ -15,7 +15,13 @@
[section:overview Overview]
Boost.Integer consists of the following components:
Boost.Integer provides integer type support, particularly helpful in generic programming. It provides standard
C99 integer types, such as might be found in <stdint.h>, without requiring that header.
It provides the means to select an integer type based upon its properties, like the number of bits or
the maximum supported value, as well as compile-time bit mask selection. There is a derivative of
std::numeric_limits that provides integral constant expressions for `min` and `max`.
Finally, it provides two compile-time algorithms: determining the highest power of two in a
compile-time value; and computing min and max of constant expressions.
[table
[[Component][Header][Purpose]]
@ -71,9 +77,9 @@ Boost.Integer consists of the following components:
The header [^[@../../../../boost/cstdint.hpp <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 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 in all implementations, because [^long long] is not [yet] included in the C++ standard.
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 [@../../test/cstdint_test.cpp cstdint_test.cpp] for a test program.
@ -82,9 +88,9 @@ See [@../../test/cstdint_test.cpp cstdint_test.cpp] for a test program.
[section:rationale Rationale]
The organization of the Boost.Integer headers and classes is designed to take advantage of <stdint.h> types from the
1999 C standard without resorting to undefined behavior in terms of the 1998 C++ standard.
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]. As always, the intension is to complement rather than compete
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.
@ -111,8 +117,9 @@ The typedef [^int#_t], with # replaced by the width, designates a signed integer
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 an implementation provides integer types with widths of 8, 16, 32, or 64 bits,
it shall define the corresponding typedef names.
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`.
@ -122,11 +129,11 @@ 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 a signed integer type with a width of at least 32 bits.
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.
Required minimum-width integer types:
The following minimum-width integer types are provided for all platforms:
* [^int_least8_t]
* [^int_least16_t]
@ -135,12 +142,11 @@ Required minimum-width integer types:
* [^uint_least16_t]
* [^uint_least32_t]
The types:
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]
Are available only if, after inclusion of [^<boost/cstdint.hpp>] the macro `BOOST_NO_INT64_T` is ['[*not defined]].
All other minimum-width integer types are optional.
@ -155,7 +161,7 @@ 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.
Required fastest minimum-width integer types:
The following fastest minimum-width integer types are provided for all platforms:
* [^int_fast8_t]
* [^int_fast16_t]
@ -164,13 +170,11 @@ Required fastest minimum-width integer types:
* [^uint_fast16_t]
* [^uint_fast32_t]
The types:
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]
Are available only if, after inclusion of [^<boost/cstdint.hpp>] the macro `BOOST_NO_INT64_T` is ['[*not defined]].
All other fastest minimum-width integer types are optional.
[endsect]
@ -181,7 +185,7 @@ The typedef [^intmax_t ]designates a signed integer type capable of representing
The typedef [^uintmax_t] designates an unsigned integer type capable of representing any value of any unsigned integer type.
These types are required.
These types are provided for all platforms.
[endsect]
[endsect]
@ -216,6 +220,7 @@ The template class [^integer_traits] addresses this problem.
template<class T>
class integer_traits : public std::numeric_limits<T>
{
public:
static const bool is_integral = false;
//
// These members are defined only if T is a built-in
@ -230,7 +235,7 @@ The template class [^integer_traits] addresses this problem.
[section Description]
Template class [^integer_traits] is derived from [^std::numeric_limits]. In general, it adds the single
Template class [^integer_traits] is derived from [^std::numeric_limits]. The primary specialization adds the single
[^bool] member [^is_integral] with the compile-time constant value [^false].
However, for all integral types [^T] (std::3.9.1/7 [basic.fundamental]), there are specializations
provided with the following compile-time constants defined:
@ -242,9 +247,9 @@ provided with the following compile-time constants defined:
[[[^const_max]][[^T]][equivalent to [^std::numeric_limits<T>::max()]]]
]
Note: A flag [^is_integral] is provided, because a user-defined integer class should specialize
[^std::numeric_limits<>::is_integer = true], nonetheless compile-time constants
[^const_min] and [^const_max] cannot be provided for that user-defined class.
Note: The /is_integral/ flag is provided, because a user-defined integer class should specialize
[^std::numeric_limits<>::is_integer = true], while compile-time constants
[^const_min] and [^const_max] are not provided for that user-defined class, unless boost::integer_traits is also specialized.
[endsect]
@ -275,7 +280,7 @@ This facility is particularly useful for solving generic programming problems.
template<typename LeastInt>
struct int_fast_t
{
typedef ``['implementation-defined-type]`` fast;
typedef ``['implementation-defined-type]`` type;
};
// signed
@ -330,12 +335,12 @@ The [^int_fast_t] class template maps its input type to the next-largest type th
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].
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 conditionalized for each platform to give accurate mappings between the built-in types and the easiest-to-manipulate
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.
[endsect]
@ -344,7 +349,7 @@ built-in types. Also, there is no guarantee that the output type actually is eas
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].
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 Criteria for the Sized Type Class Templates
@ -352,33 +357,71 @@ The following table describes each template's criteria.
[Class Template][Template Parameter Mapping]
]
[
[[^boost::int_t<N>]]
[The smallest built-in signed integral type with at least /N/ bits, including the sign bit.
[[^boost::int_t<N>::least]]
[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. Note that the member /exact/ is defined
[*only] if there is a type with exactly N bits.]
larger than the number of bits in the largest integer type.]
]
[
[[^boost::uint_t<N>]]
[The smallest built-in unsigned integral type with at least /N/ bits.
[[^boost::int_t<N>::fast]]
[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.]
]
[
[[^boost::int_t<N>::exact]]
[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.]
]
[
[[^boost::uint_t<N>::least]]
[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.]
]
[
[[^boost::uint_t<N>::fast]]
[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.]
]
[
[[^boost::uint_t<N>::exact]]
[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 is a type with exactly N bits.]
[*only] if there exists a type with exactly N bits.]
]
[
[[^boost::int_max_value_t<V>]]
[The smallest built-in signed integral type that can hold all the values in the inclusive range ['0 - V].
[[^boost::int_max_value_t<V>::last]]
[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.]
]
[
[[^boost::int_min_value_t<V>]]
[The smallest built-in signed integral type that can hold all the values in the inclusive range ['V-0].
[[^boost::int_max_value_t<V>::fast]]
[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.]
]
[
[[^boost::int_min_value_t<V>::least]]
[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.]
]
[
[[^boost::uint_value_t<V>]]
[The smallest built-in unsigned integral type that can hold all positive values
[[^boost::int_min_value_t<V>::fast]]
[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.]
]
[
[[^boost::uint_value_t<V>::least]]
[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.]
]
[
[[^boost::uint_value_t<V>::fast]]
[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.]
]
]
@ -500,9 +543,9 @@ the members of an instantiation of [^high_bit_mask_t].
[table Members of the `boost::high_bit_mask_t` Class Template
[[Member][Meaning]]
[[[^least]][The smallest unsigned built-in type that supports the given bit position.]]
[[[^fast]][The quick-to-manipulate analog of [^least].]]
[[[^high_bit]][A [^least] constant of the desired bit-masking value.]]
[[[^least]][The smallest, unsigned, built-in type that supports the given bit position.]]
[[[^fast]][The easiest-to-manipulate analog of [^least].]]
[[[^high_bit]][A [^least] constant of the value 2[super Bit].]]
[[[^high_bit_fast]][A [^fast] analog of [^high_bit].]]
[[[^bit_position]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]]
]
@ -511,16 +554,16 @@ the members of an instantiation of [^high_bit_mask_t].
[section Group Bit-Mask Class Template]
The [^boost::low_bits_mask_t] class template provides constants for bit masks representing the lowest
bits of a certain amount. The masks are equivalent to the value (2[super Bits] - 1),
where [^Bits] is the template parameter. The bit amount must be a nonnegative number from
zero to ['Max], where Max is the number of bits supported by the largest unsigned built-in integral type.
The following table describes the members of an instantiation of [^low_bits_mask_t].
The [^boost::low_bits_mask_t] class template provides constants for bit masks
equivalent to the value (2[super Bits] - 1), where [^Bits] is the template parameter.
The parameter [^Bits] must be a non-negative integer from
zero to ['Max], where Max is the number of bits supported by the largest, unsigned, built-in integral type.
The following table describes the members of [^low_bits_mask_t].
[table Members of the [^boost::low_bits_mask_t] Class Template
[[Member][Meaning]]
[[[^least]][The smallest unsigned built-in type that supports the given bit count.]]
[[[^fast]][The quick-to-manipulate analog of [^least].]]
[[[^least]][The smallest, unsigned built-in type that supports the given bit count.]]
[[[^fast]][The easiest-to-manipulate analog of [^least].]]
[[[^sig_bits]][A [^least] constant of the desired bit-masking value.]]
[[[^sig_bits_fast]][A [^fast] analog of [^sig_bits].]]
[[[^bit_count]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]]
@ -581,7 +624,7 @@ The author of the Boost bit mask class templates is [@http://www.boost.org/peopl
[endsect]
[endsect]
[section:log2 Compile time log2 Calculation]
[section:log2 Compile Time log2 Calculation]
The class template in [@../../../../boost/integer/static_log2.hpp <boost/integer/static_log2.hpp>]
determines the position of the highest bit in a given value. This facility is useful for solving generic programming problems.
@ -616,7 +659,7 @@ determines the position of the highest bit in a given value. This facility is us
The [^boost::static_log2] class template takes one template parameter, a value of type
[^static_log2_argument_type]. The template only defines one member, [^value], which gives the
truncated base-two logarithm of the template argument.
truncated, base-two logarithm of the template argument.
Since the logarithm of zero, for any base, is undefined, there is a specialization of [^static_log2]
for a template argument of zero. This specialization has no members, so an attempt to use the base-two
@ -629,37 +672,6 @@ Note:
[endsect]
[section Example]
#include "boost/integer/static_log2.hpp"
template < boost::static_log2_argument_type value >
bool is_it_what()
{
typedef boost::static_log2<value> lb_type;
int temp = lb_type::value;
//...
return (temp % 2) != 0;
}
//...
int main()
{
bool temp = is_it_what<2000>();
//...
# if 0
temp = is_it_what<0>(); // would give an error
# endif
//...
temp = is_it_what<24>();
//...
}
[endsect]
[section Demonstration Program]
The program [@../../test/static_log2_test.cpp static_log2_test.cpp] is a simplistic
@ -672,7 +684,7 @@ demonstration of the results from instantiating various examples of the binary l
The base-two (binary) logarithm, abbreviated lb, function is occasionally used to give order-estimates
of computer algorithms. The truncated logarithm can be considered the highest power-of-two in a value,
which corresponds to the value's highest set bit (for binary integers). Sometimes the highest-bit position
could be used in generic programming, which requires the position to be statically (['i.e.] at compile-time) available.
could be used in generic programming, which requires the position to be available statically (['i.e.] at compile-time).
[endsect]
@ -719,8 +731,8 @@ for generic programming problems.
[section Usage]
The four class templates provide the combinations for finding the minimum or maximum of two signed or
[^unsigned] ([^long]) parameters, Value1 and Value2, at compile-time. Each template has a single static data member,
The four class templates provide the combinations for finding the minimum or maximum of two [^signed] or
[^unsigned] ([^long]) parameters, /Value1/ and /Value2/, at compile-time. Each template has a single static data member,
[^value], which is set to the respective minimum or maximum of the template's parameters.
[endsect]