mirror of
https://github.com/boostorg/ratio.git
synced 2025-05-09 23:24:01 +00:00
Boost.Ratio: Update doc with new Rational Constant feature
[SVN r67787]
This commit is contained in:
Vicente J. Botet Escriba
parent
5e0d91410c
commit
6d066021af
BIN
doc/ratio.pdf
BIN
doc/ratio.pdf
Binary file not shown.
431
doc/ratio.qbk
431
doc/ratio.qbk
@ -9,7 +9,7 @@
|
||||
|
||||
[article Boost.Ratio
|
||||
[quickbook 1.5]
|
||||
[version 1.0.0]
|
||||
[version 1.0.1]
|
||||
[authors [Hinnant, Howard]]
|
||||
[authors [Dawes, Beman]]
|
||||
[authors [Botet Escriba, Vicente J.]]
|
||||
@ -24,7 +24,7 @@
|
||||
]
|
||||
|
||||
[/==================]
|
||||
[def __Boost_Ratio__ [*Boost.Ratio]]
|
||||
[def __Boost_Ratio [*Boost.Ratio]]
|
||||
|
||||
[/===============================================]
|
||||
|
||||
@ -45,6 +45,11 @@
|
||||
[def __ratio_subtract [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_subtract`]]
|
||||
[def __ratio_multiply [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_multiply`]]
|
||||
[def __ratio_divide [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_divide`]]
|
||||
[def __ratio_negate [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_negate`]]
|
||||
[def __ratio_abs [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_abs`]]
|
||||
[def __ratio_sign [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_sign`]]
|
||||
[def __ratio_gcd [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_gcd`]]
|
||||
[def __ratio_lcm [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_lcm`]]
|
||||
|
||||
|
||||
[template ratio_comparison[link_text] [link boost_ratio.reference.ratio_hpp.ratio_comparison [link_text]]]
|
||||
@ -76,6 +81,9 @@
|
||||
|
||||
[template mu[]'''μ'''] [/ µ Greek small letter mu]
|
||||
|
||||
[def __Rational_Constant [link boost_ratio.reference.rational_constant Rational Constant]]
|
||||
|
||||
|
||||
[/warning Ratio is not part of the Boost libraries.]
|
||||
|
||||
[/===============]
|
||||
@ -109,7 +117,7 @@ Finally, you can mentally add the following to any code fragments in this docume
|
||||
[section Motivation]
|
||||
[/=================]
|
||||
|
||||
__Boost_Ratio__ aims to implement the compile time ratio facility in C++0x, as proposed in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*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.
|
||||
__Boost_Ratio aims to implement the compile time ratio facility in C++0x, as proposed in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*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.
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -117,12 +125,14 @@ __Boost_Ratio__ aims to implement the compile time ratio facility in C++0x, as p
|
||||
[section Description]
|
||||
[/==================]
|
||||
|
||||
The __Boost_Ratio__ library provides:
|
||||
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.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
@ -146,7 +156,7 @@ The __Boost_Ratio__ library provides:
|
||||
|
||||
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 [@https://svn.boost.org/svn/boost-trunk/ratio Boost trunk] directories boost/ratio and libs/ratio. Just go to [@http://svn.boost.org/trac/boost/wiki/BoostSubversion here] and follow the instructions there for anonymous SVN access.
|
||||
You can also access the latest (unstable?) state from the [@https://svn.boost.org/svn/boost-trunk Boost trunk] directories boost/ratio and libs/ratio. Just go to [@http://svn.boost.org/trac/boost/wiki/BoostSubversion here] and follow the instructions there for anonymous SVN access.
|
||||
|
||||
[/==========================================]
|
||||
[heading Where to install Boost.Ratio? ]
|
||||
@ -158,16 +168,16 @@ The simple way is to decompress (or checkout from SVN) the files in your BOOST_R
|
||||
[heading Building Boost.Ratio ]
|
||||
[/=================================]
|
||||
|
||||
__Boost_Ratio__ is a header only library, so no need to compile anything, you just need to `include <boost/ratio.hpp>`.
|
||||
__Boost_Ratio is a header only library, so no need to compile anything, you just need to `include <boost/ratio.hpp>`.
|
||||
|
||||
|
||||
[/===================]
|
||||
[heading 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).
|
||||
__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:
|
||||
In particular, __Boost_Ratio depends on:
|
||||
|
||||
[variablelist
|
||||
[
|
||||
@ -192,7 +202,7 @@ In particular, __Boost_Ratio__ depends on:
|
||||
|
||||
|
||||
[/=========================================================]
|
||||
[heading Building an executable that uses __Boost_Ratio__ ]
|
||||
[heading Building an executable that uses __Boost_Ratio ]
|
||||
[/=========================================================]
|
||||
|
||||
No link is needed.
|
||||
@ -214,7 +224,7 @@ All functions in the library are thread-unsafe except when noted explicitly.
|
||||
[heading Tested compilers ]
|
||||
[/========================]
|
||||
|
||||
__Boost_Ratio__ should work with an C++03 conforming compiler. The current version has been tested on:
|
||||
__Boost_Ratio should work with an C++03 conforming compiler. The current version has been tested on:
|
||||
|
||||
Windows with
|
||||
|
||||
@ -222,23 +232,23 @@ Windows with
|
||||
* MSVC 9.0 Express
|
||||
* MSVC 8.0
|
||||
|
||||
[/* Intel 11.0]
|
||||
|
||||
Scientific Linux with
|
||||
|
||||
* GCC 4.1.2
|
||||
|
||||
Cygwin with
|
||||
Cygwin 1.5 with
|
||||
|
||||
* GCC 3.4.4
|
||||
* GCC 4.3.2
|
||||
|
||||
Cygwin 1.7 with
|
||||
|
||||
* GCC 4.3.4
|
||||
|
||||
MinGW with
|
||||
|
||||
* GCC 4.4.0
|
||||
* GCC 4.5.0
|
||||
* GCC 4.5.0 -std=c++0x
|
||||
* GCC 4.6.0
|
||||
* GCC 4.6.0 -std=c++0x
|
||||
|
||||
Initial version was tested on:
|
||||
Initial versions were tested on:
|
||||
|
||||
MacOS with GCC 4.2.4
|
||||
|
||||
@ -249,18 +259,6 @@ Ubuntu Linux with GCC 4.2.4
|
||||
[note Please send any questions, comments and bug reports to boost <at> lists <dot> boost <dot> org.]
|
||||
|
||||
[endsect]
|
||||
[/
|
||||
[/====================]
|
||||
[section Hello World! ]
|
||||
[/====================]
|
||||
|
||||
If all you want to do is to time a program's execution, here is a complete program (stopclock_example.cpp):
|
||||
|
||||
#include <boost/ratio.hpp>
|
||||
|
||||
|
||||
[endsect]
|
||||
]
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -342,7 +340,19 @@ The output will be
|
||||
ratio_string<giga, char>::short_name() = G
|
||||
ratio_string<ratio<4, 6>, char>::long_name() = [2/3]
|
||||
ratio_string<ratio<4, 6>, char>::short_name() = [2/3]
|
||||
|
||||
|
||||
[heading 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
|
||||
|
||||
|
||||
[endsect]
|
||||
[/===============]
|
||||
[section:Examples Example]
|
||||
@ -352,9 +362,9 @@ The output will be
|
||||
[section 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.
|
||||
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:
|
||||
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>
|
||||
@ -611,11 +621,23 @@ Finally, we can exercise what we've created, even using custom time durations (`
|
||||
[section:reference Reference ]
|
||||
[/=================]
|
||||
|
||||
[/===========================================]
|
||||
[section:ratio_fwdhpp Header `<boost/ratio_fwd.hpp>`]
|
||||
[/===========================================]
|
||||
[/=================================================]
|
||||
[section:ratio_ratio_hpp Header `<boost/ratio.hpp>`]
|
||||
[/=================================================]
|
||||
|
||||
This header provides forward declarations for the `<boost/ratio.hpp>` file.
|
||||
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>
|
||||
|
||||
[endsect]
|
||||
|
||||
[/========================================================]
|
||||
[section:ratio_fwdhpp Header `<boost/ratio/ratio_fwd.hpp>`]
|
||||
[/========================================================]
|
||||
|
||||
This header provides forward declarations for the `<boost/ratio/ratio.hpp>` file.
|
||||
|
||||
namespace boost {
|
||||
|
||||
@ -626,6 +648,11 @@ This header provides forward declarations for the `<boost/ratio.hpp>` file.
|
||||
template <class R1, class R2> struct __ratio_subtract;
|
||||
template <class R1, class R2> struct __ratio_multiply;
|
||||
template <class R1, class R2> struct __ratio_divide;
|
||||
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;
|
||||
|
||||
// ratio comparison
|
||||
template <class R1, class R2> struct __ratio_equal;
|
||||
@ -656,9 +683,9 @@ This header provides forward declarations for the `<boost/ratio.hpp>` file.
|
||||
|
||||
[endsect]
|
||||
|
||||
[/===========================================]
|
||||
[section:ratio_hpp Header `<boost/ratio.hpp>`]
|
||||
[/===========================================]
|
||||
[/=================================================]
|
||||
[section:ratio_hpp 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).
|
||||
|
||||
@ -666,6 +693,7 @@ __ratio is a facility which is useful in specifying compile-time rational consta
|
||||
#define __BOOST_RATIO_USES_STATIC_ASSERT
|
||||
#define __BOOST_RATIO_USES_MPL_ASSERT
|
||||
#define __BOOST_RATIO_USES_ARRAY_ASSERT
|
||||
#define __BOOST_RATIO_EXTENSIONS
|
||||
|
||||
|
||||
[section:conf Configuration Macros]
|
||||
@ -673,8 +701,8 @@ __ratio is a facility which is useful in specifying compile-time rational consta
|
||||
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_RATIO_ASSERT to use __Boost_Ratio__ static assertions.
|
||||
* BOOST_RATIO_USES_MPL_ASSERT to use [*Boost.MPL] static assertions.
|
||||
* BOOST_RATIO_USES_RATIO_ASSERT to use __Boost_Ratio static assertions.
|
||||
|
||||
The default behavior is as if BOOST_RATIO_USES_ARRAY_ASSERT is defined.
|
||||
|
||||
@ -690,6 +718,9 @@ When BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are define
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:ratio Class Template `ratio<>`]
|
||||
@ -701,13 +732,23 @@ Depending upon the static assertion system used, a hint as to the failing assert
|
||||
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>&) {return *this;}
|
||||
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.
|
||||
@ -725,6 +766,16 @@ Two __ratio classes `__ratio<N1,D1>` and `__ratio<N2,D2>` have the same normaliz
|
||||
|
||||
[section:ca Construction and Assignment]
|
||||
|
||||
Included only if BOOST_RATIO_EXTENSIONS is defined.
|
||||
|
||||
[heading Default Constructor]
|
||||
|
||||
ratio()=default;
|
||||
|
||||
[*Effects:] Constructs a __ratio object.
|
||||
|
||||
[heading Copy Constructor]
|
||||
|
||||
template <intmax_t N2, intmax_t D2>
|
||||
ratio(const __ratio<N2, D2>& r);
|
||||
|
||||
@ -732,6 +783,8 @@ Two __ratio classes `__ratio<N1,D1>` and `__ratio<N2,D2>` have the same normaliz
|
||||
|
||||
[*Remarks:] This constructor will not participate in overload resolution unless `r` has the same normalized form as `*this`.
|
||||
|
||||
[heading Assignement]
|
||||
|
||||
template <intmax_t N2, intmax_t D2>
|
||||
__ratio& operator=(const __ratio<N2, D2>& r);
|
||||
|
||||
@ -743,6 +796,28 @@ Two __ratio classes `__ratio<N1,D1>` and `__ratio<N2,D2>` have the same normaliz
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:mpl 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;
|
||||
[endsect]
|
||||
|
||||
[section:obs Observers]
|
||||
|
||||
Included only if BOOST_RATIO_EXTENSIONS is defined.
|
||||
|
||||
static value_type value();
|
||||
value_type operator()() const;
|
||||
|
||||
[*Returns:] value_type(num,den);
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -783,6 +858,57 @@ The nested typedef `type` is a synonym for `__ratio<R1::num * R2::num, R1::den *
|
||||
|
||||
The nested typedef `type` is a synonym for `__ratio<R1::num * R2::den, R2::num * R1::den>::type`.
|
||||
|
||||
[heading `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`.
|
||||
|
||||
[heading `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`.
|
||||
|
||||
[heading `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`.
|
||||
|
||||
[heading `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`.
|
||||
|
||||
[heading `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`.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:ratio_comparison `ratio` Comparison]
|
||||
@ -827,7 +953,7 @@ If R1::num * R2::den < R2::num * R1::den, ratio_less derives from true_type, els
|
||||
|
||||
[section:ratio_si_typedefs SI typedefs]
|
||||
|
||||
The [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes International System of Units] specifies twenty SI prefixes. __Boost_Ratio__ defines all except `yocto`, `zepto`, `zetta`, and `yotta`
|
||||
The [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes 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;
|
||||
@ -854,8 +980,8 @@ The [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes International S
|
||||
|
||||
The following are limitations of Boost.Ratio relative to the specification in the C++0x draft standard:
|
||||
|
||||
* Four of the SI units typedefs -- `yocto`, `zepto`, `zetta`, and `yotta` -- are to be conditionally supported, if the range of `intmax_t` allows, but are not supported by __Boost_Ratio__.
|
||||
* Ratio values should be of type static `constexpr intmax_t` (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#1121 Ratio values should be constexpr]), but no compiler supports `constexpr` today, so __Boost_Ratio__ uses `static const intmax_t` instead.
|
||||
* Four of the SI units typedefs -- `yocto`, `zepto`, `zetta`, and `yotta` -- are to be conditionally supported, if the range of `intmax_t` allows, but are not supported by __Boost_Ratio.
|
||||
* Ratio values should be of type static `constexpr intmax_t` (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#1122 Ratio values should be constexpr]), but for compiler not supporting `constexpr` today, __Boost_Ratio uses `static const intmax_t` instead.
|
||||
* Rational arithmetic should use template aliases (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3134.html#921 Rational Arithmetic should use template aliases]), but those are not available in C++03, so inheritance is used instead.
|
||||
|
||||
The current implementation extends the requirements of the C++0x draft standard by making the copy constructor and copy assignment operator have the same normalized form (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3133.html#1281 copy constructor and assignment between ratios having the same normalized form]).
|
||||
@ -864,24 +990,213 @@ The current implementation extends the requirements of the C++0x draft standard
|
||||
|
||||
[endsect]
|
||||
|
||||
[/===========================================]
|
||||
[section:ratio_io_hpp Header `<boost/ratio_io.hpp>`]
|
||||
[/===========================================]
|
||||
[/=======================================================]
|
||||
[section:ratio_io_hpp 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
|
||||
{
|
||||
static std::basic_string<CharT> short_name();
|
||||
static std::basic_string<CharT> long_name();
|
||||
};
|
||||
|
||||
}
|
||||
|
||||
[endsect]
|
||||
|
||||
[/===========================================]
|
||||
[section:rational_constant Rational Constant Concept]
|
||||
[/===========================================]
|
||||
|
||||
[heading Description]
|
||||
|
||||
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.
|
||||
|
||||
[heading Expression requirements]
|
||||
|
||||
In the following table and subsequent specifications, r is a model of __Rational_Constant.
|
||||
|
||||
[table
|
||||
[[Expression][Type] [Complexity]]
|
||||
[[`r::tag`][`rational_c_tag`] [Constant time]]
|
||||
[[`r::value_type`][A rational type] [Constant time]]
|
||||
[[`r::num_type`][An integral type] [Constant time]]
|
||||
[[`r::den_type`][An integral type] [Constant time]]
|
||||
[[`r::num`][An Integral constant expression] [Constant time]]
|
||||
[[`r::den`][An Integral constant expression] [Constant time]]
|
||||
[[`r::type`][__Rational_Constant] [Constant time]]
|
||||
[[`r::value_type const c=r()`][] [Constant time]]
|
||||
]
|
||||
|
||||
[heading Expression semantics]
|
||||
|
||||
[table
|
||||
[[Expression][Semantics]]
|
||||
[[`r::tag`][r's tag type; r::tag::value is r's conversion rank.]]
|
||||
[[`r::value_type`][A cv-unqualified type of `r()`]]
|
||||
[[`r::num_type`][A cv-unqualified type of `r::num`]]
|
||||
[[`r::den_type`][A cv-unqualified type of `r::den`]]
|
||||
[[`r::num`][The numerator of the rational constant]]
|
||||
[[`r::den`][The denominator of the rational constant]]
|
||||
[[`r::type`][equal_to<n::type,n>::value == true.]]
|
||||
[[`r::value_type const c=r()`][`r::value_type const c=r::value_type(r::num,r::den)`]]
|
||||
]
|
||||
|
||||
[heading Models]
|
||||
|
||||
* __ratio<>
|
||||
|
||||
[endsect]
|
||||
|
||||
[/===========================================]
|
||||
[section:rational_constant_hpp Header `<boost/ratio/rational_constant.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
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>
|
||||
|
||||
|
||||
[endsect] [/section:rational_constant_hpp Header `<boost/ratio/rational_constant.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_rational_c_tag_hpp Header `<boost/ratio/mpl/rational_c_tag.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
namespace boost {
|
||||
namespace mpl {
|
||||
|
||||
struct rational_c_tag : int_<10> {};
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
[endsect] [/section:mpl_rational_c_tag_hpp Header `<boost/ratio/mpl/rational_c_tag.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_numeric_cast_hpp Header `<boost/ratio/mpl/numeric_cast.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
namespace boost {
|
||||
namespace mpl {
|
||||
|
||||
template<> struct numeric_cast< integral_c_tag,rational_c_tag >;
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
[section:numeric_cast `mpl::numeric_cast<>` Specialization]
|
||||
|
||||
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 >
|
||||
{
|
||||
};
|
||||
};
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect] [/section:mpl_numeric_cast_hpp Header `<boost/ratio/mpl/numeric_cast.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_arithmetic_hpp Header `<boost/ratio/mpl/arithmetic.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
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>
|
||||
|
||||
|
||||
[endsect] [/section:mpl_arithmetic_hpp Header `<boost/ratio/mpl/arithmetic.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_plus_hpp Header `<boost/ratio/mpl/plus.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
namespace boost {
|
||||
namespace mpl {
|
||||
|
||||
template<>
|
||||
struct plus_impl< rational_c_tag,rational_c_tag >;
|
||||
}
|
||||
}
|
||||
|
||||
[section:plus_impl `mpl::plus_impl<>` Specialization]
|
||||
|
||||
template<>
|
||||
struct plus_impl< rational_c_tag,rational_c_tag >
|
||||
{
|
||||
template< typename R1, typename R2 > struct apply
|
||||
: ratio_add<R1, R2>
|
||||
{
|
||||
};
|
||||
};
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect] [/section:mpl_plus_hpp Header `<boost/ratio/mpl/plus.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_comparison_hpp Header `<boost/ratio/mpl/comparison.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
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>
|
||||
|
||||
|
||||
[endsect] [/section:mpl_comparison_hpp Header `<boost/ratio/mpl/mpl_comparison_hpp.hpp>`]
|
||||
|
||||
[/===========================================]
|
||||
[section:mpl_equal_to_hpp Header `<boost/ratio/mpl/equal_to.hpp>`]
|
||||
[/===========================================]
|
||||
|
||||
namespace boost {
|
||||
namespace mpl {
|
||||
|
||||
template<>
|
||||
struct equal_to_impl< rational_c_tag,rational_c_tag >;
|
||||
}
|
||||
}
|
||||
|
||||
[section:equal_to `mpl::equal_to_impl<>` Specialization]
|
||||
|
||||
template<>
|
||||
struct equal_to_impl< rational_c_tag,rational_c_tag >
|
||||
{
|
||||
template< typename R1, typename R2 > struct apply
|
||||
: ratio_equal<R1, R2>
|
||||
{
|
||||
};
|
||||
};
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect] [/section:mpl_equal_to_hpp Header `<boost/ratio/mpl/equal_to.hpp>`]
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -892,6 +1207,13 @@ This header provides `ratio_string<>` which can generate a textual representatio
|
||||
[section:history Appendix A: History]
|
||||
[/==================================]
|
||||
|
||||
[section [*Version 1.0.1, Jan 8, 2011] ]
|
||||
|
||||
* Added MPL Rational Constant and the associated numeric metafunction specializations.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
[section [*Version 1.0.0, Jan 2, 2011] ]
|
||||
|
||||
* Moved ratio to trunk.
|
||||
@ -1160,9 +1482,11 @@ The library code was derived from Howard Hinnant's `time2_demo` prototype. Many
|
||||
|
||||
Much thanks to Andrei Alexandrescu, Walter Brown, Peter Dimov, Jeff Garland, Terry Golubiewski, Daniel Krugler, Anthony Williams.
|
||||
|
||||
The ratio.hpp source has been adapted from the experimental header `<ratio_io>` from Howard Hinnant.
|
||||
Howard Hinnant, who is the real author of the library, has provided valuable feedback and suggestions during the development of the library. In particular, The ratio_io.hpp source has been adapted from the experimental header `<ratio_io>` from Howard Hinnant.
|
||||
|
||||
Thanks to Andrew Chinnoff for his help polishing the documentation.
|
||||
The acceptance review of Boost.Ratio took place between October 2nd and 11th 2010. Many thanks to Anthony Williams, the review manager, and to all the reviewers: Bruno Santos, Joel Falcou, Robert Stewart, Roland Bock, Tom Tan and Paul A. Bristol.
|
||||
|
||||
Thanks to Andrew Chinoff and Paul A. Bristol for his help polishing the documentation.
|
||||
|
||||
[endsect] [/section:acknowledgements Appendix E: Acknowledgements]
|
||||
|
||||
@ -1242,7 +1566,6 @@ You can also run a specific suite of test by doing
|
||||
|
||||
[heading For later releases]
|
||||
|
||||
* Use constexpr on compilers providing it.
|
||||
* Use template aliases on compiler providing it.
|
||||
* Implement [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#3135 multiple arguments] ratio arithmetic.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user