...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
This header includes all the ratio related header files
#include <boost/ratio/ratio.hpp> #include <boost/ratio/ratio_io.hpp> #include <boost/ratio/rational_constant.hpp>
This header provides forward declarations for the <boost/ratio/ratio.hpp>
file.
namespace boost { template <boost::intmax_t N, boost::intmax_t D = 1> classratio
; // ratio arithmetic template <class R1, class R2> structratio_add
; template <class R1, class R2> structratio_subtract
; template <class R1, class R2> structratio_multiply
; template <class R1, class R2> structratio_divide
; template <class R> structratio_negate
; template <class R> structratio_sign
; template <class R> structratio_abs
; template <class R1, class R2> structratio_gcd
; template <class R1, class R2> structratio_lcm
; // ratio comparison template <class R1, class R2> structratio_equal
; template <class R1, class R2> structratio_not_equal
; template <class R1, class R2> structratio_less
; template <class R1, class R2> structratio_less_equal
; template <class R1, class R2> structratio_greater
; template <class R1, class R2> structratio_greater_equal
; // convenience SI typedefs typedef ratio<1LL, 1000000000000000000LL>atto
; typedef ratio<1LL, 1000000000000000LL>femto
; typedef ratio<1LL, 1000000000000LL>pico
; typedef ratio<1LL, 1000000000LL>nano
; typedef ratio<1LL, 1000000LL>micro
; typedef ratio<1LL, 1000LL>milli
; typedef ratio<1LL, 100LL>centi
; typedef ratio<1LL, 10LL>deci
; typedef ratio< 10LL, 1LL>deca
; typedef ratio< 100LL, 1LL>hecto
; typedef ratio< 1000LL, 1LL>kilo
; typedef ratio< 1000000LL, 1LL>mega
; typedef ratio< 1000000000LL, 1LL>giga
; typedef ratio< 1000000000000LL, 1LL>tera
; typedef ratio< 1000000000000000LL, 1LL>peta
; typedef ratio<1000000000000000000LL, 1LL>exa
; }
ratio
is a facility which is useful in specifying compile-time rational constants.
Compile-time rational arithmetic is supported with protection against overflow
and divide by zero. Such a facility is very handy to efficiently represent
1/3 of a nanosecond, or to specify an inch in terms of meters (for example
254/10000 meters - which ratio
will reduce to 127/5000
meters).
// Configuration macros #defineBOOST_RATIO_USES_STATIC_ASSERT
#defineBOOST_RATIO_USES_MPL_ASSERT
#defineBOOST_RATIO_USES_ARRAY_ASSERT
#defineBOOST_RATIO_EXTENSIONS
When BOOST_NO_STATIC_ASSERT is defined, the user can select the way static assertions are reported. Define
The default behavior is as if BOOST_RATIO_USES_ARRAY_ASSERT is defined.
When BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are defined as shown:
#define BOOST_RATIO_OVERFLOW_IN_ADD "overflow in ratio add" #define BOOST_RATIO_OVERFLOW_IN_SUB "overflow in ratio sub" #define BOOST_RATIO_OVERFLOW_IN_MUL "overflow in ratio mul" #define BOOST_RATIO_OVERFLOW_IN_DIV "overflow in ratio div" #define BOOST_RATIO_NUMERATOR_IS_OUT_OF_RANGE "ratio numerator is out of range" #define BOOST_RATIO_DIVIDE_BY_0 "ratio divide by 0" #define BOOST_RATIO_DENOMINATOR_IS_OUT_OF_RANGE "ratio denominator is out of range"
Depending upon the static assertion system used, a hint as to the failing assertion will appear in some form in the compiler diagnostic output.
When BOOST_RATIO_EXTENSIONS is defined, Boost.Ratio provides in addition some extenion to the C++ standard, see below.
template <boost::intmax_t N, boost::intmax_t D> class ratio { public: static const boost::intmax_t num; static const boost::intmax_t den; typedef ratio<num, den> type; #ifdef BOOST_RATIO_EXTENSIONS typedef mpl::rational_c_tag tag; typedef boost::rational<boost::intmax_t> value_type; typedef boost::intmax_t num_type; typedef boost::intmax_t den_type; ratio() = default; template <intmax_t _N2, intmax_t _D2> ratio(const ratio<_N2, _D2>&); template <intmax_t _N2, intmax_t _D2> ratio& operator=(const ratio<_N2, _D2>&); static value_type value(); value_type operator()() const; #endif };
A diagnostic will be emitted if ratio
is instantiated with
D ==
0
, or if the absolute value of
N
or D
cannot be represented. Note: These rules
ensure that infinite ratios are avoided and that for any negative input,
there exists a representable value of its absolute value which is positive.
In a two's complement representation, this excludes the most negative
value.
The members num and den will be normalized values of the template arguments
N and D computed as follows. Let gcd
denote the greatest common divisor of N
's
absolute value and of D
's
absolute value. Then:
num
has the value
sign(N)*sign(D)*abs(N)/gcd
.
den
has the value
abs(D)/gcd
.
The nested typedef type
denotes the normalized form of this ratio
type. It should be used
when the normalized form of the template arguments are required, since
the arguments are not necessarily normalized.
Two ratio
classes
and ratio
<N1,D1>
have the same normalized form if ratio
<N2,D2>
is the same type as ratio
<N1,D1>::typeratio
<N2,D2>::type
Included only if BOOST_RATIO_EXTENSIONS is defined.
ratio()=default;
Effects: Constructs a ratio
object.
template <intmax_t N2, intmax_t D2>
ratio(const ratio
<N2, D2>& r);
Effects: Constructs a ratio
object.
Remarks: This constructor will not
participate in overload resolution unless r
has the same normalized form as *this
.
template <intmax_t N2, intmax_t D2>ratio
& operator=(constratio
<N2, D2>& r);
Effects: Assigns a ratio
object.
Returns: *this.
Remarks: This operator will not participate
in overload resolution unless r
has the same normalized form as *this
.
Included only if BOOST_RATIO_EXTENSIONS is defined.
In order to work with Boost.MPL numeric metafunctions as a Rational Constant, the following has beed added:
typedef mpl::rational_c_tag tag; typedef boost::rational<boost::intmax_t> value_type; typedef boost::intmax_t num_type; typedef boost::intmax_t den_type;
Included only if BOOST_RATIO_EXTENSIONS is defined.
static value_type value(); value_type operator()() const;
Returns: value_type(num,den);
For each of the class templates in this section, each template parameter
refers to a ratio
. If
the implementation is unable to form the indicated ratio
due to overflow, a diagnostic
will be issued.
ratio_add<>
template <class R1, class R2> struct ratio_add { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<R1::num * R2::den + R2::num * R1::den, R1::den * R2::den>::type
ratio_subtract<>
template <class R1, class R2> struct ratio_subtract { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<R1::num * R2::den - R2::num * R1::den, R1::den * R2::den>::type
ratio_multiply<>
template <class R1, class R2> struct ratio_multiply { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<R1::num * R2::num, R1::den * R2::den>::type
ratio_divide<>
template <class R1, class R2> struct ratio_divide { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<R1::num * R2::den, R2::num * R1::den>::type
ratio_negate<>
This extension of the C++ standard helps in the definition of some Boost.MPL numeric metafunctions.
template <class R> struct ratio_negate { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<-R::num, R::den>::type
ratio_abs<>
This extension of the C++ standard helps in the definition of some Boost.MPL numeric metafunctions.
template <class R> struct ratio_abs { typedef [/see below] type; };
The nested typedef type
is a synonym for
.
ratio
<abs_c<intmax_t,R::num>::value, R::den>::type
ratio_sign<>
This extension of the C++ standard helps in the definition of some Boost.MPL numeric metafunctions.
template <class R> struct ratio_sign { typedef [/see below] type; };
The nested typedef type
is a synonym for sign_c<intmax_t,R::num>::type
.
ratio_gcd<>
This extension of the C++ standard helps in the definition of some Boost.MPL numeric metafunctions.
template <class R1, class R2> struct ratio_gcd { typedef [/see below] type; };
The nested typedef type
is a synonym for ratio<gcd_c<intmax_t, R1::num, R2::num>::value, mpl::lcm_c<intmax_t, R1::den, R2::den>::value>::type
.
ratio_lcm<>
This extension of the C++ standard helps in the definition of some Boost.MPL numeric metafunctions.
template <class R1, class R2> struct ratio_lcm { typedef [/see below] type; };
The nested typedef type
is a synonym for ratio<lcm_c<intmax_t, R1::num, R2::num>::value, gcd_c<intmax_t, R1::den, R2::den>::value>::type
.
ratio_equal<>
template <class R1, class R2> struct ratio_equal : public boost::integral_constant<bool, [/see below] > {};
If R1::num == R2::num && R1::den == R2::den, ratio_equal derives from true_type, else derives from false_type.
ratio_not_equal<>
template <class R1, class R2> struct ratio_not_equal : public boost::integral_constant<bool, !ratio_equal<R1, R2>::value> {};
ratio_less<>
template <class R1, class R2> struct ratio_less : public boost::integral_constant<bool, [/see below] > {};
If R1::num * R2::den < R2::num * R1::den, ratio_less derives from true_type, else derives from false_type.
ratio_less_equal<>
template <class R1, class R2> struct ratio_less_equal : public boost::integral_constant<bool, !ratio_less<R2, R1>::value> {};
ratio_greater<>
template <class R1, class R2> struct ratio_greater : public boost::integral_constant<bool, ratio_less<R2, R1>::value> {};
ratio_greater_equal<>
template <class R1, class R2> struct ratio_greater_equal : public boost::integral_constant<bool, !ratio_less<R1, R2>::value> {};
The International
System of Units specifies twenty SI prefixes. Boost.Ratio
defines all except yocto
,
zepto
, zetta
, and yotta
// convenience SI typedefs typedefratio
<1LL, 1000000000000000000LL> atto; typedefratio
<1LL, 1000000000000000LL> femto; typedefratio
<1LL, 1000000000000LL> pico; typedefratio
<1LL, 1000000000LL> nano; typedefratio
<1LL, 1000000LL> micro; typedefratio
<1LL, 1000LL> milli; typedefratio
<1LL, 100LL> centi; typedefratio
<1LL, 10LL> deci; typedefratio
< 10LL, 1LL> deca; typedefratio
< 100LL, 1LL> hecto; typedefratio
< 1000LL, 1LL> kilo; typedefratio
< 1000000LL, 1LL> mega; typedefratio
< 1000000000LL, 1LL> giga; typedefratio
< 1000000000000LL, 1LL> tera; typedefratio
< 1000000000000000LL, 1LL> peta; typedefratio
<1000000000000000000LL, 1LL> exa;
The following are limitations of Boost.Ratio relative to the specification in the C++0x draft standard:
yocto
,
zepto
, zetta
, and yotta
-- are to be conditionally supported, if the range of intmax_t
allows, but are not supported
by Boost.Ratio.
constexpr
intmax_t
(see Ratio
values should be constexpr), but for compiler not supporting
constexpr
today,
Boost.Ratio uses static
const intmax_t
instead.
When BOOST_RATIO_EXTENSIONS
is defined
Boost.Ratio provides the following extensions:
This header provides ratio_string<>
which can generate a textual representation
of a ratio<>
in the form of a std::basic_string<>
.
These strings can be useful for I/O.
namespace boost { template <class Ratio, class CharT> struct ratio_string { static std::basic_string<CharT> short_name(); static std::basic_string<CharT> long_name(); }; }
<boost/ratio/mpl/rational_constant.hpp>
<boost/ratio/mpl/rational_c_tag.hpp>
<boost/ratio/mpl/numeric_cast.hpp>
<boost/ratio/mpl/arithmetic.hpp>
<boost/ratio/mpl/plus.hpp>
<boost/ratio/mpl/minus.hpp>
<boost/ratio/mpl/times.hpp>
<boost/ratio/mpl/divides.hpp>
<boost/ratio/mpl/gcd.hpp>
<boost/ratio/mpl/lcm.hpp>
<boost/ratio/mpl/negate.hpp>
<boost/ratio/mpl/abs.hpp>
<boost/ratio/mpl/sign.hpp>
<boost/ratio/mpl/comparison.hpp>
<boost/ratio/mpl/equal_to.hpp>
<boost/ratio/mpl/not_equal_to.hpp>
<boost/ratio/mpl/less.hpp>
<boost/ratio/mpl/less_equal.hpp>
<boost/ratio/mpl/greater.hpp>
<boost/ratio/mpl/greater_equal.hpp>
A Rational Constant is a holder class for a compile-time value of a rational type. Every Rational Constant is also a nullary Metafunction, returning itself. A rational constant object is implicitly convertible to the corresponding run-time value of the rational type.
In the following table and subsequent specifications, r is a model of Rational Constant.
Expression |
Type |
Complexity |
---|---|---|
|
|
Constant time |
|
A rational type |
Constant time |
|
An integral type |
Constant time |
|
An integral type |
Constant time |
|
An Integral constant expression |
Constant time |
|
An Integral constant expression |
Constant time |
|
Constant time |
|
|
Constant time |
Expression |
Semantics |
---|---|
|
r's tag type; r::tag::value is r's conversion rank. |
|
A cv-unqualified type of |
|
A cv-unqualified type of |
|
A cv-unqualified type of |
|
The numerator of the rational constant |
|
The denominator of the rational constant |
|
equal_to<n::type,n>::value == true. |
|
|
ratio
<>
This header includes all the rational constant related header files
#include <boost/ratio/mpl/rational_c_tag.hpp> #include <boost/ratio/mpl/numeric_cast.hpp> #include <boost/ratio/mpl/arithmetic.hpp> #include <boost/ratio/mpl/comparison.hpp>
namespace boost { namespace mpl { struct rational_c_tag : int_<10> {}; } }
namespace boost { namespace mpl { template<> struct numeric_cast< integral_c_tag,rational_c_tag >; } }
A Integral Constant is seen as a ratio with numerator the Integral Constant value and denominator 1.
template<> struct numeric_cast< integral_c_tag,rational_c_tag > { template< typename N > struct apply : ratio< N::value, 1 > { }; };
This header includes all the rational constant arithmetic MPL specializations.
#include <boost/ratio/mpl/plus.hpp> #include <boost/ratio/mpl/minus.hpp> #include <boost/ratio/mpl/times.hpp> #include <boost/ratio/mpl/divides.hpp> #include <boost/ratio/mpl/negate.hpp> #include <boost/ratio/mpl/abs.hpp> #include <boost/ratio/mpl/sign.hpp> #include <boost/ratio/mpl/gcd.hpp> #include <boost/ratio/mpl/lcm.hpp>
namespace boost { namespace mpl { template<> struct plus_impl< rational_c_tag,rational_c_tag >; } }
namespace boost { namespace mpl { template<> struct minus_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_subtract
template class.
template<>
struct plus_impl< rational_c_tag,rational_c_tag >
{
template< typename R1, typename R2 > struct apply
: ratio_subtract
<R1, R2>
{
};
};
namespace boost { namespace mpl { template<> struct times_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_multiply
template class.
template<>
struct times_impl< rational_c_tag,rational_c_tag >
{
template< typename R1, typename R2 > struct apply
: ratio_multiply
<R1, R2>
{
};
};
namespace boost { namespace mpl { template<> struct divides_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_divide
template class.
template<>
struct divides_impl< rational_c_tag,rational_c_tag >
{
template< typename R1, typename R2 > struct apply
: ratio_divide
<R1, R2>
{
};
};
namespace boost { namespace mpl { template<> struct gcd_impl< rational_c_tag,rational_c_tag >; } }
namespace boost { namespace mpl { template<> struct lcm_impl< rational_c_tag,rational_c_tag >; } }
namespace boost { namespace mpl { template<> struct negate_impl< rational_c_tag >; } }
The specialization relays on the ratio_negate
template class.
template<>
struct negate_impl< rational_c_tag >
{
template< typename R > struct apply
: ratio_negate
<R>
{
};
};
namespace boost { namespace mpl { template<> struct abs_impl< rational_c_tag >; } }
namespace boost { namespace mpl { template<> struct sign_impl< rational_c_tag >; } }
The specialization relays on the ratio_sign
template class.
template<>
struct sign_impl< rational_c_tag >
{
template< typename R > struct apply
: ratio_sign
<R>
{
};
};
This header includes all the rational constant comparison MPL specializations.
#include <boost/ratio/mpl/equal_to.hpp> #include <boost/ratio/mpl/not_equal_to.hpp> #include <boost/ratio/mpl/less.hpp> #include <boost/ratio/mpl/less_equal.hpp> #include <boost/ratio/mpl/greater.hpp> #include <boost/ratio/mpl/greater_equal.hpp>
namespace boost { namespace mpl { template<> struct equal_to_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_equal
template class.
template<>
struct equal_to_impl< rational_c_tag,rational_c_tag >
{
template< typename R1, typename R2 > struct apply
: ratio_equal
<R1, R2>
{
};
};
namespace boost { namespace mpl { template<> struct not_equal_to_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_not_equal
template class.
template<>
struct not_equal_to_impl< rational_c_tag,rational_c_tag >
{
template< typename R1, typename R2 > struct apply
: ratio_not_equal
<R1, R2>
{
};
};
namespace boost { namespace mpl { template<> struct less_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_less
template class.
template<> struct less_impl< rational_c_tag,rational_c_tag > { template< typename R1, typename R2 > struct apply : ratio_less<R1, R2> { }; };
namespace boost { namespace mpl { template<> struct less_equal_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_less_equal
template class.
template<> struct less_equal_impl< rational_c_tag,rational_c_tag > { template< typename R1, typename R2 > struct apply : ratio_less_equal<R1, R2> { }; };
namespace boost { namespace mpl { template<> struct greater_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_greater
template class.
template<> struct greater_impl< rational_c_tag,rational_c_tag > { template< typename R1, typename R2 > struct apply : ratio_greater<R1, R2> { }; };
namespace boost { namespace mpl { template<> struct greater_equal_impl< rational_c_tag,rational_c_tag >; } }
The specialization relays on the ratio_greater_equal
template
class.
template<> struct greater_equal_impl< rational_c_tag,rational_c_tag > { template< typename R1, typename R2 > struct apply : ratio_greater_equal<R1, R2> { }; };