From ca84baa55db80d55245ff1b740e7bf4678ac7070 Mon Sep 17 00:00:00 2001 From: John Maddock Date: Wed, 25 Nov 2009 12:38:09 +0000 Subject: [PATCH] Update Boost.Integer meta-programming classes to work with intmax_t where possible - ie to be 64-bit clean. Added quickbook based docs - updated as necessary. Removed old html docs. [SVN r57926] --- cstdint.htm | 81 --- doc/Jamfile.v2 | 59 ++ doc/html/boost_integer/cstdint.html | 235 +++++++ doc/html/boost_integer/history.html | 82 +++ doc/html/boost_integer/integer.html | 323 +++++++++ doc/html/boost_integer/log2.html | 184 ++++++ doc/html/boost_integer/mask.html | 376 +++++++++++ doc/html/boost_integer/minmax.html | 160 +++++ doc/html/boost_integer/traits.html | 214 ++++++ doc/html/index.html | 238 +++++++ doc/integer.qbk | 801 +++++++++++++++++++++++ doc/integer_mask.html | 210 ------ doc/static_log2.html | 215 ------ doc/static_min_max.html | 120 ---- include/boost/integer.hpp | 2 +- include/boost/integer/static_log2.hpp | 11 +- include/boost/integer/static_min_max.hpp | 20 +- include/boost/integer_fwd.hpp | 26 +- index.html | 156 +---- integer.htm | 212 ------ integer_traits.html | 94 --- 21 files changed, 2714 insertions(+), 1105 deletions(-) delete mode 100644 cstdint.htm create mode 100644 doc/Jamfile.v2 create mode 100644 doc/html/boost_integer/cstdint.html create mode 100644 doc/html/boost_integer/history.html create mode 100644 doc/html/boost_integer/integer.html create mode 100644 doc/html/boost_integer/log2.html create mode 100644 doc/html/boost_integer/mask.html create mode 100644 doc/html/boost_integer/minmax.html create mode 100644 doc/html/boost_integer/traits.html create mode 100644 doc/html/index.html create mode 100644 doc/integer.qbk delete mode 100644 doc/integer_mask.html delete mode 100644 doc/static_log2.html delete mode 100644 doc/static_min_max.html delete mode 100644 integer.htm delete mode 100644 integer_traits.html diff --git a/cstdint.htm b/cstdint.htm deleted file mode 100644 index 9492827..0000000 --- a/cstdint.htm +++ /dev/null @@ -1,81 +0,0 @@ - - - - - - -Header boost/cstdint.hpp - - - - -

boost.png (6897 bytes)Header -boost/cstdint.hpp 

-

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 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.

-

See cstdint_test.cpp for a test program.

-

Exact-width integer types

-

The typedef int#_t, with # replaced by the width, designates a -signed integer type of exactly # bits; int8_t denotes an 8-bit -signed integer type.  Similarly, the typedef uint#_t -designates and 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.

-

Minimum-width integer types

-

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. 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:

- -

All other minimum-width integer types are optional.

-

Fastest minimum-width integer types

-

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.

-

Required fastest minimum-width integer types:

- -

All other fastest minimum-width integer types are optional.

-

Greatest-width integer types

-

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 required.

-
-

Revised 06 Nov 2007 -

-

© Copyright Beman Dawes 2000

- -

Distributed under the Boost Software License, Version 1.0. See -www.boost.org/LICENSE_1_0.txt

- - - - \ No newline at end of file diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 0000000..18c50ae --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,59 @@ + + +# Copyright John Maddock 2005. Use, modification, and distribution are +# subject to the Boost Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +using quickbook ; + +xml integer : integer.qbk ; +boostbook standalone + : + integer + : + # HTML options first: + # Use graphics not text for navigation: + navig.graphics=1 + # How far down we chunk nested sections, basically all of them: + chunk.section.depth=1 + # Don't put the first section on the same page as the TOC: + chunk.first.sections=0 + # How far down sections get TOC's + toc.section.depth=1 + # Max depth in each TOC: + toc.max.depth=1 + # How far down we go with TOC's + generate.section.toc.level=4 + # Path for links to Boost: + boost.root=../../../.. + # Path for libraries index: + boost.libraries=../../../../libs/libraries.htm + # Use the main Boost stylesheet: + html.stylesheet=../../../../doc/html/boostbook.css + + # PDF Options: + # TOC Generation: this is needed for FOP-0.9 and later: + fop1.extensions=0 + # Or enable this if you're using XEP: + xep.extensions=1 + # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9! + fop.extensions=0 + # No indent on body text: + body.start.indent=0pt + # Margin size: + page.margin.inner=0.5in + # Margin size: + page.margin.outer=0.5in + # Yes, we want graphics for admonishments: + admon.graphics=1 + # Set this one for PDF generation *only*: + # default pnd graphics are awful in PDF form, + # better use SVG's instead: + pdf:admon.graphics.extension=".svg" + pdf:admon.graphics.path=$(boost-images)/ + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/regex/doc/html + ; + +install pdf-install : standalone : . PDF ; + + diff --git a/doc/html/boost_integer/cstdint.html b/doc/html/boost_integer/cstdint.html new file mode 100644 index 0000000..fca043b --- /dev/null +++ b/doc/html/boost_integer/cstdint.html @@ -0,0 +1,235 @@ + + + +Standard Integer Types + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Overview
+
Rationale
+
Caveat emptor
+
Exact-width + integer types
+
Minimum-width + integer types
+
Fastest + minimum-width integer types
+
Greatest-width + integer types
+
+
+
+

+ 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 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. +

+

+ 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 + resorting to 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 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 an implementation provides integer + types with widths of 8, 16, 32, or 64 bits, it shall define the corresponding + typedef names. +

+

+ 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. 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: +

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

+ The types: +

+
    +
  • 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. +

+
+
+
+

+ 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. +

+

+ Required fastest minimum-width integer types: +

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

+ The types: +

+
    +
  • 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. +

+
+
+
+

+ 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 required. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/history.html b/doc/html/boost_integer/history.html new file mode 100644 index 0000000..fb7fc8a --- /dev/null +++ b/doc/html/boost_integer/history.html @@ -0,0 +1,82 @@ + + + +History + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+
+
+ + 1.42.0 +
+
    +
  • + Reverted Trunk to release branch state (i.e. a "known good state"). +
    • +
  • + Fixed issues: 653, + 3084, + 3177, + 3180, + 3568, + 3657, + 2134. +
    • +
  • + Added long long support to boost::static_log2, boost::static_signed_min, + boost::static_signed_max, boost::static_unsigned_minboost::static_unsigned_max, + when available. +
    • +
  • + The argument type and the result type of boost::static_signed_min + etc are now typedef'd. Formerly, they were hardcoded as unsigned + long and int respectively. Please, use the provided + typedefs in new code (and update old code as soon as possible). +
    • +
+
+ + 1.32.0 +
+
  • + The argument type and the result type of boost::static_log2 + are now typedef'd. Formerly, they were hardcoded as unsigned long + and int respectively. Please, use the provided typedefs + in new code (and update old code as soon as possible). +
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHome +
+ + diff --git a/doc/html/boost_integer/integer.html b/doc/html/boost_integer/integer.html new file mode 100644 index 0000000..8772326 --- /dev/null +++ b/doc/html/boost_integer/integer.html @@ -0,0 +1,323 @@ + + + +Integer Type Selection + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Synopsis
+
Easiest-to-Manipulate + Types
+
Sized Types
+
Example
+
Demonstration + Program
+
Rationale
+
Alternative
+
Credits
+
+

