| Home | Libraries | People | FAQ | More

## Reference

### Standard C++11 Functionality

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

This header includes all the ratio related header files

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

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

This header provides forward declarations for the `<boost/ratio/ratio.hpp>` file.

    namespace boost  {

        template <std::intmax_t N, std::intmax_t D = 1> class ratio;

        // ratio arithmetic
        template <class R1, class R2> using ratio_add = /* ... */;
        template <class R1, class R2> using ratio_subtract = /* ... */;
        template <class R1, class R2> using ratio_multiply = /* ... */;
        template <class R1, class R2> using ratio_divide = /* ... */;
        template <class R1, class R2> using ratio_gcd = /* ... */;

        // 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;
    }

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

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

    template <std::intmax_t N, std::intmax_t D>
    class ratio {
    public:
        static constexpr std::intmax_t num;
        static constexpr std::intmax_t den;
        typedef ratio<num, den> type;
    };

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`

##### `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> using ratio_add = /* see below */;

`ratio_add<R1, R2>` 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> using ratio_subtract = /* see below */;

`ratio_subtract<R1, R2>` 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> using ratio_multiply = /* see below */;

`ratio_multiply<R1, R2>` is a synonym for ``ratio`<R1::num * R2::num, R1::den * R2::den>::type`.

###### `ratio_divide<>`

    template <class R1, class R2> using ratio_divide = /* see below */;

`ratio_divide<R1, R2>` is a synonym for ``ratio`<R1::num * R2::den, R2::num * R1::den>::type`.

###### `ratio_gcd<>`

This extension of the C++ standard is used by Boost.Chrono.

    template <class R1, class R2> using ratio_gcd = /* see below */;

`ratio_gcd<R1, R2>` is a synonym for `ratio<GCD(R1::num, R2::num), LCM(R1::den, R2::den)>::type`.

##### `ratio` Comparison

###### `ratio_equal<>`

    template <class R1, class R2>  struct ratio_equal
        : public std::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 std::integral_constant<bool, !ratio_equal<R1, R2>::value> {};

###### `ratio_less<>`

    template <class R1, class R2>
    struct ratio_less
        : public std::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 std::integral_constant<bool, !ratio_less<R2, R1>::value> {};

###### `ratio_greater<>`

    template <class R1, class R2> struct ratio_greater
        : public std::integral_constant<bool, ratio_less<R2, R1>::value> {};

###### `ratio_greater_equal<>`

    template <class R1, class R2> struct ratio_greater_equal
        : public std::integral_constant<bool, !ratio_less<R1, R2>::value> {};

##### SI typedefs

