2nd draft with zero errors from Inspect.

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, and code snippets from examples.
+# 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
+             <auto-index>on
+             <auto-index-script>integer.idx
+             <auto-index-prefix>.
+             <auto-index-verbose>on
+             <format>html:<auto-index-internal>on
+             <format>html:<xsl:param>generate.index=0
+             <format>pdf:<auto-index-internal>on
+             <format>pdf:<xsl:param>index.on.type=1
+             <quickbook-define>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/*.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
+    #     <doxygen:param>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.
+
+  :
+    <doxygen:param>PROJECT_NAME="Integer"
+    <doxygen:param>RECURSIVE=NO # Specify all folders and files above explicitly.
+    <doxygen:param>ENABLE_PREPROCESSING=YES
+    <doxygen:param>EXPAND_ONLY_PREDEF=YES
+    <doxygen:param>EXTRACT_ALL=NO
+    <doxygen:param>EXTRACT_PRIVATE=NO
+    <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+    <doxygen:param>MACRO_EXPANSION=YES
+    <doxygen:param>SORT_MEMBER_DOCS=NO
+    <doxygen:param>SHOW_INCLUDE_FILES=NO
+    <doxygen:param>MAX_INITIALIZER_LINES=0
+    <doxygen:param>VERBATIM_HEADERS=NO
+    <doxygen:param>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.
+    <doxygen:param>WARN_IF_UNDOCUMENTED=YES # If WARN_IF_UNDOCUMENTED is set to YES,
+    # then doxygen will generate warnings for all undocumented members.
+    <doxygen:param>WARN_IF_DOC_ERROR=YES # If WARN_IF_DOC_ERROR is set to YES, Doxygen will generate warnings for
+    # potential errors in the documentation.
+    <doxygen:param>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.
+
+    #<reftitle>"Reference" # Default is "Reference" but helpful to specify library.
+    <xsl:param>"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:
         <xsl:param>navig.graphics=1
+        <xsl:param>chapter.autolabel=0 # No Chapter numbering.
         # How far down we chunk nested sections, basically all of them:
         <xsl:param>chunk.section.depth=1
         # Don't put the first section on the same page as the TOC:
@@ -26,7 +103,7 @@ boostbook standalone
         <xsl:param>generate.section.toc.level=4
         # Path for links to Boost:
         <xsl:param>boost.root=../../../..
-        
+
         # PDF Options:
         # TOC Generation: this is needed for FOP-0.9 and later:
         <xsl:param>fop1.extensions=0
@@ -47,10 +124,20 @@ boostbook standalone
         # better use SVG's instead:
         <format>pdf:<xsl:param>admon.graphics.extension=".svg"
         <format>pdf:<xsl:param>admon.graphics.path=$(boost-images)/
-        <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/regex/doc/html
+        # Use Arial for PDF.
+        <format>pdf:<xsl:param>title.font.family="sans-serif"
+        <format>pdf:<xsl:param>body.font.family="sans-serif"
+        <format>pdf:<xsl:param>monospace.font.family="sans-serif"
+
+       <dependency>autodoc # Add Doxygen info.
+
     ;
 
-install pdfinstall : standalone/<format>pdf : <location>. <install-type>PDF ;
+# install pdfinstall : standalone/<format>pdf : <location>. <install-type>PDF <name>boost.pdf ;
+
+
+install pdf-install : standalone : <install-type>PDF <location>. <name>integer.pdf ;
+
 explicit pdfinstall ;
 
 

doc/integer.idx

@@ -0,0 +1,28 @@
+# integer.idx for Boost.integer/Spreadinteger Quickbook, Doxygen and Auto-index.
+
+# Note needs more customization to be useful in practice! TODO?
+
+#!debug "\<\w*\>"
+
+# integer Header files.
+!scan-path "../include/boost/" ".*\.hpp" false
+!scan-path "../include/boost/integer" ".*\.hpp" false
+
+# All example source files, assuming no sub-folders.
+# integer example files.
+#!scan-path "../example" ".*\.cpp" true
+
+# Allow alternative spellings colour | color, and plurals etc.
+color  \<\w*(colour|color)\w*\>
+example \<example\w*\>
+font  \<font\w*\>
+greek
+ioflags
+origin
+outlier
+maximum \<max\w*\>
+minimum \<min\w*\>
+precision
+range  \<\w*\range\w*\>
+title
+Unicode \<unicode\w*\>

example/integer_common_factor_example.cpp

@@ -0,0 +1,62 @@
+// boost integer_common_factor_example.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+// #include <boost/integer/common_factor.hpp> // Includes both ct and rt but now deprecated.
+
+//[integer_common_factor_example_0]
+#include <boost/integer/common_factor_ct.hpp> // For compile-time GCD & LCM Determination.
+#include <boost/integer/common_factor_rt.hpp> // For run-time GCD & LCM Determination.
+//] [/integer_common_factor_example_0]
+#include <iostream>
+#include <algorithm>
+#include <iterator>
+
+#include <limits>  // for numeric_limits min and max.
+
+int main()
+{
+//[integer_common_factor_example_1
+  std::cout << "The run-time GCD and LCM of 6 and 15 are "
+    << boost::integer::gcd(6, 15) << " and "
+    << boost::integer::lcm(6, 15) << ", respectively."
+    << std::endl;
+  // The GCD and LCM of 6 and 15 are 3 and 30, respectively.
+//] [/integer_common_factor_example_1]
+
+//[integer_common_factor_example_2
+
+  std::cout << "The compile-time GCD and LCM of 8 and 9 are "
+    << boost::integer::static_gcd<8, 9>::value
+    << " and "
+    << boost::integer::static_lcm<8, 9>::value
+    << ", respectively." << std::endl;
+  // The GCD and LCM of 8 and 9 are 1 and 72, respectively.
+//] [/integer_common_factor_example_2]
+
+//[integer_common_factor_example_3
+  int  a[] = { 4, 5, 6 }, b[] = { 7, 8, 9 }, c[3];
+  std::transform(a, a + 3, b, c, boost::integer::gcd_evaluator<int>());
+  std::copy(c, c + 3, std::ostream_iterator<int>(std::cout, " "));
+//] [/integer_common_factor_example_3]
+
+} // int main
+
+/*
+//[integer_common_factor_example_output_1
+The run-time GCD and LCM of 6 and 15 are 3 and 30, respectively.
+
+The compile-time GCD and LCM of 8 and 9 are 1 and 72, respectively.
+//] [/integer_common_factor_example_output_1]
+
+//[integer_common_factor_example_output_2
+1 1 3
+//] [/integer_common_factor_example_output_2]
+*/