+ 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  fast;
+  };
+
+  //  signed
+  template<int Bits>
+  struct int_t 
+  {
+      typedef implementation-defined-type  least;
+      typedef int_fast_t<least>::fast      fast;
+  };
+
+  //  unsigned
+  template<int Bits>
+  struct uint_t 
+  {
+      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, despite the name. The output type is given as the + class member 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 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 class member least. + The easiest-to-manipulate version of that type is given by the class member + fast. The following table describes each template's criteria. +

+
+

Table 1. Criteria for the Sized Type Class Templates

+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ 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. 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> +

+ 		+

+ 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::int_max_value_t<V> +

+ 		+

+ 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. 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 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, it's 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: +

+
    +
  • + Avoid recursion because of concern about C++'s limited guaranteed recursion + depth (17). +
    • +
  • + Avoid macros on general principles. +
    • +
  • + Try to keep the design as simple as possible. +
    • +
+
+
+
+

+ 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. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/log2.html b/doc/html/boost_integer/log2.html new file mode 100644 index 0000000..2d5f4d0 --- /dev/null +++ b/doc/html/boost_integer/log2.html @@ -0,0 +1,184 @@ + + + +Compile time log2 Calculation + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Synopsis
+
Usage
+
Example
+
Demonstration + Program
+
Rationale
+
Credits
+
+

+ The class template in <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. +

+
+
+
namespace boost
+{
+
+  typedef implementation-defined static_log2_argument_type;
+  typedef implementation-defined static_log2_result_type;
+
+  template <static_log2_argument_type arg>
+  struct static_log2
+  {
+    static const static_log2_result_type value = implementation-defined;
+  };
+
+
+  template < >
+  struct static_log2< 0 >
+  {
+    // The logarithm of zero is undefined.
+  };
+
+
+}  // namespace boost
+
+
+
+

+Usage +

+

+ 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. +

+

+ 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 logarithm of zero results + in a compile-time error. +

+

+ Note: +

+
    +
  • +static_log2_argument_type is an unsigned integer + type (C++ standard, 3.9.1p3). +
    • +
  • +static_log2_result_type is an integer type + (C++ standard, 3.9.1p7). +
    • +
+
+
+
+
#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>();
+    //...
+}
+
+
+
+
+

+ The program static_log2_test.cpp + is a simplistic demonstration of the results from instantiating various examples + of the binary logarithm class template. +

+
+
+
+

+ 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. +

+
+
+
+

+ The original version of the Boost binary logarithm class template was written + by Daryle Walker + and then enhanced by Giovanni Bajo with support for compilers without partial + template specialization. The current version was suggested, together with + a reference implementation, by Vesa Karvonen. Gennaro Prota wrote the actual + source file. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/mask.html b/doc/html/boost_integer/mask.html new file mode 100644 index 0000000..e8ca8e2 --- /dev/null +++ b/doc/html/boost_integer/mask.html @@ -0,0 +1,376 @@ + + + +Integer Masks + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Overview
+
Synopsis
+
Single + Bit-Mask Class Template
+
Group + Bit-Mask Class Template
+
Implementation + Notes
+
Example
+
Demonstration + Program
+
Rationale
+
Credits
+
+
+
+

+ The class templates in <boost/integer/integer_mask.hpp> + provide bit masks for a certain bit position or a contiguous-bit pack of + a certain size. The types of the masking constants come from the integer + type selection templates header. +

+
+
+
+
#include <cstddef>  // for std::size_t
+
+namespace boost
+{
+
+template <std::size_t Bit>
+struct high_bit_mask_t
+{
+    typedef implementation-defined-type  least;
+    typedef implementation-defined-type  fast;
+
+    static const least       high_bit       = implementation-defined;
+    static const fast        high_bit_fast  = implementation-defined;
+
+    static const std::size_t bit_position   = Bit;
+};
+
+template <std::size_t Bits>
+struct low_bits_mask_t
+{
+    typedef implementation-defined-type  least;
+    typedef implementation-defined-type  fast;
+
+    static const least       sig_bits       = implementation-defined;
+    static const fast        sig_bits_fast  = implementation-defined;
+
+    static const std::size_t bit_count      = Bits;
+};
+
+// Specializations for low_bits_mask_t exist for certain bit counts.
+
+}  // namespace boost
+
+
+
+
+

+ The boost::high_bit_mask_t class template provides constants + for bit masks representing the bit at a certain position. The masks are equivalent + to the value 2Bit, where Bit is the template parameter. + The bit position must be a nonnegative number from zero to Max, + where Max is one less than the number of bits supported by the largest unsigned + built-in integral type. The following table describes the members of an instantiation + of high_bit_mask_t. +

+
+

Table 2. 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. +

+
+

+ 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. +

+
+
+
+
+
+
+

