From efb84707f04f154d2cf391f7149c371bedee1c9c Mon Sep 17 00:00:00 2001 From: jzmaddock Date: Mon, 24 Apr 2017 13:01:57 +0100 Subject: [PATCH] Update docs to match new gcd/lcm code. --- doc/gcd/math-gcd.qbk | 44 +++- doc/html/boost_integer/gcd_lcm.html | 395 ++++++++++++++++++++++++++++ doc/html/boost_integer/integer.html | 6 +- doc/html/boost_integer/mask.html | 6 +- doc/html/index.html | 25 +- doc/integer.qbk | 6 + 6 files changed, 469 insertions(+), 13 deletions(-) create mode 100644 doc/html/boost_integer/gcd_lcm.html diff --git a/doc/gcd/math-gcd.qbk b/doc/gcd/math-gcd.qbk index 346050c..7b9b312 100644 --- a/doc/gcd/math-gcd.qbk +++ b/doc/gcd/math-gcd.qbk @@ -1,5 +1,5 @@ -[mathpart gcd_lcm Integer Utilities (Greatest Common Divisor and Least Common Multiple)] +[section:gcd_lcm Greatest Common Divisor and Least Common Multiple] [section Introduction] @@ -27,6 +27,17 @@ programming problems. constexpr IntegerType gcd( IntegerType const &a, IntegerType const &b ); template < typename IntegerType > constexpr IntegerType lcm( IntegerType const &a, IntegerType const &b ); + template < typename IntegerType, typename... Args > + constexpr IntegerType gcd( IntegerType const &a, IntegerType const &b, Args const&... ); + template < typename IntegerType, typename... Args > + constexpr IntegerType lcm( IntegerType const &a, IntegerType const &b, Args const&... ); + + template + std::pair::value_type, I> + gcd_range(I first, I last); + template + std::pair::value_type, I> + lcm_range(I first, I last); typedef ``['see-below]`` static_gcd_type; @@ -123,14 +134,33 @@ They are also declared `noexcept` when appropriate. template < typename IntegerType > constexpr IntegerType boost::math::lcm( IntegerType const &a, IntegerType const &b ); + template < typename IntegerType, typename... Args > + constexpr IntegerType gcd( IntegerType const &a, IntegerType const &b, Args const&... ); + + template < typename IntegerType, typename... Args > + constexpr IntegerType lcm( IntegerType const &a, IntegerType const &b, Args const&... ); + + template + std::pair::value_type, I> + gcd_range(I first, I last); + + template + std::pair::value_type, I> + lcm_range(I first, I last); + The boost::math::gcd function template returns the greatest common (nonnegative) divisor of the two integers passed to it. +`boost::math::gcd_range` is the iteration of the above gcd algorithm over a +range, returning the greatest common divisor of all the elements. The algorithm +terminates when the gcd reaches unity or the end of the range. Thus it also +returns the iterator after the last element inspected because this may not be +equal to the end of the range. The variadic version of `gcd` behaves similarly +but does not indicate which input value caused the gcd to reach unity. + 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. +As with gcd, there are range and variadic versions of the function for +more than 2 arguments. Note that these functions are constexpr in C++14 and later only. They are also declared `noexcept` when appropriate. @@ -139,6 +169,8 @@ They are also declared `noexcept` when appropriate. [section:compile_time Compile time GCD and LCM determination] +[note These functions are deprecated in favor of constexpr `gcd` and `lcm` on C++14 capable compilers.] + [*Header: ] [@../../../../boost/math/common_factor_ct.hpp ] typedef ``['unspecified]`` static_gcd_type; @@ -246,7 +278,7 @@ pool library. The code had updates by Helmut Zeisel. [endsect] -[endmathpart] +[endsect] [/ Copyright 2005, 2013 Daryle Walker. diff --git a/doc/html/boost_integer/gcd_lcm.html b/doc/html/boost_integer/gcd_lcm.html new file mode 100644 index 0000000..25aaa55 --- /dev/null +++ b/doc/html/boost_integer/gcd_lcm.html @@ -0,0 +1,395 @@ + + + +Greatest Common Divisor and Least Common Multiple + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Introduction
+
Synopsis
+
GCD Function + Object
+
LCM Function + Object
+
Run-time GCD & LCM + Determination
+
Compile time GCD + and LCM determination
+
Header <boost/math/common_factor.hpp>
+
Demonstration Program
+
Rationale
+
History
+
Credits
+
+
+
+

+ The class and function templates in <boost/math/common_factor.hpp> + 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. +

+
+
+
+
namespace boost
+{
+namespace math
+{
+
+template < typename IntegerType >
+   class gcd_evaluator;
+template < typename IntegerType >
+   class lcm_evaluator;
+
+template < typename IntegerType >
+   constexpr IntegerType  gcd( IntegerType const &a, IntegerType const &b );
+template < typename IntegerType >
+   constexpr IntegerType  lcm( IntegerType const &a, IntegerType const &b );
+template < typename IntegerType, typename... Args >
+   constexpr IntegerType  gcd( IntegerType const &a, IntegerType const &b, Args const&... );
+template < typename IntegerType, typename... Args >
+   constexpr IntegerType  lcm( IntegerType const &a, IntegerType const &b, Args const&... );
+
+template <typename I>
+std::pair<typename std::iterator_traits<I>::value_type, I>
+   gcd_range(I first, I last);
+template <typename I>
+std::pair<typename std::iterator_traits<I>::value_type, I>
+   lcm_range(I first, I last);
+
+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;
+
+}
+}
+
+
+
+
+

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

+

+ Note that these function objects are constexpr + in C++14 and later only. They are also declared noexcept + when appropriate. +

+
+
+
+

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

+

+ Note that these function objects are constexpr in C++14 and later only. They + are also declared noexcept when + appropriate. +

+
+
+
+

+ Header: <boost/math/common_factor_rt.hpp> +

+
template < typename IntegerType >
+constexpr IntegerType  boost::math::gcd( IntegerType const &a, IntegerType const &b );
+
+template < typename IntegerType >
+constexpr IntegerType  boost::math::lcm( IntegerType const &a, IntegerType const &b );
+
+template < typename IntegerType, typename... Args >
+   constexpr IntegerType  gcd( IntegerType const &a, IntegerType const &b, Args const&... );
+
+template < typename IntegerType, typename... Args >
+   constexpr IntegerType  lcm( IntegerType const &a, IntegerType const &b, Args const&... );
+
+template <typename I>
+std::pair<typename std::iterator_traits<I>::value_type, I>
+   gcd_range(I first, I last);
+
+template <typename I>
+std::pair<typename std::iterator_traits<I>::value_type, I>
+   lcm_range(I first, I last);
+
+

+ The boost::math::gcd function template returns the greatest common (nonnegative) + divisor of the two integers passed to it. boost::math::gcd_range + is the iteration of the above gcd algorithm over a range, returning the greatest + common divisor of all the elements. The algorithm terminates when the gcd + reaches unity or the end of the range. Thus it also returns the iterator + after the last element inspected because this may not be equal to the end + of the range. The variadic version of gcd + behaves similarly but does not indicate which input value caused the gcd + to reach unity. +

+

+ The boost::math::lcm function template returns the least common (nonnegative) + multiple of the two integers passed to it. As with gcd, there are range and + variadic versions of the function for more than 2 arguments. +

+

+ Note that these functions are constexpr in C++14 and later only. They are + also declared noexcept when + appropriate. +

+
+
+
+
+ + + + + +
[Note]Note

+ These functions are deprecated in favor of constexpr gcd + and lcm on C++14 capable + compilers. +

+

+ Header: <boost/math/common_factor_ct.hpp> +

+
typedef unspecified static_gcd_type;
+
+template < static_gcd_type Value1, static_gcd_type Value2 >
+struct boost::math::static_gcd : public mpl::integral_c<static_gcd_type, implementation_defined>
+{
+};
+
+template < static_gcd_type Value1, static_gcd_type Value2 >
+struct boost::math::static_lcm : public mpl::integral_c<static_gcd_type, implementation_defined>
+{
+};
+
+

+ 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::math::static_gcd and boost::math::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. +

+

+ + Example +

+
#include <boost/math/common_factor.hpp>
+#include <algorithm>
+#include <iterator>
+#include <iostream>
+
+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<int>() );
+   std::copy( c, c + 3, std::ostream_iterator<int>(cout, " ") );
+}
+
+
+
+
+