example/integer_log2_example.cpp

@@ -0,0 +1,41 @@
+// boost integer_log2_example.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+//[integer_log2_example_0
+#include <boost/integer/static_log2.hpp> // For boost::static_log2
+//] [/integer_log2s_example_0]
+#include <iostream> 
+#include <limits>  // for numeric_limits min and max.
+
+//[integer_log2_example_
+//] [/integer_log2s_example_]
+
+int main()
+{
+//[integer_log2_example_1
+  int n = boost::static_log2<256>::value;
+//] [/integer_log2_example_1]
+
+  std::cout << n << std::endl; // 8
+
+  //[integer_log2_example_2
+  int n2 = boost::static_log2<65536>::value;
+//] [/integer_log2_example_2]
+
+  std::cout << n2 << std::endl; // 16
+
+} // int main
+
+/*
+//[integer_log2_example_output
+8
+//] [/integer_log2_example_output]
+*/

example/integer_mask_example.cpp

@@ -0,0 +1,69 @@
+// boost integer_mask_example.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+//[integer_mask_example_0
+#include <boost/integer/integer_mask.hpp> // For boost::high_bit_mask_t etc
+//] [/integer_masks_example_0]
+#include <iostream> 
+#include <limits>  // for numeric_limits min and max.
+
+//[integer_mask_example_
+//] [/integer_masks_example_]
+
+int main()
+{
+//[integer_mask_example_1
+  typedef boost::high_bit_mask_t<29>  mask1_type;
+  typedef boost::low_bits_mask_t<15>  mask2_type;
+//] [/integer_masks_example_1]
+
+//[integer_mask_example_2
+  // high_bit_mask_t
+  std::cout << std::hex << mask1_type::bit_position << std::endl; // 1d
+  std::cout << std::hex << mask1_type::high_bit << std::endl; // 20000000
+  std::cout << std::hex << mask1_type::high_bit_fast << std::endl; // 20000000
+
+  // low_bits_mask_t
+  std::cout << std::hex << mask2_type::bit_count << std::endl; // F
+  std::cout << std::hex << mask2_type::sig_bits << std::endl; // 7fff
+  std::cout << std::hex << mask2_type::sig_bits_fast << std::endl; // 7fff
+//] [/integer_masks_example_2]
+
+//[integer_mask_example_3
+  mask1_type::least  my_var1;
+  mask2_type::fast   my_var2;
+//] [/integer_masks_example_3]
+
+//[integer_mask_example_4
+  my_var1 |= mask1_type::high_bit;
+  std::cout << std::hex << my_var1 << std::endl; // eccccccc
+//] [/integer_masks_example_4]
+
+//[integer_mask_example_5
+  my_var2 &= mask2_type::sig_bits;
+  std::cout << std::hex << my_var2 << std::endl; // 4ccc
+//] [/integer_masks_example_5]
+
+} // int main
+
+/*
+//[integer_mask_example_output
+1d
+20000000
+20000000
+f
+7fff
+7fff
+eccccccc
+4ccc
+//] [/integer_mask_example_output]
+
+*/