+ 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 (2Bits - 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. +

+
+

Table 3. 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. +

+
+

+ 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. +

+
+
+
+
+
+
+

+ When Bits is the exact size of a built-in unsigned type, + the implementation has to change to prevent undefined behavior. Therefore, + there are specializations of low_bits_mask_t at those + bit counts. +

+
+
+
+
#include <boost/integer/integer_mask.hpp>
+
+//...
+
+int main()
+{
+    typedef boost::high_bit_mask_t<29>  mask1_type;
+    typedef boost::low_bits_mask_t<15>  mask2_type;
+
+    mask1_type::least  my_var1;
+    mask2_type::fast   my_var2;
+    //...
+
+    my_var1 |= mask1_type::high_bit;
+    my_var2 &= mask2_type::sig_bits_fast;
+
+    //...
+}
+
+
+
+
+

+ The program integer_mask_test.cpp + is a simplistic demonstration of the results from instantiating various examples + of the bit mask class templates. +

+
+
+
+

+ The class templates in this header are an extension of the integer + type selection class templates. The new class templates provide the + same sized types, but also convienent masks to use when extracting the highest + or all the significant bits when the containing built-in type contains more + bits. This prevents contaimination of values by the higher, unused bits. +

+
+
+
+

+ The author of the Boost bit mask class templates is Daryle + Walker. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/minmax.html b/doc/html/boost_integer/minmax.html new file mode 100644 index 0000000..c25e4fc --- /dev/null +++ b/doc/html/boost_integer/minmax.html @@ -0,0 +1,160 @@ + + + +Compile time min/max calculation + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Synopsis
+
Usage
+
Example
+
Demonstration + Program
+
Rationale
+
Credits
+
+

+ The class templates in <boost/integer/static_min_max.hpp> + provide a compile-time evaluation of the minimum or maximum of two integers. + These facilities are useful for generic programming problems. +

+
+
+
namespace boost
+{
+
+typedef implementation-defined static_min_max_signed_type;
+typedef implementation-defined static_min_max_unsigned_type;
+
+template <static_min_max_signed_type Value1, static_min_max_signed_type Value2 >
+    struct static_signed_min;
+
+template <static_min_max_signed_type Value1, static_min_max_signed_type Value2>
+    struct static_signed_max;
+
+template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Value2>
+    struct static_unsigned_min;
+
+template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Value2>
+    struct static_unsigned_max;
+
+}
+
+
+
+

+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, value, which is set to the respective + minimum or maximum of the template's parameters. +

+
+
+
+
#include <boost/integer/static_min_max.hpp>
+
+template < unsigned long AddendSize1, unsigned long AddendSize2 >
+class adder
+{
+public:
+    static  unsigned long  const  addend1_size = AddendSize1;
+    static  unsigned long  const  addend2_size = AddendSize2;
+    static  unsigned long  const  sum_size = boost::static_unsigned_max<AddendSize1, AddendSize2>::value + 1;
+
+    typedef int  addend1_type[ addend1_size ];
+    typedef int  addend2_type[ addend2_size ];
+    typedef int  sum_type[ sum_size ];
+
+    void  operator ()( addend1_type const &a1, addend2_type const &a2, sum_type &s ) const;
+};
+
+//...
+
+int main()
+{
+    int const   a1[] = { 0, 4, 3 };  // 340
+    int const   a2[] = { 9, 8 };     //  89
+    int         s[ 4 ];
+    adder<3,2>  obj;
+
+    obj( a1, a2, s );  // 's' should be 429 or { 9, 2, 4, 0 }
+    //...
+}
+
+
+
+
+

+ The program static_min_max_test.cpp + is a simplistic demonstration of various comparisons using the compile-time + extrema class templates. +

+
+
+
+

+ Sometimes the minimum or maximum of several values needs to be found for + later compile-time processing, e.g. for a bound for + another class template. +

+
+
+
+

+ The author of the Boost compile-time extrema class templates is Daryle + Walker. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/traits.html b/doc/html/boost_integer/traits.html new file mode 100644 index 0000000..c6dbe6c --- /dev/null +++ b/doc/html/boost_integer/traits.html @@ -0,0 +1,214 @@ + + + +Integer Traits + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Motivation
+
Synopsis
+
Description
+
Test Program
+
Acknowledgements
+
+
+
+

+ The C++ Standard Library <limits> header supplies a class template + numeric_limits<> + with specializations for each fundamental type. +

+

+ For integer types, the interesting members of std::numeric_limits<> are: +

+
static const bool is_specialized;      // Will be true for integer types.
+static T min() throw();                // Smallest representable value.
+static T max() throw();                // Largest representable value.
+static const int digits;               // For integers, the number of value bits.
+static const int digits10;             // The number of base 10 digits that can be represented.
+static const bool is_signed;           // True if the type is signed.
+static const bool is_integer;          // Will be true for all integer types.
+
+

+ For many uses, these are sufficient. But min() and max() are problematical + because they are not constant expressions (std::5.19), yet some usages require + constant expressions. +

+

+ The template class integer_traits addresses this problem. +

+
+
+
+
namespace boost {
+  template<class T>
+  class integer_traits : public std::numeric_limits<T>
+  {
+     static const bool is_integral = false;
+     //
+     // These members are defined only if T is a built-in
+     // integal type:
+     //
+     static const T const_min = implementation-defined;
+     static const T const_max = implementation-defined;
+  };
+}
+
+
+
+
+

+ Template class integer_traits is derived from std::numeric_limits. + In general, it 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: +

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +
+

+ member +

+ 		+

+ type +

+ 		+

+ value +

+
+

+ is_integral +

+ 		+

+ bool +

+ 		+

+ true +

+
+

+ const_min +

+ 		+

+ T +

+ 		+

+ equivalent to std::numeric_limits<T>::min() +

+
+

+ 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. +

+
+
+
+

+ The program integer_traits_test.cpp + exercises the integer_traits class. +

+
+
+
+

+ Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers discussed the integer + traits idea on the boost mailing list in August 1999. +

+
+
+ + + +
Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..69f0579 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,238 @@ + + + +Boost.Integer + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
Next
+
+
+
+

+Boost.Integer

+
+

+Beman Dawes +

+

+Daryle Walker +

+

+Gennaro Prota +

+

+John Maddock +

+
+

Copyright © 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, + John Maddock

+
+

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+
+
+

Table of Contents

+
+
Overview
+
Standard Integer Types
+
Integer Traits
+
Integer Type Selection
+
Integer Masks
+
Compile time log2 Calculation
+
Compile time min/max calculation
+
History
+
+
+
+
+

+ Boost.Integer consists of the following components: +

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

+ Component +

+ 		+

+ Header +

+ 		+

+ Purpose +

+
+

+ Forward Declarations. +

+ 		+

+ <boost/integer_fwd.hpp> +

+ 		+

+ Forward declarations of classes and class templates - for use when + just the name of a class is needed. +

+
+

+ Standard Integer Types. +

+ 		+

+ <boost/cstdint.hpp> +

+ 		+

+ Provides typedef's based on the 1999 C Standard header <stdint.h>, wrapped in namespace boost. This + implementation may #include the compiler supplied <stdint.h>, + if present. +

+
+

+ Integer Traits. +

+ 		+

+ <boost/integer_traits.hpp> +

+ 		+

+ Class template boost::integer_traits, derives from + std::numeric_limits and adds const_min + and const_max members. +

+
+

+ Integer Type Selection. +

+ 		+

+ <boost/integer.hpp> +

+ 		+

+ Templates for integer type selection based on properties such as maximum + value or number of bits: Use to select the type of an integer when + some property such as maximum value or number of bits is known. Useful + for generic programming. +

+
+

+ Integer Masks. +

+ 		+

+ <boost/integer/integer_mask.hpp> +

+ 		+

+ Templates for the selection of integer masks, single or lowest group, + based on the number of bits: Use to select a particular mask when the + bit position(s) are based on a compile-time variable. Useful for generic + programming. +

+
+

+ Compile time log2 Calculation. +

+ 		+

+ <boost/integer/static_log2.hpp> +

+ 		+

+ Template for finding the highest power of two in a number: Use to find + the bit-size/range based on a maximum value. Useful for generic programming. +

+
+

+ Compile time min/max calculation. +

+ 		+

+ <boost/integer/static_min_max.hpp> +

+ 		+

+ Templates for finding the extrema of two numbers: Use to find a bound + based on a minimum or maximum value. Useful for generic programming. +

+
+
+
+ + + +

Last revised: November 25, 2009 at 12:02:32 GMT

+
+
Next
+ + diff --git a/doc/integer.qbk b/doc/integer.qbk new file mode 100644 index 0000000..403b010 --- /dev/null +++ b/doc/integer.qbk @@ -0,0 +1,801 @@ +[article Boost.Integer + [quickbook 1.5] + [copyright 2001-2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock] + [purpose Integer Type Selection] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] + [authors [Dawes, Beman], [Walker, Daryle], [Prota, Gennaro], [Maddock, John]] + [/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $] +] + +[template super[x]''''''[x]''''''] + +[section:overview Overview] + +Boost.Integer consists of the following components: + +[table + [[Component][Header][Purpose]] + [ + [Forward Declarations.] + [[^[@../../../../boost/integer_fwd.hpp ]]] + [Forward declarations of classes and class templates - for use when just the name of a class is needed.] + ] + [ + [[link boost_integer.cstdint Standard Integer Types].] + [[^[@../../../../boost/cstdint.hpp ]]] + [Provides typedef's based on the 1999 C Standard header ``, wrapped in namespace boost. + This implementation may #include the compiler supplied ``, if present.] + ] + [ + [[link boost_integer.traits Integer Traits].] + [[^[@../../../../boost/integer_traits.hpp ]]] + [Class template [^boost::integer_traits], derives from [^std::numeric_limits] and adds [^const_min] and [^const_max] members.] + ] + [ + [[link boost_integer.integer Integer Type Selection].] + [[^[@../../../../boost/hpp ]]] + [Templates for integer type selection based on properties such as maximum value or number of bits: + Use to select the type of an integer when some property such as maximum value or number of bits is known. + Useful for generic programming. ] + ] + [ + [[link boost_integer.mask Integer Masks].] + [[^[@../../../../boost/integer/integer_mask.hpp ]]] + [Templates for the selection of integer masks, single or lowest group, based on the number of bits: + Use to select a particular mask when the bit position(s) are based on a compile-time variable. Useful for generic programming. ] + ] + [ + [[link boost_integer.log2 Compile time log2 Calculation].] + [[^[@../../../../boost/integer/static_log2.hpp ]]] + [Template for finding the highest power of two in a number: + Use to find the bit-size/range based on a maximum value. Useful for generic programming. ] + ] + [ + [[link boost_integer.minmax Compile time min/max calculation].] + [[^[@../../../../boost/integer/static_min_max.hpp ]]] + [Templates for finding the extrema of two numbers: + Use to find a bound based on a minimum or maximum value. Useful for generic programming. ] + ] +] + +[endsect] + +[section:cstdint Standard Integer Types] + +[section Overview] + +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 are based on the ISO/IEC 9899:1999 C Language standard header . +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. + +See [@../../test/cstdint_test.cpp cstdint_test.cpp] for a test program. + +[endsect] + +[section:rationale Rationale] + +The organization of the Boost.Integer headers and classes is designed to take advantage of types from the +1999 C standard without resorting to undefined behavior in terms of the 1998 C++ standard. +The header 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 +with the C++ Standard Library. Should some future C++ standard include and , +then 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. + +[endsect] + +[section:ce ['Caveat emptor]] + +As an implementation artifact, certain C macro names may possibly be +visible to users of . 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 typedef names may possibly be visible +in the global namespace to users of . Don't use these names, they are not part of +any Boost-specified interface. Use the respective names in namespace [^boost] instead. + +[endsect] + +[section Exact-width integer types] + +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 an implementation provides integer types with widths of 8, 16, 32, or 64 bits, +it shall define the corresponding typedef names. + +The absence of int64_t and uint64_t is indicated by the macro `BOOST_NO_INT64_T`. + +[endsect] + +[section Minimum-width integer types] + +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. +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: + +* [^int_least8_t] +* [^int_least16_t] +* [^int_least32_t] +* [^uint_least8_t] +* [^uint_least16_t] +* [^uint_least32_t] + +The types: + +* [^int_least64_t] +* [^uint_least64_t] + +Are available only if, after inclusion of [^] the macro `BOOST_NO_INT64_T` is ['[*not defined]]. + +All other minimum-width integer types are optional. + +[endsect] + +[section Fastest minimum-width integer types] + +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. + +Required fastest minimum-width integer types: + +* [^int_fast8_t] +* [^int_fast16_t] +* [^int_fast32_t] +* [^uint_fast8_t] +* [^uint_fast16_t] +* [^uint_fast32_t] + +The types: + +* [^int_fast64_t] +* [^uint_fast64_t] + +Are available only if, after inclusion of [^] the macro `BOOST_NO_INT64_T` is ['[*not defined]]. + +All other fastest minimum-width integer types are optional. + +[endsect] + +[section Greatest-width integer types] + +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 required. + +[endsect] +[endsect] + +[section:traits Integer Traits] + +[section Motivation] + +The C++ Standard Library header supplies a class template `numeric_limits<>` with specializations for each fundamental type. + +For integer types, the interesting members of `std::numeric_limits<>` are: + + static const bool is_specialized; // Will be true for integer types. + static T min() throw(); // Smallest representable value. + static T max() throw(); // Largest representable value. + static const int digits; // For integers, the number of value bits. + static const int digits10; // The number of base 10 digits that can be represented. + static const bool is_signed; // True if the type is signed. + static const bool is_integer; // Will be true for all integer types. + +For many uses, these are sufficient. +But min() and max() are problematical because they are not constant expressions (std::5.19), +yet some usages require constant expressions. + +The template class [^integer_traits] addresses this problem. + +[endsect] + +[section Synopsis] + + namespace boost { + template + class integer_traits : public std::numeric_limits + { + static const bool is_integral = false; + // + // These members are defined only if T is a built-in + // integal type: + // + static const T const_min = ``['implementation-defined]``; + static const T const_max = ``['implementation-defined]``; + }; + } + +[endsect] + +[section Description] + +Template class [^integer_traits] is derived from [^std::numeric_limits]. In general, it 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: + +[table + [[member][type][value]] + [[[^is_integral]][bool][[^true]]] + [[[^const_min]][[^T]][equivalent to [^std::numeric_limits::min()]]] + [[[^const_max]][[^T]][equivalent to [^std::numeric_limits::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. + +[endsect] + +[section Test Program] + +The program [^[@../../test/integer_traits_test.cpp integer_traits_test.cpp]] exercises the [^integer_traits] class. + +[endsect] + +[section Acknowledgements] + +Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers discussed the integer traits idea on the boost mailing list in August 1999. + +[endsect] +[endsect] + +[section:integer Integer Type Selection] + +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. + +[section:synopsis Synopsis] + + namespace boost + { + // fast integers from least integers + template + struct int_fast_t + { + typedef ``['implementation-defined-type]`` fast; + }; + + // signed + template + struct int_t + { + typedef ``['implementation-defined-type]`` least; + typedef int_fast_t::fast fast; + }; + + // unsigned + template + struct uint_t + { + typedef ``['implementation-defined-type]`` least; + typedef int_fast_t::fast fast; + }; + + // signed + template + struct int_max_value_t + { + typedef ``['implementation-defined-type]`` least; + typedef int_fast_t::fast fast; + }; + + template + struct int_min_value_t + { + typedef ``['implementation-defined-type]`` least; + typedef int_fast_t::fast fast; + }; + + // unsigned + template + struct uint_value_t + { + typedef ``['implementation-defined-type]`` least; + typedef int_fast_t::fast fast; + }; + } // namespace boost + +[endsect] + +[section:easiest Easiest-to-Manipulate Types] + +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, despite the name. +The output type is given as the class member [^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 +built-in types. Also, there is no guarantee that the output type actually is easier to manipulate than the input type. + +[endsect] + +[section:sized Sized Types] + +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]. +The following table describes each template's criteria. + +[table Criteria for the Sized Type Class Templates + [ + [Class Template][Template Parameter Mapping] + ] + [ + [[^boost::int_t]] + [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.] + ] + [ + [[^boost::uint_t]] + [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::int_max_value_t]] + [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]] + [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]] + [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.] + ] +] + +[endsect] + +[section Example] + + #include + + //... + + 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, it's size may be greater than + // that of my1000: + boost::int_max_value_t<1000>::fast my_fast1000 = 1000; + } + +[endsect] + +[section Demonstration Program] + +The program [@../../test/integer_test.cpp integer_test.cpp] is a simplistic demonstration of the results from instantiating +various examples of the sized type class templates. + +[endsect] + +[section Rationale] + +The rationale for the design of the templates in this header includes: + +* Avoid recursion because of concern about C++'s limited guaranteed recursion depth (17). +* Avoid macros on general principles. +* Try to keep the design as simple as possible. + +[endsect] + +[section Alternative] + +If the number of bits required is known beforehand, it may be more appropriate to use the types supplied +in [@../../../../boost/cstdint.hpp ]. + +[endsect] + +[section Credits] + +The author of most of the Boost integer type choosing templates is +[@http://www.boost.org/people/beman_dawes.html Beman Dawes]. +He gives thanks to Valentin Bonnard and [@http://www.boost.org/people/kevlin_henney.htm Kevlin Henney] +for sharing their designs for similar templates. +[@http://www.boost.org/people/daryle_walker.html Daryle Walker] designed the value-based sized templates. + +[endsect] +[endsect] + + + +[section:mask Integer Masks] + +[section Overview] + +The class templates in [@../../../../boost/integer/integer_mask.hpp ] +provide bit masks for a certain bit position or a contiguous-bit pack of a certain size. +The types of the masking constants come from the [link boost_integer.integer integer type selection templates] header. + +[endsect] + +[section Synopsis] + + #include // for std::size_t + + namespace boost + { + + template + struct high_bit_mask_t + { + typedef ``['implementation-defined-type]`` least; + typedef ``['implementation-defined-type]`` fast; + + static const least high_bit = ``['implementation-defined]``; + static const fast high_bit_fast = ``['implementation-defined]``; + + static const std::size_t bit_position = Bit; + }; + + template + struct low_bits_mask_t + { + typedef ``['implementation-defined-type]`` least; + typedef ``['implementation-defined-type]`` fast; + + static const least sig_bits = ``['implementation-defined]``; + static const fast sig_bits_fast = ``['implementation-defined]``; + + static const std::size_t bit_count = Bits; + }; + + // Specializations for low_bits_mask_t exist for certain bit counts. + + } // namespace boost + +[endsect] + +[section Single Bit-Mask Class Template] + +The [^boost::high_bit_mask_t] class template provides constants for bit masks representing the bit at a +certain position. The masks are equivalent to the value 2[super Bit], where [^Bit] is the template parameter. +The bit position must be a nonnegative number from zero to ['Max], where Max is one less than the +number of bits supported by the largest unsigned built-in integral type. The following table describes +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.]] + [[[^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.]] +] + +[endsect] + +[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]. + +[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].]] +[[[^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.]] +] + +[endsect] + +[section Implementation Notes] + +When [^Bits] is the exact size of a built-in unsigned type, the implementation has to change to +prevent undefined behavior. Therefore, there are specializations of [^low_bits_mask_t] at those bit counts. + +[endsect] + +[section Example] + + #include + + //... + + int main() + { + typedef boost::high_bit_mask_t<29> mask1_type; + typedef boost::low_bits_mask_t<15> mask2_type; + + mask1_type::least my_var1; + mask2_type::fast my_var2; + //... + + my_var1 |= mask1_type::high_bit; + my_var2 &= mask2_type::sig_bits_fast; + + //... + } + +[endsect] + +[section Demonstration Program] + +The program [@../../test/integer_mask_test.cpp integer_mask_test.cpp] is a simplistic demonstration of the +results from instantiating various examples of the bit mask class templates. + +[endsect] + +[section Rationale] + +The class templates in this header are an extension of the [link boost_integer.integer integer type selection class templates]. +The new class templates provide the same sized types, but also convienent masks to use when extracting the +highest or all the significant bits when the containing built-in type contains more bits. +This prevents contaimination of values by the higher, unused bits. + +[endsect] + +[section Credits] + +The author of the Boost bit mask class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. + +[endsect] +[endsect] + +[section:log2 Compile time log2 Calculation] + +The class template in [@../../../../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. + +[section Synopsis] + + namespace boost + { + + typedef ``['implementation-defined]`` static_log2_argument_type; + typedef ``['implementation-defined]`` static_log2_result_type; + + template + struct static_log2 + { + static const static_log2_result_type value = ``['implementation-defined]``; + }; + + + template < > + struct static_log2< 0 > + { + // The logarithm of zero is undefined. + }; + + + } // namespace boost + +[endsect] + +[section Usage] + +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. + +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 +logarithm of zero results in a compile-time error. + +Note: + +* [^static_log2_argument_type] is an ['unsigned integer type] (C++ standard, 3.9.1p3). +* [^static_log2_result_type] is an ['integer type] (C++ standard, 3.9.1p7). + +[endsect] + +[section Example] + + #include "boost/integer/static_log2.hpp" + + + template < boost::static_log2_argument_type value > + bool is_it_what() + { + typedef boost::static_log2 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 +demonstration of the results from instantiating various examples of the binary logarithm class template. + +[endsect] + +[section Rationale] + +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. + +[endsect] + +[section Credits] + +The original version of the Boost binary logarithm class template was +written by [@http://www.boost.org/people/daryle_walker.html Daryle Walker] and then +enhanced by Giovanni Bajo with support for compilers without partial template specialization. +The current version was suggested, together with a reference implementation, by Vesa Karvonen. +Gennaro Prota wrote the actual source file. + +[endsect] +[endsect] + +[section:minmax Compile time min/max calculation] + +The class templates in [@../../../../boost/integer/static_min_max.hpp ] +provide a compile-time evaluation of the minimum or maximum of two integers. These facilities are useful +for generic programming problems. + +[section Synopsis] + + namespace boost + { + + typedef ``['implementation-defined]`` static_min_max_signed_type; + typedef ``['implementation-defined]`` static_min_max_unsigned_type; + + template + struct static_signed_min; + + template + struct static_signed_max; + + template + struct static_unsigned_min; + + template + struct static_unsigned_max; + + } + +[endsect] + +[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, +[^value], which is set to the respective minimum or maximum of the template's parameters. + +[endsect] + +[section Example] + + #include + + template < unsigned long AddendSize1, unsigned long AddendSize2 > + class adder + { + public: + static unsigned long const addend1_size = AddendSize1; + static unsigned long const addend2_size = AddendSize2; + static unsigned long const sum_size = boost::static_unsigned_max::value + 1; + + typedef int addend1_type[ addend1_size ]; + typedef int addend2_type[ addend2_size ]; + typedef int sum_type[ sum_size ]; + + void operator ()( addend1_type const &a1, addend2_type const &a2, sum_type &s ) const; + }; + + //... + + int main() + { + int const a1[] = { 0, 4, 3 }; // 340 + int const a2[] = { 9, 8 }; // 89 + int s[ 4 ]; + adder<3,2> obj; + + obj( a1, a2, s ); // 's' should be 429 or { 9, 2, 4, 0 } + //... + } + +[endsect] + +[section Demonstration Program] + +The program [@../../test/static_min_max_test.cpp static_min_max_test.cpp] is a simplistic demonstration of +various comparisons using the compile-time extrema class templates. + +[endsect] + +[section Rationale] + +Sometimes the minimum or maximum of several values needs to be found for later compile-time processing, +['e.g.] for a bound for another class template. + +[endsect] + +[section Credits] + +The author of the Boost compile-time extrema class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. + +[endsect] +[endsect] + +[section:history History] + +[h4 1.42.0] + +* Reverted Trunk to release branch state (i.e. a "known good state"). +* Fixed issues: [@https://svn.boost.org/trac/boost/ticket/653 653], +[@https://svn.boost.org/trac/boost/ticket/3084 3084], +[@https://svn.boost.org/trac/boost/ticket/3177 3177], +[@https://svn.boost.org/trac/boost/ticket/3180 3180], +[@https://svn.boost.org/trac/boost/ticket/3548 3568], +[@https://svn.boost.org/trac/boost/ticket/3657 3657], +[@https://svn.boost.org/trac/boost/ticket/2134 2134]. +* Added long long support to [^boost::static_log2], [^boost::static_signed_min], [^boost::static_signed_max], +[^boost::static_unsigned_min][^boost::static_unsigned_max], when available. +* The argument type and the result type of [^boost::static_signed_min] etc are now typedef'd. +Formerly, they were hardcoded as [^unsigned long] and [^int] respectively. Please, use the +provided typedefs in new code (and update old code as soon as possible). + +[h4 1.32.0] + +* The argument type and the result type of [^boost::static_log2] are now typedef'd. +Formerly, they were hardcoded as [^unsigned long] and [^int] respectively. Please, use the +provided typedefs in new code (and update old code as soon as possible). + +[endsect] + diff --git a/doc/integer_mask.html b/doc/integer_mask.html deleted file mode 100644 index 5bc7301..0000000 --- a/doc/integer_mask.html +++ /dev/null @@ -1,210 +0,0 @@ - - - -Integer Bit Mask Templates - - - -

