mirror of
https://github.com/boostorg/integer.git
synced 2025-07-29 20:27:14 +02:00
Added refactored docs for existing Boost.Math libraries.
[SVN r39851]
This commit is contained in:
John Maddock
committed by
Peter Dimov
Peter Dimov
parent
b70c89a3ff
commit
dcf16f30bc
243
doc/gcd/math-gcd.qbk
Normal file
243
doc/gcd/math-gcd.qbk
Normal file
@ -0,0 +1,243 @@
|
||||
[article GCD and LCM
|
||||
[quickbook 1.3]
|
||||
[copyright 2001-2002 Daryle Walker]
|
||||
[license
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
[@http://www.boost.org/LICENSE_1_0.txt http://www.boost.org/LICENSE_1_0.txt])
|
||||
]
|
||||
[authors [Walker, Daryle]]
|
||||
[category math]
|
||||
[last-revision $Date: 2006-12-29 11:08:32 +0000 (Fri, 29 Dec 2006) $]
|
||||
]
|
||||
|
||||
|
||||
[section:gcd_lcm Greatest Common Divisor and Least Common Multiple]
|
||||
|
||||
[section Introduction]
|
||||
|
||||
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.
|
||||
|
||||
[endsect]
|
||||
|
||||
[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 );
|
||||
|
||||
template < unsigned long Value1, unsigned long Value2 >
|
||||
struct static_gcd;
|
||||
template < unsigned long Value1, unsigned long Value2 >
|
||||
struct static_lcm;
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
[endsect]
|
||||
|
||||
[section GCD Function Object]
|
||||
|
||||
[*Header: ] [@../../../../../boost/math/common_factor_rt.hpp <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 LCM Function Object]
|
||||
|
||||
[*Header: ] [@../../../../../boost/math/common_factor_rt.hpp <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:run_time Run-time GCD & LCM Determination]
|
||||
|
||||
[*Header: ] [@../../../../../boost/math/common_factor_rt.hpp <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:compile_time Compile time GCD and LCM determination]
|
||||
|
||||
[*Header: ] [@../../../../../boost/math/common_factor_ct.hpp <boost/math/common_factor_ct.hpp>]
|
||||
|
||||
template < unsigned long Value1, unsigned long Value2 >
|
||||
struct boost::math::static_gcd
|
||||
{
|
||||
static unsigned long const value = implementation_defined;
|
||||
};
|
||||
|
||||
template < unsigned long Value1, unsigned long Value2 >
|
||||
struct boost::math::static_lcm
|
||||
{
|
||||
static unsigned long const value = implementation_defined;
|
||||
};
|
||||
|
||||
The boost::math::static_gcd and boost::math::static_lcm class templates
|
||||
take two value-based template parameters of the unsigned long type
|
||||
and have a single static constant data member, value, of that same type.
|
||||
The value of that member 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 an unsigned long.
|
||||
|
||||
[h3 Example]
|
||||
|
||||
#include <boost/math/common_factor.hpp>
|
||||
#include <algorithm>
|
||||
#include <iterator>
|
||||
|
||||
|
||||
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, " ") );
|
||||
}
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:header Header <boost/math/common_factor.hpp>]
|
||||
|
||||
This header simply includes the headers
|
||||
[@../../../../../boost/math/common_factor_ct.hpp <boost/math/common_factor_ct.hpp>]
|
||||
and [@../../../../../boost/math/common_factor_rt.hpp <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).
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:demo Demonstration 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 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 History]
|
||||
|
||||
* 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
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Credits]
|
||||
|
||||
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.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
Reference in New Issue
Block a user