example/integer_static_minmax_example.cpp

@@ -0,0 +1,73 @@
+// boost integer_static_minmax_example.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+#include <boost/integer/static_min_max.hpp> // For boost::static_signed_min
+#include <iostream> 
+#include <limits>  // for numeric_limits min and max.
+
+//[integer_min_max_example_0
+
+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;
+}; // class adder
+
+//] [/integer_min_max_example_0]
+
+int main()
+{
+//[integer_min_max_example_1
+
+  std::cout << "boost::static_signed_min< 9, 14>::value = "<< boost::static_signed_min< 9, 14>::value << std::endl;
+  std::cout << "boost::static_signed_max< 9, 14>::value = "<< boost::static_signed_max< 9, 14>::value << std::endl;
+
+//] [/integer_min_max_example_1]
+
+//[integer_min_max_example_2
+  int const   a1[] = { 0, 4, 3 };  // 340
+  int const   a2[] = { 9, 8 };     //  89
+  int         s[4];
+
+  adder<3, 2>  obj;
+  // adder<sizeof(a1), sizeof(a2)>  obj;
+
+  std::cout << "obj.addend1_size = " << obj.addend1_size << std::endl; // 3
+  std::cout << "obj.addend2_size = " << obj.addend2_size << std::endl; // 2
+  std::cout << "obj.sum_size = " << obj.sum_size << std::endl; // 4
+//] [/integer_min_max_example_2]
+
+  // obj(a1, a2, s);  // 's' should be 429 or { 9, 2, 4, 0 }
+  //void adder<3,2>::operator()(int const (&)[3],int const (&)[2],int (&)[4])const 
+
+  std::cout << s[0] << s[1]  << s[2] << s[3]<< std::endl; // 's' should be 429 or { 9, 2, 4, 0 }
+
+} // int main
+
+/*
+//[integer_min_max_example_output
+
+boost::static_signed_min< 9, 14>::value = 9
+boost::static_signed_max< 9, 14>::value = 14
+obj.addend1_size = 3
+obj.addend2_size = 2
+obj.sum_size = 4
+//] [/integer_min_max_example_output]
+*/

example/integer_traits_example.cpp