The International System of Units specifies twenty SI prefixes. Boost.Ratio defines all except `yocto`, `zepto`, `zetta`, and `yotta`

    // 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 I/O

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

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;

        template <> struct ratio_string<atto, char>;
        template <> struct ratio_string<atto, char16_t>;
        template <> struct ratio_string<atto, char32_t>;
        template <> struct ratio_string<atto, wchar_t>;

        template <> struct ratio_string<femto, char>;
        template <> struct ratio_string<femto, char16_t>;
        template <> struct ratio_string<femto, char32_t>;
        template <> struct ratio_string<femto, wchar_t>;

        template <> struct ratio_string<pico, char>;
        template <> struct ratio_string<pico, char16_t>;
        template <> struct ratio_string<pico, char32_t>;
        template <> struct ratio_string<pico, wchar_t>;

        template <> struct ratio_string<nano, char>;
        template <> struct ratio_string<nano, char16_t>;
        template <> struct ratio_string<nano, char32_t>;
        template <> struct ratio_string<nano, wchar_t>;

        template <> struct ratio_string<micro, char>;
        template <> struct ratio_string<micro, char16_t>;
        template <> struct ratio_string<micro, char32_t>;
        template <> struct ratio_string<micro, wchar_t>;

        template <> struct ratio_string<milli, char>;
        template <> struct ratio_string<milli, char16_t>;
        template <> struct ratio_string<milli, char32_t>;
        template <> struct ratio_string<milli, wchar_t>;

        template <> struct ratio_string<centi, char>;
        template <> struct ratio_string<centi, char16_t>;
        template <> struct ratio_string<centi, char32_t>;
        template <> struct ratio_string<centi, wchar_t>;

        template <> struct ratio_string<deci, char>;
        template <> struct ratio_string<deci, char16_t>;
        template <> struct ratio_string<deci, char32_t>;
        template <> struct ratio_string<deci, wchar_t>;

        template <> struct ratio_string<deca, char>;
        template <> struct ratio_string<deca, char16_t>;
        template <> struct ratio_string<deca, char32_t>;
        template <> struct ratio_string<deca, wchar_t>;

        template <> struct ratio_string<hecto, char>;
        template <> struct ratio_string<hecto, char16_t>;
        template <> struct ratio_string<hecto, char32_t>;
        template <> struct ratio_string<hecto, wchar_t>;

        template <> struct ratio_string<kilo, char>;
        template <> struct ratio_string<kilo, char16_t>;
        template <> struct ratio_string<kilo, char32_t>;
        template <> struct ratio_string<kilo, wchar_t>;

        template <> struct ratio_string<mega, char>;
        template <> struct ratio_string<mega, char16_t>;
        template <> struct ratio_string<mega, char32_t>;
        template <> struct ratio_string<mega, wchar_t>;

        template <> struct ratio_string<giga, char>;
        template <> struct ratio_string<giga, char16_t>;
        template <> struct ratio_string<giga, char32_t>;
        template <> struct ratio_string<giga, wchar_t>;

        template <> struct ratio_string<tera, char>;
        template <> struct ratio_string<tera, char16_t>;
        template <> struct ratio_string<tera, char32_t>;
        template <> struct ratio_string<tera, wchar_t>;

        template <> struct ratio_string<peta, char>;
        template <> struct ratio_string<peta, char16_t>;
        template <> struct ratio_string<peta, char32_t>;
        template <> struct ratio_string<peta, wchar_t>;

        template <> struct ratio_string<exa, char>;
        template <> struct ratio_string<exa, char16_t>;
        template <> struct ratio_string<exa, char32_t>;
        template <> struct ratio_string<exa, wchar_t>;

        template <> struct ratio_string<kibi, char>;
        template <> struct ratio_string<kibi, char16_t>;
        template <> struct ratio_string<kibi, char32_t>;
        template <> struct ratio_string<kibi, wchar_t>;

        template <> struct ratio_string<mebi, char>;
        template <> struct ratio_string<mebi, char16_t>;
        template <> struct ratio_string<mebi, char32_t>;
        template <> struct ratio_string<mebi, wchar_t>;

        template <> struct ratio_string<gibi, char>;
        template <> struct ratio_string<gibi, char16_t>;
        template <> struct ratio_string<gibi, char32_t>;
        template <> struct ratio_string<gibi, wchar_t>;

        template <> struct ratio_string<tebi, char>;
        template <> struct ratio_string<tebi, char16_t>;
        template <> struct ratio_string<tebi, char32_t>;
        template <> struct ratio_string<tebi, wchar_t>;

        template <> struct ratio_string<pebi, char>;
        template <> struct ratio_string<pebi, char16_t>;
        template <> struct ratio_string<pebi, char32_t>;
        template <> struct ratio_string<pebi, wchar_t>;

        template <> struct ratio_string<yobi, char>;
        template <> struct ratio_string<yobi, char16_t>;
        template <> struct ratio_string<yobi, char32_t>;
        template <> struct ratio_string<yobi, wchar_t>;

    }

##### Template Class `ratio_string<>`

    template <class Ratio, class CharT>
    struct ratio_string
    {
        static std::basic_string<CharT> symbol();
        static std::basic_string<CharT> prefix();
        static std::basic_string<CharT> short_name(); // DEPRECATED V2
        static std::basic_string<CharT> long_name(); // DEPRECATED V2
    };

The class template ratio_string provides textual representations of the associated ratio appropriate for the character type charT.

The primary template provides generic strings. Specializations provide the same static member functions but these functions return the English SI prefix and symbol names as specified by the General Conference on Weights and Measures.

###### Static Member function `prefix()`

    template<class Ratio, class CharT>
    basic_string<charT>
    ratio_string<Ratio, CharT>::prefix();

Returns: A basic_string of the form: [Ratio::num/Ratio::den]

Example: `ratio_string<ratio<2, 60>, wchar_t>::prefix()` returns `L"[1/30]"`.

###### Static Member function `symbol()`

    template<class Ratio, class CharT>
    basic_string<charT>
    ratio_string<Ratio, CharT>::symbol();

Returns: prefix().

##### Specializations for `ratio_string<>`

With compilers supporting char16_t and char32_t and with a standard library don't providing std::u16string and std::u32string you will need to define the macros BOOST_NO_CXX11_U16STRING and BOOST_NO_CXX11_U32STRING until Boost.Config defines them.

For each specialization the table gives the return value for `prefix()` and `symbol()`.

Table 32.1. The return values of specializations of ratio_string