boost.png (6897 bytes)Integer Bit Mask Templates

- -

The class templates in <boost/integer/integer_mask.hpp> provide bit masks for a certain bit position or a contiguous-bit pack of a certain size. The types of the masking constants come from the integer type selection templates header.

- -

Contents

- - - -

Synopsis

- -
-#include <cstddef>  // for std::size_t
-
-namespace boost
-{
-
-template < std::size_t Bit >
-struct high_bit_mask_t
-{
-    typedef implementation_supplied  least;
-    typedef implementation_supplied   fast;
-
-    static const least  high_bit = implementation_defined;
-    static const fast   high_bit_fast = implementation_defined;
-
-    static const std::size_t  bit_position = Bit;
-
-};
-
-template < std::size_t Bits >
-struct low_bits_mask_t
-{
-    typedef implementation_supplied  least;
-    typedef implementation_supplied   fast;
-
-    static const least  sig_bits = implementation_defined;
-    static const fast   sig_bits_fast = implementation_defined;
-
-    static const std::size_t  bit_count = Bits;
-
-};
-
-// Specializations for low_bits_mask_t exist for certain bit counts.
-
-}  // namespace boost
-
- -

Single Bit-Mask Class Template

- -

The boost::high_bit_mask_t class template provides -constants for bit masks representing the bit at a certain position. The -masks are equivalent to the value 2Bit, where -Bit is the template parameter. The bit position must be a -nonnegative number from zero to Max, where Max is one -less than the number of bits supported by the largest unsigned built-in -integral type. The following table describes the members of an -instantiation of high_bit_mask_t.

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Members of the boost::high_bit_mask_t Class - Template
MemberMeaning
leastThe smallest unsigned built-in type that supports the given - bit position.
fastThe quick-to-manipulate analog of least.
high_bitA least constant of the desired bit-masking - value.
high_bit_fastA fast analog of high_bit.
bit_positionThe value of the template parameter, in case its needed from - a renamed instantiation of the class template.
- -

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 -(2Bits - 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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Members of the boost::low_bits_mask_t Class - Template
MemberMeaning
leastThe smallest unsigned built-in type that supports the given - bit count.
fastThe quick-to-manipulate analog of least.
sig_bitsA least constant of the desired bit-masking - value.
sig_bits_fastA fast analog of sig_bits.
bit_countThe value of the template parameter, in case its needed from - a renamed instantiation of the class template.
- -

Implementation Note
-When Bits is the exact size of a built-in unsigned type, -the implementation has to change to prevent undefined behavior. -Therefore, there are specializations of low_bits_mask_t at -those bit counts.

- -

Example

- -
-#include <boost/integer/integer_mask.hpp>
-
-//...
-
-int main()
-{
-    typedef boost::high_bit_mask_t<29>  mask1_type;
-    typedef boost::low_bits_mask_t<15>  mask2_type;
-
-    mask1_type::least  my_var1;
-    mask2_type::fast   my_var2;
-    //...
-
-    my_var1 |= mask1_type::high_bit;
-    my_var2 &= mask2_type::sig_bits_fast;
-
-    //...
-}
-
- -

Demonstration Program

- -

The program integer_mask_test.cpp -is a simplistic demonstration of the results from instantiating various -examples of the bit mask class templates.

- -

Rationale

- -

The class templates in this header are an extension of the integer type selection class templates. The new -class templates provide the same sized types, but also convienent masks -to use when extracting the highest or all the significant bits when the -containing built-in type contains more bits. This prevents -contaimination of values by the higher, unused bits.

- -

Credits

- -

The author of the Boost bit mask class templates is Daryle Walker.

- -
- -

Revised September 23, 2001

- -

© Copyright Daryle Walker 2001. Use, modification, and distribution are -subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)

