ChapterÂ 1.Â Boost.Ratio 2.1.0

Howard Hinnant

Beman Dawes

Vicente J. Botet Escriba

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)

Overview

Motivation
Description

How to Use This Documentation

This documentation makes use of the following naming and formatting conventions.

Code is in fixed width font and is syntax-highlighted.
Replaceable text that you will need to supply is in italics.
Free functions are rendered in the code font followed by (), as in free_function().
If a name refers to a class template, it is specified like this: class_template<>; that is, it is in code font and its name is followed by <> to indicate that it is a class template.
If a name refers to a function-like macro, it is specified like this: MACRO(); that is, it is uppercase in code font and its name is followed by () to indicate that it is a function-like macro. Object-like macros appear without the trailing ().
Names that refer to concepts in the generic programming sense are specified in CamelCase.

	Note
	In addition, notes such as this one specify non-essential information that provides additional background or rationale.

Finally, you can mentally add the following to any code fragments in this document:

// Include all of Ratio files
#include <boost/ratio.hpp>
using namespace boost;

Boost.Ratio aims to implement the compile time ratio facility in C++0x, as proposed in N2661 - A Foundation to Sleep On. That document provides background and motivation for key design decisions and is the source of a good deal of information in this documentation.

Description

The Boost.Ratio library provides:

A class template, ratio, for specifying compile time rational constants such as 1/3 of a nanosecond or the number of inches per meter. ratio represents a compile time ratio of compile time constants with support for compile time arithmetic with overflow and division by zero protection.
It provides a textual representation of boost::ratio<N, D> in the form of a std::basic_string which can be useful for I/O.
Some extension related to the Rational Constant concept enabling the use of ratio<> in the context of Boost.MPL numeric metafunctions.

User's Guide

Getting Started

Installing Ratio

Tutorial

Example

SI units

External Resources

Getting Started

Installing Ratio

Installing Ratio

Getting Boost.Ratio

Boost.Ratio is in the latest Boost release in the folder /boost/ratio. Documentation, tests and examples folder are at boost/libs/ratio/.

You can also access the latest (unstable?) state from the Boost trunk directories boost/ratio and libs/ratio.

Just go to the wiki and follow the instructions there for anonymous SVN access.

Where to install Boost.Ratio?

The simple way is to decompress (or checkout from SVN) the files in your BOOST_ROOT directory.

Building Boost.Ratio

Boost.Ratio is a header only library, so no need to compile anything, you just need to include <boost/ratio.hpp>.

Requirements

Boost.Ratio depends on some Boost libraries. For these specific parts you must use either Boost version 1.39.0 or later (even older versions may work).

In particular, Boost.Ratio depends on:

Boost.Config: for configuration purposes, ...
Boost.Integer: for cstdint conformance, and integer traits ...
Boost.MPL: for MPL Assert and bool, logical ...
Boost.StaticAssert: for STATIC_ASSERT, ...
Boost.TypeTraits: for is_base, is_convertible ...
Boost.Utility/EnableIf: for enable_if, ...

Building an executable that uses Boost.Ratio

No link is needed.

Exception safety

All functions in the library are exception-neutral, providing the strong exception safety guarantee.

Thread safety

All functions in the library are thread-unsafe except when noted explicitly.

Tested compilers

Boost.Ratio should work with an C++03 conforming compiler. The current version has been tested on:

Windows with

MSVC 10.0

MinGW with

GCC 4.5.0
GCC 4.5.0 -std=c++0x
GCC 4.5.2
GCC 4.5.2 -std=c++0x
GCC 4.6.0
GCC 4.6.0 -std=c++0x

Ubuntu with * GCC 4.4.6 * GCC 4.4.6 -std=c++0x * GCC 4.5.4 * GCC 4.5.4 -std=c++0x * GCC 4.6.1 * GCC 4.6.1 -std=c++0x * Intel 12.1.3 * Intel 12.1.3 -std=c++0x

OsX with

