Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 86319a8e16.
PrevUpHomeNext

Reference

Standard C++11 Functionality
Ratio I/O

Standard C++11 Functionality

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

This header includes all the ratio related header files 

#include <boost/ratio/ratio.hpp>
#include <boost/ratio/ratio_io.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;
}
Class Template ratio<>
ratio Arithmetic
ratio Comparison
SI typedefs

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

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

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_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> {};

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>
Template Class ratio_string<>
Specializations for ratio_string<>

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

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]". 

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

Returns: prefix().

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 33.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"


Copyright © 2008 Howard Hinnant
Copyright © 2006, 2008 Beman Dawes
Copyright © 2009-2012 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)

PrevUpHomeNext