@@ -0,0 +1,55 @@
+// boost integer_traits_example.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+#include <boost/integer_traits.hpp>
+#include <iostream> 
+#include <limits>  // for numeric_limits min and max.
+
+//[integer_traits_example_1
+template<int N>
+void f()
+{ // Entirely contrived templated function.
+  std::cout << N << std::endl; // Do something pointless.
+}
+//] [/integer_traits_example_1]
+
+
+int main()
+{
+  std::cout << "Type int, min =  " 
+    << (std::numeric_limits<int>::min)() 
+    << ", const_min =  " << boost::integer_traits<int>::const_min
+    << std::endl; // Type int, min =  -2147483648, const_min =  -2147483648
+
+//[integer_traits_example_2
+  f<2>();
+//] [/integer_traits_example_2]
+
+//[integer_traits_example_3
+  int i = 2;
+ // f<i>(); // A local variable cannot be used as a non-type argument.
+//] [/integer_traits_example_3]
+
+//[integer_traits_example_4
+  const int ci = 2;
+  f<ci>(); // But a const variable can.
+//] [/integer_traits_example_4]
+//[integer_traits_example_5
+
+  // f<std::numeric_limits<int>::min()>(); // Function call must have a constant value in a constant expression.
+//] [/integer_traits_example_5]
+//[integer_traits_example_6
+
+  f<boost::integer_traits<int>::const_min>();
+//] [/integer_traits_example_6]
+
+} // int main
+

example/integer_type_selection_example.cpp