GCC 4.1.2
GCC 4.6.2
GCC 4.6.2 -std=c++0x
GCC 4.7.0
GCC 4.7.0 -std=c++0x
GCC 4.7.1
GCC 4.7.1 -std=c++0x
clang 1.6
clang 2.9
clang 2.9 -std=c++0x
clang 3.0
clang 3.0 -std=c++0x
clang 3.1
clang 3.1 -std=c++0x
clang 3.1 -std=c++0x -stdlib=libc++
clang 3.2
clang 3.2 -std=c++11
clang 3.2 -std=c++11 -stdlib=libc++

	Note
	Please let us know how this works on other platforms/compilers.

	Note
	Please send any questions, comments and bug reports to boost <at> lists <dot> boost <dot> org.

Tutorial

Ratio

ratio is a general purpose utility inspired by Walter Brown allowing one to easily and safely compute rational values at compile-time. The ratio class catches all errors (such as divide by zero and overflow) at compile time. It is used in the duration and time_point classes to efficiently create units of time. It can also be used in other "quantity" libraries or anywhere there is a rational constant which is known at compile-time. The use of this utility can greatly reduce the chances of run-time overflow because the ratio (and any ratios resulting from ratio arithmetic) are always reduced to the lowest terms.

ratio is a template taking two intmax_ts, with the second defaulted to 1. In addition to copy constructors and assignment, it only has two public members, both of which are static const intmax_t. One is the numerator of the ratio and the other is the denominator. The ratio is always normalized such that it is expressed in lowest terms, and the denominator is always positive. When the numerator is 0, the denominator is always 1.

Example:

typedef ratio<5, 3>   five_thirds;
// five_thirds::num == 5, five_thirds::den == 3

typedef ratio<25, 15> also_five_thirds;
// also_five_thirds::num == 5, also_five_thirds::den == 3

typedef ratio_divide<five_thirds, also_five_thirds>::type one;
// one::num == 1, one::den == 1

This facility also includes convenience typedefs for the SI prefixes atto through exa corresponding to their internationally recognized definitions (in terms of ratio). This is a tremendous syntactic convenience. It will prevent errors in specifying constants as one no longer has to double count the number of zeros when trying to write millions or billions.

Example:

typedef ratio_multiply<ratio<5>, giga>::type _5giga;
// _5giga::num == 5000000000, _5giga::den == 1

typedef ratio_multiply<ratio<5>, nano>::type _5nano;
// _5nano::num == 1, _5nano::den == 200000000

Ratio I/O

For each ratio<N, D> there exists a ratio_string<ratio<N, D>, CharT> for which you can query two strings: symbol and prefix. For those ratio's that correspond to an SI prefix prefix corresponds to the internationally recognized prefix, stored as a basic_string<CharT>. For example ratio_string<mega, char>::prefix() returns string("mega"). For those ratios that correspond to an SI prefix symbol corresponds to the internationally recognized symbol, stored as a basic_string<CharT>. For example, ratio_string<mega, char>::symbol() returns string("M"). For all other ratios, both prefix() and symbol() return a basic_string containing "[ratio::num/ratio::den]".

ratio_string<ratio<N, D>, CharT> is only defined for four character types:

char: UTF-8
char16_t: UTF-16
char32_t: UTF-32
wchar_t: UTF-16 (if wchar_t is 16 bits) or UTF-32

When the character is char, UTF-8 will be used to encode the names. When the character is char16_t, UTF-16 will be used to encode the names. When the character is char32_t, UTF-32 will be used to encode the names. When the character is wchar_t, the encoding will be UTF-16 if wchar_t is 16 bits, and otherwise UTF-32.

The symbol (Greek mu or Î¼) for micro is defined by Unicode to be U+00B5.

Examples:

#include <boost/ratio/ratio_io.hpp>
#include <iostream>