- - diff --git a/doc/static_log2.html b/doc/static_log2.html deleted file mode 100644 index b77874c..0000000 --- a/doc/static_log2.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - -Binary Logarithm Template - - - - - - - -

boost.png (6897 bytes)Binary Logarithm Template

- - -

The class template in <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.

- - - -

Contents

- - - - - - -

Synopsis

- - - -
-
-namespace boost
-{
-
-  typedef implementation-defined static_log2_argument_type;
-  typedef implementation-defined static_log2_result_type;
-
-  template < static_log2_argument_type arg >
-  struct static_log2
-  {
-    static const static_log2_result_type value = implementation-defined;
-  };
-
-
-  template < >
-  struct static_log2< 0 >
-  {
-    // The logarithm of zero is undefined.
-  };
-
-
-}  // namespace boost
-
-
- - - - -

Usage

- - - -

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.

- -

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 logarithm of zero results in a compile-time error.

- -

Note:

    - -
  • static_log2_argument_type is an unsigned integer - type (C++ standard, 3.9.1p3).
    • - -
  • static_log2_result_type is an integer type - (C++ standard, 3.9.1p7).
    • - -
- - - -

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>();
-    //...
-}
-
-
- - - -

Demonstration Program

- - - -

The program static_log2_test.cpp -is a simplistic demonstration of the results from instantiating various -examples of the binary logarithm class template.