+ This header simply includes the headers <boost/math/common_factor_ct.hpp> + and <boost/math/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). +

+
+
+
+

+ The program 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.) +

+
+
+
+

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

+
+
+
+
    +
  • + 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 author of the Boost compilation of GCD and LCM computations is 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. +

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

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

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_integer/integer.html b/doc/html/boost_integer/integer.html index 825ecf4..6dc60ef 100644 --- a/doc/html/boost_integer/integer.html +++ b/doc/html/boost_integer/integer.html @@ -7,7 +7,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -426,7 +426,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_integer/mask.html b/doc/html/boost_integer/mask.html index 05c0f77..0d72e1e 100644 --- a/doc/html/boost_integer/mask.html +++ b/doc/html/boost_integer/mask.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -374,7 +374,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/index.html b/doc/html/index.html index 90fe0b7..65dbc1c 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -54,6 +54,8 @@
Overview
Integer Traits
Integer Type Selection
+
Greatest Common Divisor and Least + Common Multiple
Integer Masks
Compile Time log2 Calculation
Compile time min/max calculation
@@ -158,6 +160,27 @@ + +

+ Greatest Common Divisor and + Least Common Multiple. +

+ + +

+ <boost/integer/common_factor_rt.hpp> + and <boost/integer/common_factor_ct.hpp> +

+ + +

+ Functions gcd and + lcm plus function + objects and compile time versions. +

+ + +

Integer Masks. @@ -219,7 +242,7 @@

- +

Last revised: March 28, 2017 at 17:56:42 GMT

Last revised: April 24, 2017 at 12:00:17 GMT
diff --git a/doc/integer.qbk b/doc/integer.qbk index 6beb0f4..75042f2 100644 --- a/doc/integer.qbk +++ b/doc/integer.qbk @@ -42,6 +42,11 @@ compile-time value; and computing min and max of constant expressions. 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.gcd_lcm Greatest Common Divisor and Least Common Multiple].] + [[^[@../../../../boost/integer/common_factor_rt.hpp ]] and [^[@../../../../boost/integer/common_factor_ct.hpp ]]] + [Functions `gcd` and `lcm` plus function objects and compile time versions.] + ] [ [[link boost_integer.mask Integer Masks].] [[^[@../../../../boost/integer/integer_mask.hpp ]]] @@ -358,6 +363,7 @@ for sharing their designs for similar templates. [endsect] [endsect] +[include gcd/math-gcd.qbk] [section:mask Integer Masks]