int main()
{
    using namespace std;
    using namespace boost;

    cout << "ratio_string<deca, char>::prefix() = "
         <<  ratio_string<deca, char>::prefix() << '\n';
    cout << "ratio_string<deca, char>::symbol() = "
         <<  ratio_string<deca, char>::symbol() << '\n';

    cout << "ratio_string<giga, char>::prefix() = "
         <<  ratio_string<giga, char>::prefix() << '\n';
    cout << "ratio_string<giga, char>::symbol() = "
         <<  ratio_string<giga, char>::symbol() << '\n';

    cout << "ratio_string<ratio<4, 6>, char>::prefix() = "
         <<  ratio_string<ratio<4, 6>, char>::prefix() << '\n';
    cout << "ratio_string<ratio<4, 6>, char>::symbol() = "
         <<  ratio_string<ratio<4, 6>, char>::symbol() << '\n';
}

The output will be

ratio_string<deca, char>::prefix() = deca
ratio_string<deca, char>::symbol() = da
ratio_string<giga, char>::prefix() = giga
ratio_string<giga, char>::symbol() = G
ratio_string<ratio<4, 6>, char>::prefix() = [2/3]
ratio_string<ratio<4, 6>, char>::symbol() = [2/3]

Ratio MPL Numeric Metafunctions

With the view of the _ratio class as a Rational Constant we can mix _ratio<> and Boost.MPL Integral Constants in the same expression, as in

typedef mpl::times<int_<5>, giga>::type _5giga;
// _5giga::num == 5000000000, _5giga::den == 1

typedef mpl::times<int_<5>, nano>::type _5nano;
// _5nano::num == 1, _5nano::den == 200000000

Example

SI units

SI units

This example illustrates the use of type-safe physics code interoperating with boost::chrono::duration types, taking advantage of the Boost.Ratio infrastructure and design philosophy.

Let's start by defining a length class template that mimics boost::chrono::duration, which represents a time duration in various units, but restricts the representation to double and uses Boost.Ratio for length unit conversions:

template <class Ratio>
class length {
private:
    double len_;
public:
    typedef Ratio ratio;
    length() : len_(1) {}
    length(const double& len) : len_(len) {}

    template <class R>
    length(const length<R>& d)
            : len_(d.count() * boost::ratio_divide<Ratio, R>::type::den /
                               boost::ratio_divide<Ratio, R>::type::num) {}

    double count() const {return len_;}

    length& operator+=(const length& d) {len_ += d.count(); return *this;}
    length& operator-=(const length& d) {len_ -= d.count(); return *this;}

    length operator+() const {return *this;}
    length operator-() const {return length(-len_);}

    length& operator*=(double rhs) {len_ *= rhs; return *this;}
    length& operator/=(double rhs) {len_ /= rhs; return *this;}
};

Here's a small sampling of length units:

typedef length<boost::ratio<1> >          meter;        // set meter as "unity"
typedef length<boost::centi>              centimeter;   // 1/100 meter
typedef length<boost::kilo>               kilometer;    // 1000  meters
typedef length<boost::ratio<254, 10000> > inch;         // 254/10000 meters

Note that since length's template parameter is actually a generic ratio type, so we can use boost::ratio allowing for more complex length units:

typedef length<boost::ratio_multiply<boost::ratio<12>, inch::ratio>::type>   foot;  // 12 inchs
typedef length<boost::ratio_multiply<boost::ratio<5280>, foot::ratio>::type> mile;  // 5280 feet

Now we need a floating point-based definition of seconds:

typedef boost::chrono::duration<double> seconds;                         // unity

We can even support sub-nanosecond durations:

typedef boost::chrono::duration<double,  boost::pico> picosecond;  // 10^-12 seconds
typedef boost::chrono::duration<double, boost::femto> femtosecond; // 10^-15 seconds
typedef boost::chrono::duration<double,  boost::atto> attosecond;  // 10^-18 seconds

Finally, we can write a proof-of-concept of an SI units library, hard-wired for meters and floating point seconds, though it will accept other units:

template <class R1, class R2>
class quantity
{
    double q_;
public:
    typedef R1 time_dim;
    typedef R2 distance_dim;
    quantity() : q_(1) {}

    double get() const {return q_;}
    void set(double q) {q_ = q;}
};

template <>
class quantity<boost::ratio<1>, boost::ratio<0> >
{
    double q_;
public:
    quantity() : q_(1) {}
    quantity(seconds d) : q_(d.count()) {}  // note:  only User1::seconds needed here

