diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 92609ff..fc75505 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -1,12 +1,88 @@ - +# jamfile to build Boost.Integer Documentation. # 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 ; +# revised to include Doxygen and Autoindex +# Copyright Paul A. Bristow 2015 + +using boostbook ; +using doxygen ; # Required if you want to use Doxygen. +using quickbook ; +using auto-index ; + +path-constant here : . ; # convenient to refer to files in the same directory as this jamfile.v2 +path-constant parent : .. ; # Parent directory, /libs/integer/ + +if --enable-index in [ modules.peek : ARGV ] +{ + ECHO "Building the Integer docs with automatic index generation enabled." ; + using auto-index ; + project integer_doc : requirements + on + integer.idx + . + on + html:on + html:generate.index=0 + pdf:on + pdf:index.on.type=1 + enable_index ; +} +else +{ + project integer_doc ; + ECHO "Building the Integer docs with automatic index generation disabled. Try building with --enable-index." ; +} + + +xml integer + : + integer.qbk # This is 'root' Quickbook file (that may include other .qbk files). + ; + +doxygen autodoc + : + [ glob $(here)/../include/boost/*.hpp ] + [ glob $(here)/../include/boost/integer/integer/*.hpp ] + # but could also include this and switch Boost.Integer C++ reference info to include implementation details (or not) using Doxygen macro DETAIL. + # See http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdcond + # and http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_enabled_sections + # by adding this line below with other Doxygen parameters + # ENABLED_SECTIONS="DETAIL" + # Or setting this macro value ENABLED_SECTIONS="DETAIL" in /doxygen/integer_doxyfile.txt for Standalone Doxygen documentaation. + # This might be useful for maintainers. + + : + PROJECT_NAME="Integer" + RECURSIVE=NO # Specify all folders and files above explicitly. + ENABLE_PREPROCESSING=YES + EXPAND_ONLY_PREDEF=YES + EXTRACT_ALL=NO + EXTRACT_PRIVATE=NO + HIDE_UNDOC_MEMBERS=YES + MACRO_EXPANSION=YES + SORT_MEMBER_DOCS=NO + SHOW_INCLUDE_FILES=NO + MAX_INITIALIZER_LINES=0 + VERBATIM_HEADERS=NO + WARNINGS=NO # If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings for undocumented members. + # If EXTRACT_ALL is set to YES then this flag will automatically be disabled. + WARN_IF_UNDOCUMENTED=YES # If WARN_IF_UNDOCUMENTED is set to YES, + # then doxygen will generate warnings for all undocumented members. + WARN_IF_DOC_ERROR=YES # If WARN_IF_DOC_ERROR is set to YES, Doxygen will generate warnings for + # potential errors in the documentation. + WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen. + # Much better to send message to a logfile than the default stderr. + # and make sure that there are no Doxygen errors or significant warnings in the log file. + + #"Reference" # Default is "Reference" but helpful to specify library. + "boost.doxygen.reftitle=Boost.Integer C++ Reference" + # See Doxygen configuration for detailed explanation of these options. + # Usually these match those in /doc/doxygen/integer_doxyfile.txt. + ; -xml integer : integer.qbk ; boostbook standalone : integer @@ -14,6 +90,7 @@ boostbook standalone # HTML options first: # Use graphics not text for navigation: navig.graphics=1 + chapter.autolabel=0 # No Chapter numbering. # 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: @@ -26,7 +103,7 @@ boostbook standalone generate.section.toc.level=4 # Path for links to Boost: boost.root=../../../.. - + # PDF Options: # TOC Generation: this is needed for FOP-0.9 and later: fop1.extensions=0 @@ -47,7 +124,11 @@ boostbook standalone # 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 + #pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/regex/doc/html + # Not sure if this line is correct? + + autodoc # Add Doxygen info. + ; install pdfinstall : standalone/pdf : . PDF ; diff --git a/doc/integer.qbk b/doc/integer.qbk index 6beb0f4..334b84e 100644 --- a/doc/integer.qbk +++ b/doc/integer.qbk @@ -1,8 +1,8 @@ [article Boost.Integer [quickbook 1.6] - [compatibility-mode 1.5] - [copyright 2001-2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock] - [purpose Integer Type Selection] + [/compatibility-mode 1.5] + [copyright 2001-2015 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 @@ -10,20 +10,73 @@ ] [authors [Dawes, Beman], [Walker, Daryle], [Prota, Gennaro], [Maddock, John]] [/last-revision $Date: 2008-02-21 12:58:15 +0000 (Thu, 21 Feb 2008) $] + [/last-revision $Date] ] +[/ Required for autoindexing] +[import ../../../tools/auto_index/include/auto_index_helpers.qbk] +[/ Must be first included file!] + +[import html4_symbols.qbk] [/ Provides various useful squiggles.] + +[/ Some composite templates] [template super[x]''''''[x]''''''] +[template sub[x]''''''[x]''''''] +[template floor[x]'''⌊'''[x]'''⌋'''] +[template floorlr[x][lfloor][x][rfloor]] +[template ceil[x] '''⌈'''[x]'''⌉'''] + +[/Web links] +[def __numeric_limits [@http://www.cplusplus.com/reference/limits/numeric_limits/ std::numeric_limits]] +[def __LCM [@http://en.wikipedia.org/wiki/Least_common_multiple LCM]] +[def __GCD [@http://en.wikipedia.org/wiki/Greatest_common_divisor GCD]] +[def __positive_number [@http://simple.wikipedia.org/wiki/Positive_number positive number]] +[def __negative_number [@http://simple.wikipedia.org/wiki/Negative_number negative number]] + +[/ Links to functions for use in text] +[def __integer_log2 [^[classref boost::static_log2 static_log2]]] +[def __integer_traits[^[classref boost::integer_traits integer_traits]]] +[def __boost_integer_static_gcd [^[funcref boost::integer::static_gcd boost::integer::static_gcd]]] + +[/links to this Boost.Integer library] +[/link document_id.section_id.normalized_header_text The link text] +[def __overview [link boost_integer.overview overview]] +[def __log2 [link boost_integer.log2 log2]] +[def __log2_usage [link boost_integer.log2.usage static_log2]] +[def __cpp_reference [link boost_integer. boost_integer_c___reference C++ Reference]] + +[/LInks to other Boost libraries] +[def __Boost.Multiprecision [@boost:/libs/multiprecision/index.html Boost.Multiprecision]] +[def __Boost.Config [@boost:/libs/config/index.html Boost.Config]] [section:overview Overview] -Boost.Integer provides integer type support, particularly helpful in generic programming. -It provides the means to select an integer type based upon its properties, like the number of bits or -the maximum supported value, as well as compile-time bit mask selection. There is a derivative of -std::numeric_limits that provides integral constant expressions for `min` and `max`. -Finally, it provides two compile-time algorithms: determining the highest power of two in a -compile-time value; and computing min and max of constant expressions. +__Boost.Multiprecision +__Boost.Config +__overview +__log2 +__log2_usage +__cpp_reference +__boost_integer_static_gcd -[table +Boost.Integer provides integer type support, particularly helpful in generic programming. +It provides + +* The means to select an integer type based upon its properties, like the number of bits or +the maximum supported value, as well as compile-time bit mask selection. +* A derivative of __numeric_limits that provides integral [*constant expressions] for `min` and `max`. + +It provides two compile-time algorithms + +* Determining the highest power of two in a compile-time value. +* Computing min and max of constant expressions. + +It now includes (moved from Boost.Math) + +* Run-time and compile-time evaluation of the greatest common divisor (__GCD) +or least common multiple (__LCM) of two integers. + +[table [[Component][Header][Purpose]] [ [Forward Declarations.] @@ -38,119 +91,143 @@ compile-time value; and computing min and max of constant expressions. [ [[link boost_integer.integer 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. + [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: + [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: + [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: + [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] + [ + [[link boost_integer.gcd_lcm GCM & LCM calculation].] + [[^[@../../../../boost/integer/common_factor.hpp ]]] + [Templates for finding the GCM or LCM: Useful for generic programming. ] + ] +] +[endsect] [/section:overview Overview] [section:traits Integer Traits] [section Motivation] -The C++ Standard Library header supplies a class template `numeric_limits<>` with specializations for each fundamental type. +The C++ Standard Library __numeric_limits in header `` supplies a class template `std::numeric_limits<>` +with specializations for each fundamental type. -For integer types, the interesting members of `std::numeric_limits<>` are: +For integer types, the interesting members of __numeric_limits for integer-types (until C++11) are: - static const bool is_specialized; // Will be true for integer types. + static const bool is_specialized; // True for all fundamental integer types, and may be for other 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. + static const bool is_integer; // 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. +For many uses, these are sufficient. +But functions `min()` and `max()` may be problematical because they are not ['constant expressions] (std::5.19), +yet some usages require constant expressions. -The template class [^integer_traits] addresses this problem. +The template class __integer_traits addresses this problem. -[endsect] +[tip Since C++11, `min()` and `max()` (like other members) are `static constexpr T max();`, and `static constexpr T min();` +so there is no issue if the code is only to be run with compilers that support this definition.] + +[endsect] [/section Motivation] [section Synopsis] - namespace boost { + namespace boost + { template class integer_traits : public std::numeric_limits { public: 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]``; + + // These members are defined only if T is a built-in integal type : + static const T const_min = ``['implementation-defined]``; // Usually all available `char, int` and `long` types. + static const T const_max = ``['implementation-defined]``; // Usually all available `char, int` and `long` types . }; } -[endsect] +[endsect] [/section Synopsis] [section Description] -Template class [^integer_traits] is derived from [^std::numeric_limits]. The primary specialization adds the single -[^bool] member [^is_integral] with the compile-time constant value [^false]. -However, for all integral types [^T] (std::3.9.1/7 [basic.fundamental]), there are specializations -provided with the following compile-time constants defined: +Template class __integer_traits is derived from __std::numeric_limits. +The primary specialization adds the single +`bool` member [^is_integral] with the compile-time constant value `false`. +However, for all integral types [^T] (std::3.9.1/7 [basic.fundamental]), +there are specializations provided with the following compile-time constants defined: -[table +[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: The /is_integral/ flag is provided, because a user-defined integer class should specialize -[^std::numeric_limits<>::is_integer = true], while compile-time constants -[^const_min] and [^const_max] are not provided for that user-defined class, unless boost::integer_traits is also specialized. +[note The ['is_integral] flag is provided, because a user-defined integer class should specialize +[^std::numeric_limits<>::is_integer = true], while compile-time constants +[^const_min] and [^const_max] are [*not] provided for that user-defined class, +unless `boost::integer_traits` is also specialized.] -[endsect] +[endsect] [/section Description] + +[import ../example/integer_traits_example.cpp] +[section Example] +A templated function like + +[integer_traits_example_1] +can be called using a literal integral value thus +[integer_traits_example_2] +but not using a non-const variable +[integer_traits_example_3] +only a const variable +[integer_traits_example_4] +`std::numeric_limits<>::max()` and `min()` are sadly non-`const` so cannot be used by pre-C++11 compilers. +[integer_traits_example_5] +but fortunately `const_max` and `const_min` are `const` and so can be used thus +[integer_traits_example_6] + +See example code at [@../../example/integer_traits_example.cpp]. +[endsect] [/section example] [section Test Program] -The program [^[@../../test/integer_traits_test.cpp integer_traits_test.cpp]] exercises the [^integer_traits] class. +The program [^[@../../test/integer_traits_test.cpp integer_traits_test.cpp]] exercises the __integer_traits class. -[endsect] +[endsect] [/section Test Program] -[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] +[endsect] [/section:traits Integer Traits] [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. +The type-selection templates in header [@../../../../boost/integer.hpp ] 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 + // fast integers from least integers. template struct int_fast_t { @@ -159,34 +236,34 @@ This facility is particularly useful for solving generic programming problems. // signed template - struct int_t + struct int_t { - /* Member exact may or may not be defined depending upon Bits */ - typedef ``['implementation-defined-type]`` exact; typedef ``['implementation-defined-type]`` least; typedef int_fast_t::fast fast; + /* Member exact may or may not be defined depending upon Bits */ + typedef ``['implementation-defined-type]`` exact; }; // unsigned template - struct uint_t + struct uint_t { - /* Member exact may or may not be defined depending upon Bits */ - typedef ``['implementation-defined-type]`` exact; typedef ``['implementation-defined-type]`` least; typedef int_fast_t::fast fast; + /* Member exact may or may not be defined depending upon Bits */ + typedef ``['implementation-defined-type]`` exact; }; // signed template - struct int_max_value_t + struct int_max_value_t { typedef ``['implementation-defined-type]`` least; typedef int_fast_t::fast fast; }; template - struct int_min_value_t + struct int_min_value_t { typedef ``['implementation-defined-type]`` least; typedef int_fast_t::fast fast; @@ -194,36 +271,37 @@ This facility is particularly useful for solving generic programming problems. // unsigned template - struct uint_value_t + struct uint_value_t { typedef ``['implementation-defined-type]`` least; typedef int_fast_t::fast fast; }; } // namespace boost -[endsect] +[endsect] [/section:synopsis Synopsis] [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. -The output type is given as the nested type [^fast]. +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. +The output type is given as the nested type `fast`. -[*Implementation Notes:] -By default, the output type is identical to the input type. Eventually, this code's implementation should -be customized for each platform to give accurate mappings between the built-in types and the easiest-to-manipulate -built-in types. Also, there is no guarantee that the output type actually is easier to manipulate than the input type. +[note By default, the output type is identical to the input type. Eventually, this implementation should +be customized for each platform to give accurate mappings between the built-in types and the easiest-to-manipulate +built-in types. ] -[endsect] +[tip There is no guarantee that the output type actually is easier or faster to manipulate than the input type.] + +[endsect] [/section:easiest Easiest-to-Manipulate Types] [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 -nested type [^least]. The easiest-to-manipulate version of that type is given by the nested type [^fast]. +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 +nested type [^least]. The easiest-to-manipulate version of that type is given by the nested type [^fast]. The following table describes each template's criteria. [table Criteria for the Sized Type Class Templates @@ -232,103 +310,148 @@ The following table describes each template's criteria. ] [ [[^boost::int_t::least]] - [The smallest, built-in, signed integral type with at least /N/ bits, including the sign bit. - The parameter should be a positive number. A compile-time error results if the parameter is + [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::int_t::fast]] - [The easiest-to-manipulate, built-in, signed integral type with at least /N/ bits, including the sign bit. - The parameter should be a positive number. A compile-time error results if the parameter is + [The easiest-to-manipulate, built-in, signed integral type with at least ['N] bits, including the sign bit. + The parameter should be a __positive_number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type.] ] [ [[^boost::int_t::exact]] - [A built-in, signed integral type with exactly /N/ bits, including the sign bit. - The parameter should be a positive number. Note that the member /exact/ is defined - [*only] if there exists a type with exactly /N/ bits.] + [A built-in, signed integral type with exactly ['N] bits, including the sign bit. + The parameter should be a __positive_number. Note that the member ['exact] is defined + [*only] if there exists a type with exactly ['N] bits.] ] [ [[^boost::uint_t::least]] - [The smallest, built-in, unsigned integral type with at least /N/ bits. - The parameter should be a positive number. A compile-time error results if the + [The smallest, built-in, unsigned integral type with at least ['N] bits. + The parameter should be a __positive_number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type.] ] [ [[^boost::uint_t::fast]] - [The easiest-to-manipulate, built-in, unsigned integral type with at least /N/ bits. - The parameter should be a positive number. A compile-time error results if the + [The easiest-to-manipulate, built-in, unsigned integral type with at least ['N] bits. + The parameter should be a __positive_number. A compile-time error results if the parameter is larger than the number of bits in the largest integer type.] ] [ [[^boost::uint_t::exact]] - [A built-in, unsigned integral type with exactly /N/ bits. - The parameter should be a positive number. A compile-time error results if the - parameter is larger than the number of bits in the largest integer type. - Note that the member /exact/ is defined + [A built-in, unsigned integral type with exactly ['N] bits. + The parameter should be a __positive_number. A compile-time error results if the + parameter is larger than the number of bits in the largest integer type. + Note that the member [exact] is defined [*only] if there exists a type with exactly N bits.] ] [ [[^boost::int_max_value_t::last]] - [The smallest, built-in, signed integral type that can hold all the values in the inclusive range ['0 - V]. - The parameter should be a positive number.] + [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_max_value_t::fast]] - [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['0 - V]. - The parameter should be a positive number.] + [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['0 - V]. + The parameter should be a __positive_number.] ] [ [[^boost::int_min_value_t::least]] - [The smallest, built-in, signed integral type that can hold all the values in the inclusive range ['V - 0]. - The parameter should be a negative number.] + [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::int_min_value_t::fast]] - [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['V - 0]. - The parameter should be a negative number.] + [The easiest-to-manipulate, built-in, signed integral type that can hold all the values in the inclusive range ['V - 0]. + The parameter should be a __negative_number.] ] [ [[^boost::uint_value_t::least]] [The smallest, built-in, unsigned integral type that can hold all positive values - up to and including /V/. The parameter should be a positive number.] + up to and including ['V]. The parameter should be a __positive_number.] ] [ [[^boost::uint_value_t::fast]] [The easiest-to-manipulate, built-in, unsigned integral type that can hold all positive values - up to and including /V/. The parameter should be a positive number.] + up to and including ['V]. The parameter should be a __positive_number.] ] -] +] [/table Criteria for the Sized Type Class Templates] -[endsect] +[endsect] [/:sized Sized Types] [section Example] +[import ../example/integer_type_selection_example.cpp] + +First we need the right include + #include - //... +If, perhaps dementedly, we declare that we want an unsigned and integer type with at least 13 bits, +[integer_type_selection_1] - 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, its size may be greater than - // that of my1000: - boost::int_max_value_t<1000>::fast my_fast1000 = 1000; - } +After some effort defining a pretty-printing function `show_type`, -[endsect] +[integer_type_selection_2] -[section Demonstration Program] +we can prettily show the `std::numeric_limits` of the resulting type -The program [@../../test/integer_test.cpp integer_test.cpp] is a simplistic demonstration of the results from instantiating +[integer_type_selection_output_1] + +It may be convenient to define a `typedef` for the resulting type, for example, +to get the easiest (and hopefully fastest) 7-bit signed int + +[integer_type_selection_3] + +and display the type information using + +[integer_type_selection_4] + +[integer_type_selection_output_2] + +(This type might not prove to be the fastest - a simple `int` ['might] prove faster?). + +We could also choose an integer type by specifying the decimal ['size] that the type must contain, for example: + +Choose an integer size that can hold ['at least a value] of 1000000. +Assignment of the value 1000000 is guaranteed not to be truncated: + +[integer_value_type_selection_5] + +We can see how big a value could be stored for this type thus + +[integer_value_type_selection_6] + +which is probably 2147483647 which is actually much larger than the requirement of only 1000000. + +If we try to initialise or assign a ['value] that proves too big for the type, the compiler will warn thus: + +[integer_value_type_selection_7] + +To define a type with an exact number of bits, say 32 + +[integer_value_type_selection_8] + +If we ask for an unachievable (on a particular platform) number of bits, for example: + + boost::int_t<128>::exact exact128; + +Then the result is a compile-fail with message, for example: + + error C2338 : No suitable signed integer type with the requested number of bits is available. + see reference to class template instantiation 'boost::int_t<128>' being compiled. + +See full example code at [@../../example/integer_type_selection_example.cpp]. + +[endsect] [/section Example] + +[section Test Program] + +The program [@../../test/integer_test.cpp integer_test.cpp] is a test of the results from instantiating various examples of the sized type class templates. -[endsect] +[endsect] [/section Demonstration Program] [section Rationale] @@ -338,35 +461,30 @@ The rationale for the design of the templates in this header includes: * Avoid macros on general principles. * Try to keep the design as simple as possible. -[endsect] +[endsect ] [/section Rationale] [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 ]. +[tip If the number of bits required is known beforehand, it may be more appropriate to use the (exact) types supplied +in [@../../../../boost/cstdint.hpp ], for example: `int_least8_t`, `uint_fast16_t`, `uint64_t`]. + +[tip The __Boost.Multiprecision library provides +[@boost:/libs/multiprecision/doc/html/boost_multiprecision/tut/ints/cpp_int.html cpp_int] +that enables fixed precision integers via `typedef`s like `int128_t`, `uint512_t`, +and checked versions like `checked_int128_t`, that may also be useful.] + +[endsect] [/section Alternative] [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:masks Integer Masks] +[import ../example/integer_mask_example.cpp] [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. +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] @@ -405,14 +523,14 @@ The types of the masking constants come from the [link boost_integer.integer int } // namespace boost -[endsect] +[endsect] [/section Synopsis] [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 [^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 @@ -421,17 +539,17 @@ the members of an instantiation of [^high_bit_mask_t]. [[[^fast]][The easiest-to-manipulate analog of [^least].]] [[[^high_bit]][A [^least] constant of the value 2[super Bit].]] [[[^high_bit_fast]][A [^fast] analog of [^high_bit].]] - [[[^bit_position]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]] + [[[^bit_position]][The value of the template parameter, in case it is needed from a renamed instantiation of the class template.]] ] -[endsect] +[endsect] [/section Single Bit-Mask Class Template] [section Group Bit-Mask Class Template] -The [^boost::low_bits_mask_t] class template provides constants for bit masks -equivalent to the value (2[super Bits] - 1), where [^Bits] is the template parameter. -The parameter [^Bits] must be a non-negative integer from -zero to ['Max], where Max is the number of bits supported by the largest, unsigned, built-in integral type. +The [^boost::low_bits_mask_t] class template provides constants for bit masks +equivalent to the value (2[super Bits] - 1), where [^Bits] is the template parameter. +The parameter [^Bits] must be a non-negative integer from +zero to ['Max], where Max is the number of bits supported by the largest, unsigned, built-in integral type. The following table describes the members of [^low_bits_mask_t]. [table Members of the [^boost::low_bits_mask_t] Class Template @@ -443,71 +561,67 @@ The following table describes the members of [^low_bits_mask_t]. [[[^bit_count]][The value of the template parameter, in case its needed from a renamed instantiation of the class template.]] ] -[endsect] +[endsect] [/section Group Bit-Mask Class Template] [section Implementation Notes] -When [^Bits] is the exact size of a built-in unsigned type, the implementation has to change to +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] +[endsect] [/section Implementation Notes] -[section Example] +[section Examples] - #include +This include is need: +[integer_mask_example_0] - //... +Then it is convenient to define some `typedef`s for a couple of arbitrary masks: +[integer_mask_example_1] - int main() - { - typedef boost::high_bit_mask_t<29> mask1_type; - typedef boost::low_bits_mask_t<15> mask2_type; +and we can display some of their features: +[integer_mask_example_2] - mask1_type::least my_var1; - mask2_type::fast my_var2; - //... +and instantiate a couple of variable using them, one of type `fast` and the other at `least` +[integer_mask_example_3] - my_var1 |= mask1_type::high_bit; - my_var2 &= mask2_type::sig_bits_fast; +We can then pick out just the high or most significant bit, - //... - } +[integer_mask_example_4] +or picking the significant bits -[endsect] +[integer_mask_example_5] -[section Demonstration Program] +Output is [integer_mask_example_output]. +[endsect] [/section Example] -The program [@../../test/integer_mask_test.cpp integer_mask_test.cpp] is a simplistic demonstration of the +[section Test Program] + +The program [@../../test/integer_mask_test.cpp integer_mask_test.cpp] is a demonstration of the results from instantiating various examples of the bit mask class templates. -[endsect] +[endsect] [/section Test Program] [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 convenient masks to use when extracting the -highest or all the significant bits when the containing built-in type contains more bits. +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 convenient masks to use when extracting the +highest or all the significant bits when the containing built-in type contains more bits. This prevents contamination of values by the higher, unused bits. -[endsect] +[endsect] [/section Rationale] -[section Credits] +[endsect] [/section Group Bit-Mask Class Template] -The author of the Boost bit mask class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. +[section:log2 Compile-Time log2 Calculation] -[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. +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; @@ -517,73 +631,66 @@ determines the position of the highest bit in a given value. This facility is us static const static_log2_result_type value = ``['implementation-defined]``; }; - template < > struct static_log2< 0 > - { - // The logarithm of zero is undefined. + { // The logarithm of zero is undefined. }; - - } // namespace boost +[endsect] [/section Synopsis] -[endsect] +[import ../example/integer_log2_example.cpp] [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 +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 +For example: +[integer_log2_example_1] +gives the result +[integer_log2_example_output] + +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: +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] +[endsect] [/section Usage] -[section Demonstration Program] +[section Test 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. +The program [@../../test/static_log2_test.cpp static_log2_test.cpp] is a demonstration +of the results from instantiating various examples of the binary logarithm class template. -[endsect] +[endsect] [/section Demonstration Program] [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 +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 available statically (['i.e.] at compile-time). -[endsect] +[endsect] [/section Rationale] -[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] +[endsect] [/section:log2 Compile Time log2 Calculation] [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 +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; @@ -598,21 +705,42 @@ for generic programming problems. template struct static_unsigned_max; - } - -[endsect] +[endsect] [/section Synopsis] [section Usage] -The four class templates provide the combinations for finding the minimum or maximum of two [^signed] or -[^unsigned] ([^long]) parameters, /Value1/ and /Value2/, at compile-time. Each template has a single static data member, +The four class templates provide the combinations for finding the minimum or maximum of two [^signed] or +[^unsigned] ([^long]) parameters, /Value1/ and /Value2/, at compile-time. Each template has a single static data member, [^value], which is set to the respective minimum or maximum of the template's parameters. -[endsect] +[endsect] [/section Usage] + [section Example] +[import ../example/integer_static_minmax_example.cpp] + +The full code is [@../../test/integer_static_minmax_example.cpp integer_static_minmax_example.cpp]. + +Simple examples of finding the minimum and maximum values are + + +[integer_min_max_example_1] + +A more complex example showing static compiler-time computation of the biggest size of two arrays, plus 1, using a class adder. + +[integer_min_max_example_0] + +The computed size is 3+1 = 4 + +[integer_min_max_example_2] + + +TODO the rest of the example compiles but does not run. + +Original was: + #include template < unsigned long AddendSize1, unsigned long AddendSize2 > @@ -643,64 +771,351 @@ The four class templates provide the combinations for finding the minimum or max //... } -[endsect] +[endsect] [/section Example] -[section Demonstration Program] +[section Test Program] -The program [@../../test/static_min_max_test.cpp static_min_max_test.cpp] is a simplistic demonstration of +The program [@../../test/static_min_max_test.cpp static_min_max_test.cpp] is a test of various comparisons using the compile-time extrema class templates. -[endsect] +[endsect] [/section Demonstration Program] [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. +Sometimes the minimum or maximum of several values needs to be found for later compile-time processing, +['e.g.] as a bound for another class template. -[endsect] +[endsect] [/section Rationale] +[endsect] [/section:minmax Compile time min/max calculation] + +[section:gcd_lcm Greatest Common Divisor and Least Common Multiple Integer Utilities] + +[section Introduction] + +The class and function templates in `` +provide run-time and compile-time evaluation of the greatest common divisor +(__GCD) or least common multiple (__LCM) of two integers. +These facilities are useful for many numeric-oriented generic programming problems. + +[endsect] [/section Introduction] + +[section Synopsis] + + namespace boost + { + namespace math + { + + template < typename IntegerType > + class gcd_evaluator; + template < typename IntegerType > + class lcm_evaluator; + + template < typename IntegerType > + IntegerType gcd( IntegerType const &a, IntegerType const &b ); + template < typename IntegerType > + IntegerType lcm( IntegerType const &a, IntegerType const &b ); + + typedef ``['see-below]`` static_gcd_type; + + template < static_gcd_type Value1, static_gcd_type Value2 > + struct static_gcd; + template < static_gcd_type Value1, static_gcd_type Value2 > + struct static_lcm; + + } // namespace math + } // namespace boost + +[endsect] [/section Synopsis] + +[section GCD Function Object] + +[*Header: ] [@../../../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + class boost::math::gcd_evaluator + { + public: + // Types + typedef IntegerType result_type; + typedef IntegerType first_argument_type; + typedef IntegerType second_argument_type; + + // Function object interface + result_type operator ()( first_argument_type const &a, + second_argument_type const &b ) const; + }; + +The boost::math::gcd_evaluator class template defines a function object +class to return the greatest common divisor of two integers. +The template is parameterized by a single type, called IntegerType here. +This type should be a numeric type that represents integers. +The result of the function object is always nonnegative, even if either of +the operator arguments is negative. + +This function object class template is used in the corresponding version of +the GCD function template. If a numeric type wants to customize evaluations +of its greatest common divisors, then the type should specialize on the +gcd_evaluator class template. + +[endsect] [/section GCD Function Object] + +[section LCM Function Object] + +[*Header: ] [@../../../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + class boost::math::lcm_evaluator + { + public: + // Types + typedef IntegerType result_type; + typedef IntegerType first_argument_type; + typedef IntegerType second_argument_type; + + // Function object interface + result_type operator ()( first_argument_type const &a, + second_argument_type const &b ) const; + }; + +The `boost::math::lcm_evaluator` class template defines a function object +class to return the least common multiple of two integers. The template +is parameterized by a single type, called IntegerType here. This type +should be a numeric type that represents integers. The result of the +function object is always nonnegative, even if either of the operator +arguments is negative. If the least common multiple is beyond the range +of the integer type, the results are undefined. + +This function object class template is used in the corresponding version +of the LCM function template. If a numeric type wants to customize +evaluations of its least common multiples, then the type should +specialize on the lcm_evaluator class template. + +[endsect] [/section LCM Function Object] + +[section:run_time Run-time GCD & LCM Determination] + +[*Header: ] [@../../../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + IntegerType boost::math::gcd( IntegerType const &a, IntegerType const &b ); + + template < typename IntegerType > + IntegerType boost::math::lcm( IntegerType const &a, IntegerType const &b ); + +The boost::math::gcd function template returns the greatest common +(nonnegative) divisor of the two integers passed to it. +The boost::math::lcm function template returns the least common +(nonnegative) multiple of the two integers passed to it. +The function templates are parameterized on the function arguments' +IntegerType, which is also the return type. Internally, these function +templates use an object of the corresponding version of the +gcd_evaluator and lcm_evaluator class templates, respectively. + +[endsect] [/section:run_time Run-time GCD & LCM Determination] + +[section:compile_time Compile time GCD and LCM determination] + +[*Header: ] [@../../../../boost/math/common_factor_ct.hpp ] + + typedef ``['unspecified]`` static_gcd_type; + + template < static_gcd_type Value1, static_gcd_type Value2 > + struct boost::integer::static_gcd : public mpl::integral_c + { + }; + + template < static_gcd_type Value1, static_gcd_type Value2 > + struct boost::integer::static_lcm : public mpl::integral_c + { + }; + +The type `static_gcd_type` is the widest unsigned-integer-type that is supported +for use in integral-constant-expressions by the compiler. Usually this +the same type as `boost::uintmax_t`, but may fall back to being `unsigned long` +for some older compilers. + +The __boost_integer_static_gcd and boost::integer::static_lcm class templates +take two value-based template parameters of the ['static_gcd_type] type +and inherit from the type `boost::mpl::integral_c`. +Inherited from the base class, they have a member ['value] +that is the greatest common factor or least +common multiple, respectively, of the template arguments. +A compile-time error will occur if the least common multiple +is beyond the range of `static_gcd_type`. + +[h3 Example] + + #include + #include + #include + #include + + int main() + { + using std::cout; + using std::endl; + + cout << "The GCD and LCM of 6 and 15 are " + << boost::math::gcd(6, 15) << " and " + << boost::math::lcm(6, 15) << ", respectively." + << endl; + + cout << "The GCD and LCM of 8 and 9 are " + << boost::math::static_gcd<8, 9>::value + << " and " + << boost::math::static_lcm<8, 9>::value + << ", respectively." << endl; + + int a[] = { 4, 5, 6 }, b[] = { 7, 8, 9 }, c[3]; + std::transform( a, a + 3, b, c, boost::math::gcd_evaluator() ); + std::copy( c, c + 3, std::ostream_iterator(cout, " ") ); + } + +[endsect] [/section:compile_time Compile time GCD and LCM determination] + +[section:gcd_header Header ] + +This header simply includes the headers +[@../../../../boost/integer/common_factor_ct.hpp ] +and [@../../../../boost/integer/common_factor_rt.hpp ]. + +[note this is a legacy header: it used to contain the actual implementation, +but the compile-time and run-time facilities +were moved to separate headers (since they were independent of each other). +It is usual to only include one of these]. + +[endsect] [/section:gcd_header Header ] + +[section: Test Program] + +The program [@../../../../libs/math/test/common_factor_test.cpp common_factor_test.cpp] +is a demonstration of the results from +instantiating various examples of the run-time GCD and LCM function +templates and the compile-time GCD and LCM class templates. +(The run-time GCD and LCM class templates are tested indirectly through +the run-time function templates.) + +[endsect] [/section:demo Demonstration Program] + +[section Rationale] + +The greatest common divisor and least common multiple functions are +greatly used in some numeric contexts, including some of the other +Boost libraries. Centralizing these functions to one header improves +code factoring and eases maintainence. + +[endsect] [/section Rationale] + +[endsect] [/section gcd_lcm Greatest Common Divisor and Least Common Multiple] [section Credits] -The author of the Boost compile-time extrema class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. +Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers discussed the integer traits idea on the boost mailing list in August 1999. -[endsect] -[endsect] +The author of the Boost bit mask class templates is [@http://www.boost.org/people/daryle_walker.html Daryle Walker]. + +The author of the Boost compilation of GCD and LCM computations is +[@http://www.boost.org/people/daryle_walker.html Daryle Walker]. +The code was prompted by existing code hiding in the +implementations of Paul Moore's rational library and Steve Cleary's +pool library. The code had updates by Helmut Zeisel. + +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. + +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] [/section Credits] [section:history History] +[h4 1.57.0] + +* Jan 2015 GCD & LCM moved into Boost.Integer to reduce dependency on Boost.Math. + [h4 1.56.0] -* Moved `` into [@boost:/libs/config/index.html - Boost.Config]. +* Moved `` into [@boost:/libs/config/index.html Boost.Config]. [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], +* 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], +* 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 +* 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 +* 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] +[section:gcd_history GCD & LCM History] -[section:cstdint Removed from library: Standard Integer Types] +* Feb 2015 Documentation moved into Boost.Integer. +* Jan 2015 GCD & LCM moved into Boost.Integer to remove dependency on Boost.Math. +* 13 May 2013 Moved into main Boost.Math Quickbook documentation. +* 17 Dec 2005: Converted documentation to Quickbook Format. +* 2 Jul 2002: Compile-time and run-time items separated to new headers. +* 7 Nov 2001: Initial version -The [@boost:/libs/config/doc/html/boost_config/cstdint.html Boost.Config] module provides -the typedefs useful for writing portable code that requires certain -integer widths. +[endsect] [/section:gcd_history History] -[endsect] +[endsect] [/section:history History] + +[section:cstdint Moved from Boost.Integer to Boost.Config: Standard Integer Types] + +The [@boost:/libs/config/doc/html/boost_config/cstdint.html Boost.Config] module now provides +the standard integer [@http://www.cplusplus.com/reference/cstdint/?kw=cstdint cstdint] +`typedef`s useful for writing portable code that requires certain integer with ['specified] widths. + +The Boost.Multiprecision library provides [@boost:/libs/multiprecision/doc/html/boost_multiprecision/tut/ints/cpp_int.html cpp_int] +provides fixed-precision integers via `typedef`s like `int128_t`, `uint512_t` and checked versions like `checked_int128_t` that may also be useful. + +[endsect] [/section:cstdint Removed from library: Standard Integer Types] + +[xinclude autodoc.xml] [/ Using Doxygen reference documentation.] + +[/Include the indexes (class, function and everything - there are no macros) ] +''' + + Function Index + + + + Class Index + + + + Typedef Index + + + + +''' + + +[/ +GCD & LCD Copyright 2005, 2013 Daryle Walker. +Copyright Revision Paul A. Bristow 2015 +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/include/boost/integer.hpp b/include/boost/integer.hpp index 48c863c..516a758 100644 --- a/include/boost/integer.hpp +++ b/include/boost/integer.hpp @@ -6,6 +6,9 @@ // See http://www.boost.org/libs/integer for documentation. +//! \file +//! \brief Compile-time evaluation of specified (least and fast) integer types. + // Revision History // 22 Sep 01 Added value-based integer templates. (Daryle Walker) // 01 Apr 01 Modified to use new header. (John Maddock) @@ -42,15 +45,16 @@ namespace boost // fast integers from least integers // int_fast_t<> works correctly for unsigned too, in spite of the name. template< typename LeastInt > - struct int_fast_t - { - typedef LeastInt fast; + struct int_fast_t + { + typedef LeastInt fast; typedef fast type; }; // imps may specialize +//! \cond DETAIL namespace detail{ - // convert category to type + // convert category to type template< int Category > struct int_least_helper {}; // default is empty template< int Category > struct uint_least_helper {}; // default is empty @@ -104,8 +108,8 @@ namespace boost template <> struct exact_unsigned_base_helper { typedef boost::ulong_long_type exact; }; #endif - } // namespace detail + //! \endcond // DETAIL // integer templates specifying number of bits ---------------------------// @@ -138,7 +142,7 @@ namespace boost "No suitable unsigned integer type with the requested number of bits is available."); #if (defined(__BORLANDC__) || defined(__CODEGEAR__)) && defined(BOOST_NO_INTEGRAL_INT64_T) // It's really not clear why this workaround should be needed... shrug I guess! JM - BOOST_STATIC_CONSTANT(int, s = + BOOST_STATIC_CONSTANT(int, s = 6 + (Bits <= ::std::numeric_limits::digits) + (Bits <= ::std::numeric_limits::digits) + @@ -147,7 +151,7 @@ namespace boost typedef typename detail::int_least_helper< ::boost::uint_t::s>::least least; #else typedef typename boost::detail::uint_least_helper - < + < #ifdef BOOST_HAS_LONG_LONG (Bits <= (int)(sizeof(boost::long_long_type) * CHAR_BIT)) + #else @@ -171,7 +175,7 @@ namespace boost #else template< long MaxValue > // maximum value to require support #endif - struct int_max_value_t + struct int_max_value_t { typedef typename boost::detail::int_least_helper < @@ -193,7 +197,7 @@ namespace boost #else template< long MinValue > // minimum value to require support #endif - struct int_min_value_t + struct int_min_value_t { typedef typename boost::detail::int_least_helper < @@ -216,12 +220,12 @@ namespace boost #else template< unsigned long MaxValue > // minimum value to require support #endif - struct uint_value_t + struct uint_value_t { #if (defined(__BORLANDC__) || defined(__CODEGEAR__)) // It's really not clear why this workaround should be needed... shrug I guess! JM #if defined(BOOST_NO_INTEGRAL_INT64_T) - BOOST_STATIC_CONSTANT(unsigned, which = + BOOST_STATIC_CONSTANT(unsigned, which = 1 + (MaxValue <= ::boost::integer_traits::const_max) + (MaxValue <= ::boost::integer_traits::const_max) + @@ -229,7 +233,7 @@ namespace boost (MaxValue <= ::boost::integer_traits::const_max)); typedef typename detail::int_least_helper< ::boost::uint_value_t::which>::least least; #else // BOOST_NO_INTEGRAL_INT64_T - BOOST_STATIC_CONSTANT(unsigned, which = + BOOST_STATIC_CONSTANT(unsigned, which = 1 + (MaxValue <= ::boost::integer_traits::const_max) + (MaxValue <= ::boost::integer_traits::const_max) + @@ -240,7 +244,7 @@ namespace boost #endif // BOOST_NO_INTEGRAL_INT64_T #else typedef typename boost::detail::uint_least_helper - < + < #if !defined(BOOST_NO_INTEGRAL_INT64_T) && defined(BOOST_HAS_LONG_LONG) (MaxValue <= ::boost::integer_traits::const_max) + #else @@ -255,7 +259,6 @@ namespace boost typedef typename int_fast_t::type fast; }; - } // namespace boost #endif // BOOST_INTEGER_HPP diff --git a/include/boost/integer/common_factor.hpp b/include/boost/integer/common_factor.hpp index fab9199..2577a3b 100644 --- a/include/boost/integer/common_factor.hpp +++ b/include/boost/integer/common_factor.hpp @@ -5,7 +5,9 @@ // accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -// See http://www.boost.org for updates, documentation, and revision history. +// See http://www.boost.org for updates, documentation, and revision history. +//! \file +//! \brief Include both GCD and LCM. #ifndef BOOST_INTEGER_COMMON_FACTOR_HPP #define BOOST_INTEGER_COMMON_FACTOR_HPP diff --git a/include/boost/integer/common_factor_ct.hpp b/include/boost/integer/common_factor_ct.hpp index 0671d16..572e063 100644 --- a/include/boost/integer/common_factor_ct.hpp +++ b/include/boost/integer/common_factor_ct.hpp @@ -5,7 +5,9 @@ // accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -// See http://www.boost.org for updates, documentation, and revision history. +// See http://www.boost.org for updates, documentation, and revision history. +//! \file +//! \brief Evaluate Greatest Common Divisor at compile-time. #ifndef BOOST_INTEGER_COMMON_FACTOR_CT_HPP #define BOOST_INTEGER_COMMON_FACTOR_CT_HPP @@ -17,9 +19,10 @@ namespace boost { namespace integer { + // Warning: this is from 1.58 in namespace boost::integer and no longer in namespace boost::math. // Implementation details --------------------------------------------------// - +//! \cond DETAIL namespace detail { // Build GCD with Euclid's recursive algorithm @@ -71,7 +74,7 @@ namespace detail }; } // namespace detail - +//! \endcond // DETAIL // Compile-time greatest common divisor evaluator class declaration --------// diff --git a/include/boost/integer/common_factor_rt.hpp b/include/boost/integer/common_factor_rt.hpp index c2b54db..4970aaa 100644 --- a/include/boost/integer/common_factor_rt.hpp +++ b/include/boost/integer/common_factor_rt.hpp @@ -4,13 +4,15 @@ // use, modify, sell and distribute this software is granted provided this // copyright notice appears in all copies. This software is provided "as is" // without express or implied warranty, and with no claim as to its suitability -// for any purpose. +// for any purpose. // boostinspect:nolicense (don't complain about the lack of a Boost license) // (Paul Moore hasn't been in contact for years, so there's no way to change the // license.) -// See http://www.boost.org for updates, documentation, and revision history. +// See http://www.boost.org for updates, documentation, and revision history. +//! \file +//! \brief Evaluate Least Common Multiple at compile-time. #ifndef BOOST_INTEGER_COMMON_FACTOR_RT_HPP #define BOOST_INTEGER_COMMON_FACTOR_RT_HPP @@ -31,7 +33,7 @@ namespace boost { namespace integer { - +// Warning: this is from 1.58 in namespace boost::interger and no longer in namespace boost::math. // Forward declarations for function templates -----------------------------// @@ -75,6 +77,7 @@ public: // Implementation details --------------------------------------------------// +//! \cond DETAIL namespace detail { @@ -387,9 +390,13 @@ namespace detail } } // namespace detail +//! \endcond // DETAIL - -// Greatest common divisor evaluator member function definition ------------// +// Greatest common divisor operator() evaluator member function definition ------------// +//! Evaluation operator() for Greatest Common Divisor (GCD) of two arguments. +//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant +//! \param a first_argument_type +//! \param b second_argument_type template < typename IntegerType > inline @@ -405,7 +412,11 @@ gcd_evaluator::operator () // Least common multiple evaluator member function definition --------------// - +//! Evaluates Least Common Multiplier of two arguments. +//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant +//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant +//! \param a first_argument_type +//! \param b second_argument_type template < typename IntegerType > inline typename lcm_evaluator::result_type @@ -420,6 +431,10 @@ lcm_evaluator::operator () // Greatest common divisor and least common multiple function definitions --// +//! Function for Greatest Common Divisor (GCD) of two arguments. +//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant +//! \param a first_argument_type +//! \param b second_argument_type template < typename IntegerType > inline @@ -435,6 +450,11 @@ gcd return solver( a, b ); } +//! Function for Least Common Multiplier (LCM) of two arguments. +//! \tparam IntegerType must be an integral constant http://en.cppreference.com/w/cpp/types/integral_constant +//! \param a first_argument_type +//! \param b second_argument_type + template < typename IntegerType > inline IntegerType diff --git a/include/boost/integer/integer_log2.hpp b/include/boost/integer/integer_log2.hpp index 8b34ce7..dcc6ee8 100644 --- a/include/boost/integer/integer_log2.hpp +++ b/include/boost/integer/integer_log2.hpp @@ -1,15 +1,18 @@ // ----------------------------------------------------------- // integer_log2.hpp // -// Gives the integer part of the logarithm, in base 2, of a -// given number. Behavior is undefined if the argument is <= 0. -// // Copyright (c) 2003-2004, 2008 Gennaro Prota // // 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) // +//! \file +//! \brief Function integer_log2 gives the integer part of the logarithm, in base 2, of a +//! given number (at run-time). Behavior is undefined if the argument is <= 0. +// +//! \note For analogous compile-time computation of log2 see static_log2. +//! \sa http::www.boost.org/doc/integer // ----------------------------------------------------------- #ifndef BOOST_INTEGER_INTEGER_LOG2_HPP @@ -24,6 +27,8 @@ namespace boost { + +//! \cond DETAIL namespace detail { template @@ -46,7 +51,6 @@ namespace boost { } - // helper to find the maximum power of two // less than p (more involved than necessary, // to avoid PTS) @@ -82,9 +86,8 @@ namespace boost { #endif }; - } // detail - +//! \endcond // DETAIL // --------- // integer_log2 @@ -104,9 +107,6 @@ namespace boost { } - } - - -#endif // include guard +#endif // BOOST_INTEGER_INTEGER_LOG2_HPP include guard diff --git a/include/boost/integer/integer_mask.hpp b/include/boost/integer/integer_mask.hpp index 2acf7f7..468e6c7 100644 --- a/include/boost/integer/integer_mask.hpp +++ b/include/boost/integer/integer_mask.hpp @@ -5,7 +5,10 @@ // accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -// See http://www.boost.org for updates, documentation, and revision history. +// See http://www.boost.org for updates, documentation, and revision history. + +//! \file +//! \brief Compile-time integer mask evaluation. #ifndef BOOST_INTEGER_INTEGER_MASK_HPP #define BOOST_INTEGER_INTEGER_MASK_HPP @@ -35,7 +38,6 @@ namespace boost { - // Specified single-bit mask class declaration -----------------------------// // (Lowest bit starts counting at 0.) diff --git a/include/boost/integer/static_log2.hpp b/include/boost/integer/static_log2.hpp index 56c7a00..8c066a8 100644 --- a/include/boost/integer/static_log2.hpp +++ b/include/boost/integer/static_log2.hpp @@ -10,6 +10,11 @@ // // --------------------------------------------------- // See http://www.boost.org/libs/integer for documentation. + +//! \file +//! \brief Compile-time calculation of integer part of the logarithm, in base 2, of a given number. +//! \note For a run-time calculation of log2, see function integer_log2 at integer_log2.hpp. + // ------------------------------------------------------------------------- // @@ -20,6 +25,8 @@ namespace boost { + //! \cond DETAIL + namespace detail { namespace static_log2_impl { @@ -99,8 +106,7 @@ namespace boost { } } // detail - - +//! \endcond // DETAIL // -------------------------------------- // static_log2 @@ -120,7 +126,7 @@ namespace boost { template <> struct static_log2<0> { }; -} +} // namespace boost diff --git a/include/boost/integer/static_min_max.hpp b/include/boost/integer/static_min_max.hpp index ee76fd4..5996ff3 100644 --- a/include/boost/integer/static_min_max.hpp +++ b/include/boost/integer/static_min_max.hpp @@ -5,7 +5,9 @@ // accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) -// See http://www.boost.org for updates, documentation, and revision history. +// See http://www.boost.org for updates, documentation, and revision history. +//! \file +//! \brief Compile-time evaluation of extrema: minimum or maximum of two values, signed or unsigned. #ifndef BOOST_INTEGER_STATIC_MIN_MAX_HPP #define BOOST_INTEGER_STATIC_MIN_MAX_HPP diff --git a/include/boost/integer_fwd.hpp b/include/boost/integer_fwd.hpp index 10577ae..a0922ca 100644 --- a/include/boost/integer_fwd.hpp +++ b/include/boost/integer_fwd.hpp @@ -5,6 +5,8 @@ // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) // See http://www.boost.org/libs/integer for documentation. +//! \file +//! \brief Include all Boost.Integer files. #ifndef BOOST_INTEGER_FWD_HPP #define BOOST_INTEGER_FWD_HPP diff --git a/include/boost/integer_traits.hpp b/include/boost/integer_traits.hpp index 94eb00d..0fd043d 100644 --- a/include/boost/integer_traits.hpp +++ b/include/boost/integer_traits.hpp @@ -8,10 +8,15 @@ * $Id$ * * Idea by Beman Dawes, Ed Brey, Steve Cleary, and Nathan Myers + */ // See http://www.boost.org/libs/integer for documentation. +//! \file +//! \brief integer traits +//! \sa http://www.boost.org/libs/integer + #ifndef BOOST_INTEGER_TRAITS_HPP #define BOOST_INTEGER_TRAITS_HPP @@ -47,6 +52,7 @@ public: BOOST_STATIC_CONSTANT(bool, is_integral = false); }; +//! \cond DETAIL namespace detail { template class integer_traits_base @@ -70,6 +76,7 @@ const T integer_traits_base::const_max; #endif } // namespace detail +//! \endcond // DETAIL template<> class integer_traits diff --git a/test/integer_test.cpp b/test/integer_test.cpp index fd9e6df..35f59ac 100644 --- a/test/integer_test.cpp +++ b/test/integer_test.cpp @@ -69,7 +69,7 @@ void do_test_exact(boost::mpl::true_ const&) template void do_test_exact(boost::mpl::false_ const&) { - // Nothing to do, type does not have an ::extact member. + // Nothing to do, type does not have an ::exact member. } template