- - - -

Rationale

- - - -

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.

- - - -

Changes from previous versions:

- - - -
    -
  • New in version 1.32.0:

    - -The argument type and the result type of boost::static_log2 -are now typedef'd. Formerly, they were hardcoded as unsigned long -and int respectively. Please, use the provided typedefs in new -code (and update old code as soon as possible). -
    • -
- - - -

Credits

- - - -

The original version of the Boost binary logarithm class template was -written by Daryle Walker -and then enhanced by Giovanni Bajo with support for compilers without -partial template specialization. The current version was suggested, -together with a reference implementation, by Vesa Karvonen. Gennaro Prota -wrote the actual source file. -

- -
- - - -

Revised July 19, 2004

- -

© Copyright Daryle Walker 2001.
- © Copyright Gennaro Prota 2004.

- - Distributed under the Boost Software License, Version 1.0. - (See accompanying file LICENSE_1_0.txt or copy at - - http://www.boost.org/LICENSE_1_0.txt) - -
- - - - - diff --git a/doc/static_min_max.html b/doc/static_min_max.html deleted file mode 100644 index 1beb503..0000000 --- a/doc/static_min_max.html +++ /dev/null @@ -1,120 +0,0 @@ - - - -Compile-Time Extrema Templates - - - -

boost.png (6897 bytes)Compile-Time Extrema -Templates

- -

The class templates in <boost/integer/static_min_max.hpp> -provide a compile-time evaluation of the minimum or maximum of -two integers. These facilities are useful for generic programming problems.

- -

Contents

- - - -

Synopsis

- -
-namespace boost
-{
-
-template < long Value1, long Value2 >
-    struct static_signed_min;
-
-template < long Value1, long Value2 >
-    struct static_signed_max;
-
-template < unsigned long Value1, unsigned long Value2 >
-    struct static_unsigned_min;
-
-template < unsigned long Value1, unsigned long Value2 >
-    struct static_unsigned_max;
-
-}
-
- -

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, -value, which is set to the respective minimum or maximum -of the template's parameters.

- -

Example

- -
-#include <boost/integer/static_min_max.hpp>
-
-template < unsigned long AddendSize1, unsigned long AddendSize2 >
-class adder
-{
-public:
-    static  unsigned long  const  addend1_size = AddendSize1;
-    static  unsigned long  const  addend2_size = AddendSize2;
-    static  unsigned long  const  sum_size = boost::static_unsigned_max<AddendSize1, AddendSize2>::value + 1;
-
-    typedef int  addend1_type[ addend1_size ];
-    typedef int  addend2_type[ addend2_size ];
-    typedef int  sum_type[ sum_size ];
-
-    void  operator ()( addend1_type const &a1, addend2_type const &a2, sum_type &s ) const;
-};
-
-//...
-
-int main()
-{
-    int const   a1[] = { 0, 4, 3 };  // 340
-    int const   a2[] = { 9, 8 };     //  89
-    int         s[ 4 ];
-    adder<3,2>  obj;
-
-    obj( a1, a2, s );  // 's' should be 429 or { 9, 2, 4, 0 }
-    //...
-}
-
- -

Demonstration Program

- -

The program static_min_max_test.cpp is a -simplistic demonstration of various comparisons using the compile-time -extrema class templates.

- -

Rationale

- -

Sometimes the minimum or maximum of several values needs to be found -for later compile-time processing, e.g. for a bound for another -class template.

- -

Credits

- -

The author of the Boost compile-time extrema class templates is Daryle Walker.

- -
- -

Revised October 12, 2001

- -

© Copyright Daryle Walker 2001. Use, modification, and distribution are -subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)