    double get() const {return q_;}
    void set(double q) {q_ = q;}
};

template <>
class quantity<boost::ratio<0>, boost::ratio<1> >
{
    double q_;
public:
    quantity() : q_(1) {}
    quantity(meter d) : q_(d.count()) {}  // note:  only User1::meter needed here

    double get() const {return q_;}
    void set(double q) {q_ = q;}
};

template <>
class quantity<boost::ratio<0>, boost::ratio<0> >
{
    double q_;
public:
    quantity() : q_(1) {}
    quantity(double d) : q_(d) {}

    double get() const {return q_;}
    void set(double q) {q_ = q;}
};

That allows us to create some useful SI-based unit types:

typedef quantity<boost::ratio<0>, boost::ratio<0> >  Scalar;
typedef quantity<boost::ratio<1>, boost::ratio<0> >  Time;         // second
typedef quantity<boost::ratio<0>, boost::ratio<1> >  Distance;     // meter
typedef quantity<boost::ratio<-1>, boost::ratio<1> > Speed;        // meter/second
typedef quantity<boost::ratio<-2>, boost::ratio<1> > Acceleration; // meter/second^2

To make quantity useful, we need to be able to do arithmetic:

template <class R1, class R2, class R3, class R4>
quantity<typename boost::ratio_subtract<R1, R3>::type,
         typename boost::ratio_subtract<R2, R4>::type>
operator/(const quantity<R1, R2>& x, const quantity<R3, R4>& y)
{
    typedef quantity<typename boost::ratio_subtract<R1, R3>::type,
                    typename boost::ratio_subtract<R2, R4>::type> R;
    R r;
    r.set(x.get() / y.get());
    return r;
}

template <class R1, class R2, class R3, class R4>
quantity<typename boost::ratio_add<R1, R3>::type,
         typename boost::ratio_add<R2, R4>::type>
operator*(const quantity<R1, R2>& x, const quantity<R3, R4>& y)
{
    typedef quantity<typename boost::ratio_add<R1, R3>::type,
                    typename boost::ratio_add<R2, R4>::type> R;
    R r;
    r.set(x.get() * y.get());
    return r;
}

template <class R1, class R2>
quantity<R1, R2>
operator+(const quantity<R1, R2>& x, const quantity<R1, R2>& y)
{
    typedef quantity<R1, R2> R;
    R r;
    r.set(x.get() + y.get());
    return r;
}

template <class R1, class R2>
quantity<R1, R2>
operator-(const quantity<R1, R2>& x, const quantity<R1, R2>& y)
{
    typedef quantity<R1, R2> R;
    R r;
    r.set(x.get() - y.get());
    return r;
}

With all of the foregoing scaffolding, we can now write an exemplar of a type-safe physics function:

Distance
compute_distance(Speed v0, Time t, Acceleration a)
{
    return v0 * t + Scalar(.5) * a * t * t;  // if a units mistake is made here it won't compile
}

Finally, we can exercise what we've created, even using custom time durations (User1::seconds) as well as Boost time durations (boost::chrono::hours). The input can be in arbitrary, though type-safe, units, the output is always in SI units. (A complete Units library would support other units, of course.)