@@ -0,0 +1,251 @@
+// boost integer_type_selection.cpp 
+
+// Copyright Paul A. Bristow 2015
+// 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)
+
+// Caution: this file contains Quickbook markup as well as code
+// and comments, don't change any of the special comment markups!
+
+#include <boost/integer.hpp>
+#include <iostream> 
+#include <limits>  // for numeric_limits min and max.
+// Note use of extra brackets to avoid potential clash for any min and max macros:
+// (std::numeric_limits<T>::max)()  (std::numeric_limits<T>::min)()
+
+//! Show info about type
+template <const int Bits, typename T>
+void show_type()
+{ 
+  std::cout << typeid(T).name() 
+    << " is a signed int using at least " << Bits << " bits uses "
+    << std::numeric_limits<boost::int_t<Bits>::least>::digits 
+    << " bits, needing at most "
+    << std::numeric_limits<boost::int_t<Bits>::least>::digits10
+    << " decimal digits, "    " and representing a maximum decimal value of "
+    << static_cast<int>((std::numeric_limits<boost::int_t<Bits>::least>::max)())
+    << std::endl;
+} // template <const int Bits, typename T> void show_type()
+
+template <typename T>
+void show_consts()
+{ // 
+  std::cout << "Type " << typeid(T).name();
+  if (std::numeric_limits<T>::is_specialized)
+  {
+    std::cout << " is specialized for std::numeric_limits,";
+    if (std::numeric_limits<T>::is_integer)
+    {
+      std::cout << " and is integer type." << std::endl;
+      // If a constant expression for `min` and `max` are required, see  
+      // Boost integer_traits.
+      std::cout << "const_max = " << boost::integer_traits<T>::const_max << std::endl;
+      std::cout << "const_min = " << boost::integer_traits<T>::const_min << std::endl;
+    }
+  }
+} // void show_consts()
+
+template <typename T>
+void show_type()
+{
+  std::cout << "Type " << typeid(T).name(); // name of resultant type.
+  if (std::numeric_limits<T>::is_specialized)
+  {
+    if (std::numeric_limits<T>::is_integer)
+    {
+      std::cout << " is an unsigned int with at least 13 bits using "
+      << std::numeric_limits<T>::digits + (std::numeric_limits<T>::is_signed ? 1 : 0) << " bits,\n"
+      // See http://en.cppreference.com/w/cpp/types/numeric_limits/digits for details on the meaning of digits10.
+      // The value of std::numeric_limits<T>::digits is the number of digits in base-radix that can be represented 
+      // by the type T without change. 
+      // For integer types, this is the number of bits *not counting the sign bit*, so add one for the total.
+      // (For floating-point types, this is the number of digits in the mantissa).
+      "guaranteeing at most " << std::numeric_limits<T>::digits10 << " decimal digits precision,\n"
+      "and using at most " << std::numeric_limits<T>::digits10 + 1
+      << " decimal digits,\n"
+      // See http://en.cppreference.com/w/cpp/types/numeric_limits/digits10 for details on the meaning of digits10.
+      // The value of std::numeric_limits<T>::digits is the number of digits in base-radix that can be represented 
+      // by the type T without change. 
+      // For integer types, the maximum number of digits that may be required is one more than digits10.
+      "a maximum decimal value of " << static_cast<long>((std::numeric_limits<T>::max)())
+      << " and a minimum decimal value of " << static_cast<long>((std::numeric_limits<T>::min)()) << "."
+      << std::endl;
+   }
+    else
+    {
+      std::cout << "is floating-point." << std::endl;
+    }
+  }
+  else
+  { //  is NOT specialized.
+    std::cout << " is NOT specialized for std::numeric_limits!" << std::endl;
+  }
+} // template <typename T> void show_type()
+
+
+template <typename T>
+void show_type_limits()
+{ // 
+
+  std::cout <<"Type " << typeid(T).name();
+  if (std::numeric_limits<T>::is_specialized)
+  {
+    std::cout << " is specialized for std::numeric_limits." << std::endl;
+    if (std::numeric_limits<T>::is_integer)
+      {
+        std::cout << "is integer." << std::endl;
+
+        std::cout << (std::numeric_limits<T>::is_bounded ? "is bounded." : "") << std::endl;
+        std::cout << (std::numeric_limits<T>::is_exact ? "is exact." : "") << std::endl;
+        std::cout << (std::numeric_limits<T>::is_modulo ? "is modulo." : "") << std::endl;
+        std::cout << "radix = " << std::numeric_limits<T>::radix << std::endl;
+        std::cout << (std::numeric_limits<T>::is_signed ? "is signed." : "is unsigned.") << std::endl;
+
+        std::cout << "max = " << static_cast<long>((std::numeric_limits<T>::max)()) << std::endl;
+        std::cout << "min = " << static_cast<long>((std::numeric_limits<T>::min)()) << std::endl;
+        // Can't list const_max or const_min here because compiler will protest that
+        // const_max' : is not a member of 'boost::integer_traits<T>' when T is double.
+        //std::cout << "const_max = " << boost::integer_traits<T>::const_max << std::endl;
+        //std::cout << "const_min = " << boost::integer_traits<T>::const_min << std::endl;
+
+        std::cout << "digits = " << std::numeric_limits<T>::digits << std::endl;
+        std::cout << "bits = " << std::numeric_limits<T>::digits +1 << std::endl;
+        // digits is the number of bits not counting the sign bit for integer types.
+
+        std::cout << "digits10 = " << std::numeric_limits<T>::digits10 << std::endl;
+        // max_digits10 is not defined for integer types.
+        //std::cout << "max_digits10 = " << std::numeric_limits<T>::max_digits10 << std::endl;
+      }
+      else
+      { // Not integral, so might be floating-point, or ?
+        std::cout << "is NOT integral type." << std::endl;
+        if ((std::numeric_limits<T>::max_exponent != 0) && (std::numeric_limits<T>::max_exponent10 != 0))
+        { // floating-point type including fundamental float, double and multiprecision like cpp_dec_float_50 and cpp_bin_float_50.
+          std::cout << "is floating-point type." << std::endl;
+          std::cout << "digits = " << std::numeric_limits<T>::digits << std::endl;
+          // digits is the number of bits in the significand (not counting the sign bit) for floating-point types.
+          std::cout << "digits10 = " << std::numeric_limits<T>::digits10 << std::endl;
+          // http://en.cppreference.com/w/cpp/types/numeric_limits/digits10  
+          std::cout << "max_digits10 = " << std::numeric_limits<T>::max_digits10 << std::endl;
+          std::cout << "is_modulo = " << std::numeric_limits<T>::is_modulo << std::endl;
+          std::cout << "is_iec559 = " << std::numeric_limits<T>::is_iec559 << std::endl;
+          std::cout << (std::numeric_limits<T>::is_exact ? "is exact." : "") << std::endl;
+          std::cout << (std::numeric_limits<T>::is_signed ? "is signed." : "is unsigned.") << std::endl;
+          std::cout << "has_quiet_NaN = " << std::numeric_limits<T>::has_quiet_NaN << std::endl;
+          std::cout << "has_infinity = " << std::numeric_limits<T>::has_infinity << std::endl;
+          std::cout << "has_denorm_loss = " << std::numeric_limits<T>::has_denorm_loss << std::endl;
+          std::cout << "max_exponent = " << std::numeric_limits<T>::max_exponent << std::endl;
+          std::cout << "min_exponent = " << std::numeric_limits<T>::min_exponent << std::endl;
+          std::cout << "max_exponent10 = " << std::numeric_limits<T>::max_exponent10 << std::endl;
+          std::cout << "min_exponent10 = " << std::numeric_limits<T>::min_exponent10 << std::endl;
+        }
+        else
+        { // Unknown type
+          std::cout << "Unknown type." << std::endl;
+        }
+      }
+  }
+  else 
+  { // Not specialized!
+    std::cout << " is NOT specialized for std::numeric_limits!" << std::endl;
+  }
+} // show_type_limits
+
+
+int main()
+{
+  try
+  { 
+
+// Select, construct and assign an unsigned integer of at least 13 bits.
+//[integer_type_selection_1
+     boost::uint_t<13>::least my_var13 = 42;  
+//] [/integer_type_selection_1]
+
+//[integer_type_selection_2
+     show_type<boost::uint_t<13>::least>();
+//] [/integer_type_selection_2]
+
+    // Select fastest signed integer of at least 7 bits.
+//[integer_type_selection_3
+    typedef boost::int_t<7>::fast int_7; 
+//] [/integer_type_selection_3]
+
+//[integer_type_selection_4
+    show_type<int_7>();
+//] [/integer_type_selection_4]
+
+
+  // Choose an integer size that can hold at least a value of 1000
+  // Assignment of this value is guaranteed not to be truncated:
+//[integer_value_type_selection_5
+
+    boost::int_max_value_t<1000>::least thousand = 1000;
+//] [/integer_value_type_selection_5]
+
+    std::cout << thousand << std::endl;
+
+//[integer_value_type_selection_6
+
+    std::cout << (std::numeric_limits<boost::int_max_value_t<1000>::least>::max)() << std::endl;
+
+//] [/integer_value_type_selection_6]
+
+//[integer_value_type_selection_7
+
+  thousand = 100000; // Probably too big!
+
+  // warning C4305 :  warning C4305: '=' : truncation from 'int' to 'short'
+  // warning C4309:  '='  : truncation of constant value
+
+//] [/integer_value_type_selection_7]
+
+//[integer_value_type_selection_8
+
+    boost::int_t<32>::exact my_exact32 = 1000000;
+  
+    std::cout << "boost::int_t<32>::exact has "
+      << std::numeric_limits<boost::int_t<32>::exact>::digits
+      << " bits and 1 sign bit." << std::endl;
+//  boost::int_t<32>::exact has 31 bits and 1 sign bit.
+
+//] [/integer_value_type_selection_8]
+
+// If we ask for an unachievable number of bits or value
+
+    //boost::int_t<128>::exact exact128;
+    //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
+
+    show_consts<boost::int_t<32>::exact>();
+    //  const_max = 2147483647  const_min = -2147483648
+
+    show_type<16, boost::int_max_value_t<1000>::least>();
+
+  }
+  catch (std::exception ex)
+  {
+    std::cout << ex.what() << std::endl;
+  }
+  return 0;
+} // int main
+
+
+/*
+
+//[integer_type_selection_output_1
+Type short is an unsigned int with at least 13 bits using 16 bits,
+guaranteeing at most 4 decimal digits precision,
+and using at most 5 decimal digits,
+//] [/integer_type_selection_output_1]
+
+//[integer_type_selection_output_2
+Type signed char is an unsigned int with at least 13 bits using 8 bits,
+guaranteeing at most 2 decimal digits precision,
+and using at most 3 decimal digits,
+a maximum decimal value of 127 and a minimum decimal value of -128.
+//] [/integer_type_selection_output_2]
+
+*/