- - diff --git a/include/boost/integer.hpp b/include/boost/integer.hpp index 2d339ae..86cc3a5 100644 --- a/include/boost/integer.hpp +++ b/include/boost/integer.hpp @@ -17,7 +17,7 @@ #include // self include -#include // for ::boost::integer_traits +#include // for boost::::boost::integer_traits #include // for ::std::numeric_limits #include // for boost::int64_t and BOOST_NO_INTEGRAL_INT64_T diff --git a/include/boost/integer/static_log2.hpp b/include/boost/integer/static_log2.hpp index 219a48e..56c7a00 100644 --- a/include/boost/integer/static_log2.hpp +++ b/include/boost/integer/static_log2.hpp @@ -16,7 +16,7 @@ #ifndef BOOST_INTEGER_STATIC_LOG2_HPP #define BOOST_INTEGER_STATIC_LOG2_HPP -#include "boost/config.hpp" // for BOOST_STATIC_CONSTANT +#include "boost/integer_fwd.hpp" // for boost::intmax_t namespace boost { @@ -41,9 +41,8 @@ namespace boost { // terminates with x = 1 and n = 0 (see the algorithm's // invariant). - typedef unsigned long argument_type; - typedef int result_type; - + typedef boost::static_log2_argument_type argument_type; + typedef boost::static_log2_result_type result_type; template struct choose_initial_n { @@ -107,10 +106,6 @@ namespace boost { // static_log2 // ---------------------------------------- - typedef detail::static_log2_impl::argument_type static_log2_argument_type; - typedef detail::static_log2_impl::result_type static_log2_result_type; - - template struct static_log2 { diff --git a/include/boost/integer/static_min_max.hpp b/include/boost/integer/static_min_max.hpp index 2646037..ee76fd4 100644 --- a/include/boost/integer/static_min_max.hpp +++ b/include/boost/integer/static_min_max.hpp @@ -12,39 +12,35 @@ #include // self include -#include // for BOOST_STATIC_CONSTANT - - namespace boost { - // Compile-time extrema class declarations ---------------------------------// // Get the minimum or maximum of two values, signed or unsigned. -template < long Value1, long Value2 > +template struct static_signed_min { - BOOST_STATIC_CONSTANT( long, value = (Value1 > Value2) ? Value2 : Value1 ); + BOOST_STATIC_CONSTANT(static_min_max_signed_type, value = (Value1 > Value2) ? Value2 : Value1 ); }; -template < long Value1, long Value2 > +template struct static_signed_max { - BOOST_STATIC_CONSTANT( long, value = (Value1 < Value2) ? Value2 : Value1 ); + BOOST_STATIC_CONSTANT(static_min_max_signed_type, value = (Value1 < Value2) ? Value2 : Value1 ); }; -template < unsigned long Value1, unsigned long Value2 > +template struct static_unsigned_min { - BOOST_STATIC_CONSTANT( unsigned long, value + BOOST_STATIC_CONSTANT(static_min_max_unsigned_type, value = (Value1 > Value2) ? Value2 : Value1 ); }; -template < unsigned long Value1, unsigned long Value2 > +template struct static_unsigned_max { - BOOST_STATIC_CONSTANT( unsigned long, value + BOOST_STATIC_CONSTANT(static_min_max_unsigned_type, value = (Value1 < Value2) ? Value2 : Value1 ); }; diff --git a/include/boost/integer_fwd.hpp b/include/boost/integer_fwd.hpp index cd213b6..ab39561 100644 --- a/include/boost/integer_fwd.hpp +++ b/include/boost/integer_fwd.hpp @@ -14,11 +14,23 @@ #include // for BOOST_NO_INTRINSIC_WCHAR_T #include // for std::numeric_limits +#include // For intmax_t namespace boost { +#ifdef BOOST_NO_INTEGRAL_INT64_T + typedef unsigned long static_log2_argument_type; + typedef int static_log2_result_type; + typedef long static_min_max_signed_type; + typedef unsigned long static_min_max_unsigned_type; +#else + typedef boost::uintmax_t static_min_max_unsigned_type; + typedef boost::intmax_t static_min_max_signed_type; + typedef boost::uintmax_t static_log2_argument_type; + typedef int static_log2_result_type; +#endif // From ------------------------------------------------// @@ -136,28 +148,26 @@ template < > // From ------------------------------------// -template < unsigned long Value > +template struct static_log2; -template < > - struct static_log2< 0ul >; +template <> struct static_log2<0u>; // From ---------------------------------// -template < long Value1, long Value2 > +template struct static_signed_min; -template < long Value1, long Value2 > +template struct static_signed_max; -template < unsigned long Value1, unsigned long Value2 > +template struct static_unsigned_min; -template < unsigned long Value1, unsigned long Value2 > +template struct static_unsigned_max; - } // namespace boost diff --git a/index.html b/index.html index 6aa0bb8..dfc23cc 100644 --- a/index.html +++ b/index.html @@ -1,148 +1,16 @@ - -Boost Integer Library + - - - - - - - - - - - -
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
- -