int main()
{
    typedef boost::ratio<8, BOOST_INTMAX_C(0x7FFFFFFFD)> R1;
    typedef boost::ratio<3, BOOST_INTMAX_C(0x7FFFFFFFD)> R2;
    typedef User1::quantity<boost::ratio_subtract<boost::ratio<0>, boost::ratio<1> >::type,
                             boost::ratio_subtract<boost::ratio<1>, boost::ratio<0> >::type > RR;
    typedef boost::ratio_subtract<R1, R2>::type RS;
    std::cout << RS::num << '/' << RS::den << '\n';


    std::cout << "*************\n";
    std::cout << "* testUser1 *\n";
    std::cout << "*************\n";
    User1::Distance d( User1::mile(110) );
    User1::Time t( boost::chrono::hours(2) );

    RR r=d / t;
    //r.set(d.get() / t.get());

    User1::Speed rc= r;

    User1::Speed s = d / t;
    std::cout << "Speed = " << s.get() << " meters/sec\n";
    User1::Acceleration a = User1::Distance( User1::foot(32.2) ) / User1::Time() / User1::Time();
    std::cout << "Acceleration = " << a.get() << " meters/sec^2\n";
    User1::Distance df = compute_distance(s, User1::Time( User1::seconds(0.5) ), a);
    std::cout << "Distance = " << df.get() << " meters\n";
    std::cout << "There are "
        << User1::mile::ratio::den << '/' << User1::mile::ratio::num << " miles/meter";
    User1::meter mt = 1;
    User1::mile mi = mt;
    std::cout << " which is approximately " << mi.count() << '\n';
    std::cout << "There are "
        << User1::mile::ratio::num << '/' << User1::mile::ratio::den << " meters/mile";
    mi = 1;
    mt = mi;
    std::cout << " which is approximately " << mt.count() << '\n';
    User1::attosecond as(1);
    User1::seconds sec = as;
    std::cout << "1 attosecond is " << sec.count() << " seconds\n";
    std::cout << "sec = as;  // compiles\n";
    sec = User1::seconds(1);
    as = sec;
    std::cout << "1 second is " << as.count() << " attoseconds\n";
    std::cout << "as = sec;  // compiles\n";
    std::cout << "\n";
    return 0;
}

See the source file example/si_physics.cpp

External Resources

C++ Standards Committee's current Working Paper: The most authoritative reference material for the library is the C++ Standards Committee's current Working Paper (WP). 20.6 Compile-time rational arithmetic "ratio"
N2661 - A Foundation to Sleep On: From Howard E. Hinnant, Walter E. Brown, Jeff Garland and Marc Paterno. Is very informative and provides motivation for key design decisions
LWG 1281. CopyConstruction and Assignment between ratios having the same normalized form: From Vicente Juan Botet Escriba.

Reference

Header <boost/ratio/config.hpp>

Extensions
Deprecated
Version
Static Assert

C++0x Recommendation

Header <boost/ratio.hpp>
Header <boost/ratio/ratio_fwd.hpp>
Header <boost/ratio/ratio.hpp>

Ratio I/O

Header <boost/ratio/ratio_io.hpp>

Rational Constant

Rational Constant Concept
Header <boost/ratio/mpl/rational_constant.hpp>
Header <boost/ratio/mpl/rational_c_tag.hpp>
Header <boost/ratio/mpl/numeric_cast.hpp>
Header <boost/ratio/mpl/arithmetic.hpp>
Header <boost/ratio/mpl/plus.hpp>
Header <boost/ratio/mpl/minus.hpp>
Header <boost/ratio/mpl/times.hpp>
Header <boost/ratio/mpl/divides.hpp>
Header <boost/ratio/mpl/gcd.hpp>
Header <boost/ratio/mpl/lcm.hpp>
Header <boost/ratio/mpl/negate.hpp>
Header <boost/ratio/mpl/abs.hpp>
Header <boost/ratio/mpl/sign.hpp>
Header <boost/ratio/mpl/comparison.hpp>
Header <boost/ratio/mpl/equal_to.hpp>
Header <boost/ratio/mpl/not_equal_to.hpp>
Header <boost/ratio/mpl/less.hpp>
Header <boost/ratio/mpl/less_equal.hpp>
Header <boost/ratio/mpl/greater.hpp>
Header <boost/ratio/mpl/greater_equal.hpp>

Header `<boost/ratio/config.hpp>`

Extensions
Deprecated
Version
Static Assert

// Configuration macros
#define BOOST_RATIO_VERSION 
#define BOOST_RATIO_EXTENSIONS
#define BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0
#define BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 
#define BOOST_RATIO_USES_STATIC_ASSERT
#define BOOST_RATIO_USES_MPL_ASSERT
#define BOOST_RATIO_USES_ARRAY_ASSERT

Extensions

When BOOST_RATIO_EXTENSIONS is defined, Boost.Ratio provides in addition some extension to the C++ standard, see below.

Deprecated

When BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined the deprecated features stated as DEPRECATED V2 are provided.

When BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined the deprecated features stated as DEPRECATED V2 are NOT provided.

Version

BOOST_RATIO_VERSION stands for the Boost.Ratio version which can be 1 or 2. The default up to 1.55 is version 1. Since 1.56 it will be 2.

When BOOST_RATIO_VERSION is 1 BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined by default.

When BOOST_RATIO_VERSION is 2 BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined by default.

Static Assert

When BOOST_NO_STATIC_ASSERT is defined, the user can select the way static assertions are reported. Define

BOOST_RATIO_USES_STATIC_ASSERT to use Boost.StaticAssert.
BOOST_RATIO_USES_MPL_ASSERT to use Boost.MPL static assertions.
BOOST_RATIO_USES_ARRAY_ASSERT to use Boost.Ratio internal static assertions.

The default behavior is as if BOOST_RATIO_USES_ARRAY_ASSERT was 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.

C++0x Recommendation

Header <boost/ratio.hpp>

Header <boost/ratio/ratio_fwd.hpp>

Header <boost/ratio/ratio.hpp>

Class Template ratio<>
ratio Arithmetic
ratio Comparison
SI typedefs
IEC typedefs
Limitations
Extensions

Header `<boost/ratio.hpp>`

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>

Header `<boost/ratio/ratio_fwd.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> class ratio;

    // ratio arithmetic
    template <class R1, class R2> struct ratio_add;
    template <class R1, class R2> struct ratio_subtract;
    template <class R1, class R2> struct ratio_multiply;
    template <class R1, class R2> struct ratio_divide;
#ifdef BOOST_RATIO_EXTENSIONS
    template <class R,int P> struct ratio_power;
    template <class R> struct ratio_negate;
    template <class R> struct ratio_sign;
    template <class R> struct ratio_abs;
    template <class R1, class R2> struct ratio_gcd;
    template <class R1, class R2> struct ratio_lcm;
#endif

    // ratio comparison
    template <class R1, class R2> struct ratio_equal;
    template <class R1, class R2> struct ratio_not_equal;
    template <class R1, class R2> struct ratio_less;
    template <class R1, class R2> struct ratio_less_equal;
    template <class R1, class R2> struct ratio_greater;
    template <class R1, class R2> struct ratio_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;

#ifdef BOOST_RATIO_EXTENSIONS
    // convenience IEC typedefs
    typedef ratio<                                   1024LL> kibi;
    typedef ratio<                            1024LL*1024LL> mebi;
    typedef ratio<                     1024LL*1024LL*1024LL> gibi;
    typedef ratio<              1024LL*1024LL*1024LL*1024LL> tebi;
    typedef ratio<       1024LL*1024LL*1024LL*1024LL*1024LL> pebi;
    typedef ratio<1024LL*1024LL*1024LL*1024LL*1024LL*1024LL> exbi;
#endif
}

Header `<boost/ratio/ratio.hpp>`

Class Template ratio<>
ratio Arithmetic
ratio Comparison
SI typedefs
IEC typedefs
Limitations
Extensions

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

Class Template `ratio<>`

Construction and Assignment
MPL Numeric Metafunctions
Observers

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 ratio<N1,D1> and ratio<N2,D2> have the same normalized form if ratio<N1,D1>::type is the same type as ratio<N2,D2>::type

Construction and Assignment

Included only if BOOST_RATIO_EXTENSIONS is defined.

Default Constructor

ratio()=default;

Effects: Constructs a ratio object.

Copy Constructor

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.

Assignement

template <intmax_t N2, intmax_t D2>
  ratio& operator=(const ratio<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.

MPL Numeric Metafunctions

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;

Observers

Included only if BOOST_RATIO_EXTENSIONS is defined.

static value_type value();
value_type operator()() const;

Returns: value_type(num,den);

`ratio` Arithmetic

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_power<>`

Included only if BOOST_RATIO_EXTENSIONS is defined.

template <class R, int P> struct ratio_power {
   typedef  [/see below]  type;
};

The nested typedef type is a synonym for R* *R P times.