example/jamfile.v2

@@ -0,0 +1,33 @@
+# libs/integer/example Jamfile
+# Copyright (c) Vladimir Batov 2009-2014
+# Copyright Paul A. Bristow 2015
+
+# Distributed under the Boost Software License, Version 1.0.
+# See copy at http://www.boost.org/LICENSE_1_0.txt.
+
+# bring in the rules for testing
+import testing ;
+
+project convert_examples
+    : requirements
+        <warnings>on
+        <toolset>gcc:<warnings>all
+        <toolset>msvc:<warnings>all
+        <toolset>gcc:<cxxflags>"-Wno-unused-local-typedefs -Wno-unused-variable -Wno-long-long"
+        <toolset>msvc:<cxxflags>"/wd4996 /wd4512 /wd4610 /wd4510 /wd4127 /wd4701 /wd4127 /wd4305 /wd4100 /wd4512 /wd4714"
+        <toolset>msvc:<asynch-exceptions>on
+        <toolset>msvc:<define>_CRT_SECURE_NO_DEPRECATE
+        <toolset>msvc:<define>_SCL_SECURE_NO_DEPRECATE
+        <toolset>msvc:<define>_SCL_SECURE_NO_WARNINGS
+        <toolset>msvc:<define>_CRT_SECURE_NO_WARNINGS
+        <include>../include
+    ;
+
+run integer_mask_example.cpp ;
+run integer_traits_example.cpp ;
+run integer_type_selection_example.cpp ;
+
+
+
+
+

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 <boost/limits.hpp> 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<sizeof(boost::ulong_long_type)* CHAR_BIT> { 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<unsigned long>::digits) +
           (Bits <= ::std::numeric_limits<unsigned int>::digits) +