Boost Integer Library

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Header / DocsContentsUse
<boost/integer_fwd.hpp>Forward declarations of classes and class templatesWhen just the name of a class is needed
<boost/cstdint.hpp>
-
- documentation - 		Typedef's based on the 1999 C Standard header <stdint.h>, wrapped in namespace boost. - This implementation may #include the compiler - supplied <stdint.h>, if present. Supplies typedefs for standard integer types such as int32_t or uint_least16_t. - Use in preference to <stdint.h> - for enhanced portability. Furthermore, all names are safely placed in the boost namespace.
<boost/integer_traits.hpp>
-
- documentation - 		Template class boost::integer_traits, derived from std::numeric_limits.  - Adds const_min and const_max members.Use to obtain the characteristics of a known integer type.
<boost/integer.hpp>
-
- documentation		Templates for integer type selection based on properties such as - maximum value or number of bits.Use to select the type an integer when some property such as maximum value or number of bits is known. - Useful for generic programming.
<boost/integer/integer_mask.hpp>
-
- documentation		Templates for the selection of integer masks, single or lowest group, based on the number of bits.Use to select a particular mask when the bit position(s) are based on a compile-time variable. - Useful for generic programming.
<boost/integer/static_log2.hpp>
-
- documentation		Template for finding the highest power of two in a number.Use to find the bit-size/range based on a maximum value. - Useful for generic programming.
<boost/integer/static_min_max.hpp>
-
- documentation		Templates for finding the extrema of two numbers.Use to find a bound based on a minimum or maximum value. - Useful for generic programming.
- -

Rationale

- -

The organization of 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. 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 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.

- -

Caveat emptor

- -

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.

- -

- History -

- -

- Reverted Trunk to release branch state (i.e. a "known good state"), Nov 2009. Then fixed issues: - 653, - 3084, - 3177, - 3180, - 3568, - 3657, - 2134, -

- -
- -

Revised: 06 Nov 2007 -

- -

© Copyright Beman Dawes 2003

- -

Distributed under the Boost Software License, Version 1.0. See -www.boost.org/LICENSE_1_0.txt

- + +Automatic redirection failed, please go to +doc/html/index.html. +

Copyright Beman Dawes, Daryle Walker, Gennaro Prota and John Maddock 2001-2009

+

Distributed under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt).

- \ No newline at end of file + + + + + diff --git a/integer.htm b/integer.htm deleted file mode 100644 index 68767b4..0000000 --- a/integer.htm +++ /dev/null @@ -1,212 +0,0 @@ - - - -Integer Type Selection Templates - - - -

-boost.png (6897 bytes)Integer Type Selection -Templates

- -

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.

- -

Contents

- - - -

Synopsis

- -
namespace boost
-{
-  //  fast integers from least integers
-  template< typename LeastInt >
-  struct int_fast_t
-  {
-      typedef implementation_supplied  fast;
-  };
-
-  //  signed
-  template< int Bits >
-  struct int_t 
-  {
-      typedef implementation_supplied  least;
-      typedef int_fast_t<least>::fast  fast;
-  };
-
-  //  unsigned
-  template< int Bits >
-  struct uint_t 
-  {
-      typedef implementation_supplied  least;
-      typedef int_fast_t<least>::fast  fast;
-  };
-
-  //  signed
-  template< long long MaxValue >
-  struct int_max_value_t 
-  {
-      typedef implementation_supplied  least;
-      typedef int_fast_t<least>::fast  fast;
-  };
-
-  template< long long MinValue >
-  struct int_min_value_t 
-  {
-      typedef implementation_supplied  least;
-      typedef int_fast_t<least>::fast  fast;
-  };
-
-  //  unsigned
-  template< unsigned long long Value >
-  struct uint_value_t 
-  {
-      typedef implementation_supplied  least;
-      typedef int_fast_t<least>::fast  fast;
-  };
-} // namespace boost
-
- -

Easiest-to-Manipulate Types

- -

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, despite the name. -The output type is given as the class member 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 built-in types. Also, there is no guarantee that -the output type actually is easier to manipulate than the input -type.

- -

Sized Types

- -

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. -The following table describes each template's criteria.

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Criteria for the Sized Type Class Templates
Class TemplateTemplate Parameter Mapping
boost::int_tThe smallest built-in signed integral type with at least the - given number of 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 a - long.
boost::uint_tThe smallest built-in unsigned integral type with at least - the given number of bits. The parameter should be a positive - number. A compile-time error results if the parameter is - larger than the number of bits in an unsigned - long.
boost::int_max_value_tThe smallest built-in signed integral type that supports the - given value as a maximum. The parameter should be a - positive number.
boost::int_min_value_tThe smallest built-in signed integral type that supports the - given value as a minimum. The parameter should be a - negative number.
boost::uint_value_tThe smallest built-in unsigned integral type that supports - the given value as a maximum. The parameter should be a - positive number.
- -

Example

- -
#include <boost/integer.hpp>
-
-//...
-
-int main()
-{
-    boost::int_t<24>::least my_var;
-    //...
-}
-
- -

Demonstration Program

- -

The program integer_test.cpp is a -simplistic demonstration of the results from instantiating various -examples of the sized type class templates.

- -

Rationale

- -

The rationale for the design of the templates in this header includes:

- -
    -
  • Avoid recursion because of concern about C++'s limited - guaranteed recursion depth (17).
    • -
  • Avoid macros on general principles.
    • -
  • Try to keep the design as simple as possible.
    • -
- -

Alternative

- -

If the number of bits required is known beforehand, it may be more -appropriate to use the types supplied in <boost/cstdint.hpp>.

- -

Credits

- -

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.

- -
- -

Revised May 20, 2001

- -

© Copyright Beman Dawes 1999. Use, modification, and distribution are -subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or a copy at <http://www.boost.org/LICENSE_1_0.txt>.)

- - diff --git a/integer_traits.html b/integer_traits.html deleted file mode 100644 index 6fc75b8..0000000 --- a/integer_traits.html +++ /dev/null @@ -1,94 +0,0 @@ - - - - - -integer_traits: Compile-Time Limits for Integral Types - - - - -

boost.png (6897 bytes)Compile-Time Integral -Type Limits

- -

-The C++ Standard Library <limits> header supplies a class template -numeric_limits<> with specializations for each fundamental -type.

-

-For integer types, the interesting members of std::numeric_limits<> are: -

   static const bool is_specialized; // will be true for integers
-   static T min() throw();
-   static T max() throw();
-   static const int digits;     // for integers, # value bits
-   static const int digits10;     
-   static const bool is_signed;
-   static const bool is_integer; // will be true for integers
-For many uses, these are sufficient. But min() and max() are problematical because they are not constant expressions -(std::5.19), yet some usages require constant expressions. -

-The template class integer_traits addresses this -problem. - - -

Header integer_traits.hpp Synopsis

- -
namespace boost {
-  template<class T>
-  class integer_traits : public std::numeric_limits<T>
-  {
-    static const bool is_integral = false;
-  };
-
-  // specializations for all integral types
-}
- - -

Description

- -Template class integer_traits is derived from -std::numeric_limits. In general, it 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: -

- - - - - -
membertypevalue
is_integralbooltrue
const_minTequivalent -to std::numeric_limits<T>::min()
const_maxTequivalent -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. - -

- -Test Program

- -

- -The program integer_traits_test.cpp -exercises the integer_traits class. - -

Acknowledgements

- -Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers discussed the integer -traits idea on the boost mailing list in August 1999. -
-

Revised -06 November 2007

-

© Copyright Beman Dawes 2000

- -

Distributed under the Boost Software License, Version 1.0. See -www.boost.org/LICENSE_1_0.txt

-