Specialization | `prefix()` | `symbol()`
--- | --- | ---
`ratio_string<atto, char>` | `"atto"` | `"a"`
`ratio_string<atto, char16_t>` | `u"atto"` | `u"a"`
`ratio_string<atto, char32_t>` | `U"atto"` | `U"a"`
`ratio_string<atto, wchar_t>` | `L"atto"` | `L"a"`
`ratio_string<femto, char>` | `"femto"` | `"f"`
`ratio_string<femto, char16_t>` | `u"femto"` | `u"f"`
`ratio_string<femto, char32_t>` | `U"femto"` | `U"f"`
`ratio_string<femto, wchar_t>` | `L"femto"` | `L"f"`
`ratio_string<pico, char>` | `"pico"` | `"p"`
`ratio_string<pico, char16_t>` | `u"pico"` | `u"p"`
`ratio_string<pico, char32_t>` | `U"pico"` | `U"p"`
`ratio_string<pico, wchar_t>` | `L"pico"` | `L"p"`
`ratio_string<nano, char>` | `"nano"` | `"a"`
`ratio_string<nano, char16_t>` | `u"nano"` | `u"a"`
`ratio_string<nano, char32_t>` | `U"nano"` | `U"a"`
`ratio_string<nano, wchar_t>` | `L"nano"` | `L"a"`
`ratio_string<micro, char>` | `"micro"` | `u8"\u00B5"`
`ratio_string<micro, char16_t>` | `u"micro"` | `u"\u00B5"`
`ratio_string<micro, char32_t>` | `U"micro"` | `U"\u00B5"`
`ratio_string<micro, wchar_t>` | `L"micro"` | `Lu8"\u00B5"`
`ratio_string<milli, char>` | `"milli"` | `"m"`
`ratio_string<milli, char16_t>` | `u"milli"` | `u"m"`
`ratio_string<milli, char32_t>` | `U"milli"` | `U"m"`
`ratio_string<milli, wchar_t>` | `L"milli"` | `L"m"`
`ratio_string<centi, char>` | `"centi"` | `"c"`
`ratio_string<centi, char16_t>` | `u"centi"` | `u"c"`
`ratio_string<centi, char32_t>` | `U"centi"` | `U"c"`
`ratio_string<centi, wchar_t>` | `L"centi"` | `L"c"`
`ratio_string<deci, char>` | `"deci"` | `"d"`
`ratio_string<deci, char16_t>` | `u"deci"` | `u"d"`
`ratio_string<deci, char32_t>` | `U"deci"` | `U"d"`
`ratio_string<deci, wchar_t>` | `L"deci"` | `L"d"`
`ratio_string<deca, char>` | `"deca"` | `"da"`
`ratio_string<deca, char16_t>` | `u"deca"` | `u"da"`
`ratio_string<deca, char32_t>` | `U"deca"` | `U"da"`
`ratio_string<deca, wchar_t>` | `L"deca"` | `L"da"`
`ratio_string<hecto, char>` | `"hecto"` | `"h"`
`ratio_string<hecto, char16_t>` | `u"hecto"` | `u"h"`
`ratio_string<hecto, char32_t>` | `U"hecto"` | `U"h"`
`ratio_string<hecto, wchar_t>` | `L"hecto"` | `L"h"`
`ratio_string<kilo, char>` | `"kilo"` | `"k"`
`ratio_string<kilo, char16_t>` | `u"kilo"` | `u"k"`
`ratio_string<kilo, char32_t>` | `U"kilo"` | `U"k"`
`ratio_string<kilo, wchar_t>` | `L"kilo"` | `L"k"`
`ratio_string<mega, char>` | `"mega"` | `"M"`
`ratio_string<mega, char16_t>` | `u"mega"` | `u"M"`
`ratio_string<mega, char32_t>` | `U"mega"` | `U"M"`
`ratio_string<mega, wchar_t>` | `L"mega"` | `L"M"`
`ratio_string<giga, char>` | `"giga"` | `"G"`
`ratio_string<giga, char16_t>` | `u"giga"` | `u"G"`
`ratio_string<giga, char32_t>` | `U"giga"` | `U"G"`
`ratio_string<giga, wchar_t>` | `L"giga"` | `L"G"`
`ratio_string<tera, char>` | `"tera"` | `"T"`
`ratio_string<tera, char16_t>` | `u"tera"` | `u"T"`
`ratio_string<tera, char32_t>` | `U"tera"` | `U"T"`
`ratio_string<tera, wchar_t>` | `L"tera"` | `L"T"`
`ratio_string<peta, char>` | `"peta"` | `"P"`
`ratio_string<peta, char16_t>` | `u"peta"` | `u"P"`
`ratio_string<peta, char32_t>` | `U"peta"` | `U"P"`
`ratio_string<peta, wchar_t>` | `L"peta"` | `L"P"`
`ratio_string<exa, char>` | `"exa"` | `"E"`
`ratio_string<exa, char16_t>` | `u"exa"` | `u"E"`
`ratio_string<exa, char32_t>` | `U"exa"` | `U"E"`
`ratio_string<exa, wchar_t>` | `L"exa"` | `L"E"`