@@ -147,7 +151,7 @@ namespace boost
      typedef typename detail::int_least_helper< ::boost::uint_t<Bits>::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<unsigned long>::const_max) +
           (MaxValue <= ::boost::integer_traits<unsigned int>::const_max) +
@@ -229,7 +233,7 @@ namespace boost
           (MaxValue <= ::boost::integer_traits<unsigned char>::const_max));
       typedef typename detail::int_least_helper< ::boost::uint_value_t<MaxValue>::which>::least least;
 #else // BOOST_NO_INTEGRAL_INT64_T
-      BOOST_STATIC_CONSTANT(unsigned, which = 
+      BOOST_STATIC_CONSTANT(unsigned, which =
            1 +
           (MaxValue <= ::boost::integer_traits<boost::ulong_long_type>::const_max) +
           (MaxValue <= ::boost::integer_traits<unsigned long>::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<boost::ulong_long_type>::const_max) +
 #else
@@ -255,7 +259,6 @@ namespace boost
       typedef typename int_fast_t<least>::type  fast;
   };
 
-
 } // namespace boost
 
 #endif  // BOOST_INTEGER_HPP

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

include/boost/integer/common_factor_ct.hpp

@@ -5,21 +5,25 @@
 //  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 and Least Common Multiple at compile-time.
 
 #ifndef BOOST_INTEGER_COMMON_FACTOR_CT_HPP
 #define BOOST_INTEGER_COMMON_FACTOR_CT_HPP
 
-#include <boost/integer_fwd.hpp>  // self include
+#include <boost/integer_fwd.hpp>  // Include for declaration of static_gcd_type and static_gcd.
 #include <boost/config.hpp>  // for BOOST_STATIC_CONSTANT, etc.
+#include <boost/cstdint.hpp> // for boost::uintmax_t
 
 namespace boost
 {
 namespace integer
 {
+  // Warning: From 1.58 this is 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 +75,7 @@ namespace detail
     };
 
 }  // namespace detail
-
+//! \endcond // DETAIL
 
 //  Compile-time greatest common divisor evaluator class declaration  --------//
 

include/boost/integer/common_factor_rt.hpp

@@ -4,46 +4,56 @@
 //  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
 
-#include <boost/integer_fwd.hpp>  // self include
-
 #include <boost/config.hpp>  // for BOOST_NESTED_TEMPLATE, etc.
 #include <boost/limits.hpp>  // for std::numeric_limits
-#include <climits>           // for CHAR_MIN
 #include <boost/detail/workaround.hpp>
 
+#include <boost/integer_fwd.hpp>  // Include for declarations of gcd_evaluator and lcm_evaluator.
+
+#include <climits>           // for CHAR_MIN
+
 #ifdef BOOST_MSVC
 #pragma warning(push)
 #pragma warning(disable:4127 4244)  // Conditional expression is constant
 #endif
 
+// Warning:  this is from 1.58 in namespace boost::integer and no longer in namespace boost::math.
+
 namespace boost
 {
 namespace integer
 {
-
+//  Forward declarations copied from <boost/math/common_factor_rt.hpp> at 1.58 -----//
 
 //  Forward declarations for function templates  -----------------------------//
 
 template < typename IntegerType >
-    IntegerType  gcd( IntegerType const &a, IntegerType const &b );
+IntegerType  gcd( IntegerType const &a, IntegerType const &b );
 
 template < typename IntegerType >
-    IntegerType  lcm( IntegerType const &a, IntegerType const &b );
-
+IntegerType  lcm( IntegerType const &a, IntegerType const &b );
 
 //  Greatest common divisor evaluator class declaration  ---------------------//
 
+template < typename IntegerType >
+class gcd_evaluator;
+
+template < typename IntegerType >
+class lcm_evaluator;
+
 template < typename IntegerType >
 class gcd_evaluator
 {
@@ -75,6 +85,7 @@ public:
 
 
 //  Implementation details  --------------------------------------------------//
+//! \cond DETAIL
 
 namespace detail
 {
@@ -387,9 +398,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 +420,11 @@ gcd_evaluator<IntegerType>::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<IntegerType>::result_type
@@ -420,6 +439,10 @@ lcm_evaluator<IntegerType>::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 +458,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

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 <typename T>
@@ -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

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

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<x>
@@ -120,7 +126,7 @@ namespace boost {
  template <>
  struct static_log2<0> { };
 
-}
+} // namespace boost
 
 
 

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

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
@@ -16,7 +18,6 @@
 #include <boost/limits.hpp>  // for std::numeric_limits
 #include <boost/cstdint.hpp>  // For intmax_t
 
-
 namespace boost
 {
 
@@ -158,6 +159,8 @@ template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Valu
 template <static_min_max_unsigned_type Value1, static_min_max_unsigned_type Value2>
     struct static_unsigned_max;
 
+namespace integer
+{
 
 //  From <boost/integer/common_factor_ct.hpp>
 
@@ -180,6 +183,7 @@ template < typename IntegerType >
 template < typename IntegerType >
     class lcm_evaluator;
 
+] // namespace integer
 
 }  // namespace boost
 

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 T, T min_val, T max_val>
 class integer_traits_base
@@ -70,6 +76,7 @@ const T integer_traits_base<T, min_val, max_val>::const_max;
 #endif
 
 } // namespace detail
+//! \endcond // DETAIL
 
 template<>
 class integer_traits<bool>

test/integer_test.cpp

@@ -69,7 +69,7 @@ void do_test_exact(boost::mpl::true_ const&)
 template <int Bits>
 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 <int Bits>