2 / Copyright (c) 2008 Howard Hinnant
3 / Copyright (c) 2006, 2008 Beman Dawes
4 / Copyright (c) 2009-2011 Vicente J. Botet Escriba
6 / Distributed under the Boost Software License, Version 1.0. (See accompanying
7 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
13 [authors [Hinnant, Howard]]
14 [authors [Dawes, Beman]]
15 [authors [Botet Escriba, Vicente J.]]
16 [copyright 2008 Howard Hinnant]
17 [copyright 2006, 2008 Beman Dawes]
18 [copyright 2009-2012 Vicente J. Botet Escriba]
23 Compile time rational arithmetic.
26 Distributed under the Boost Software License, Version 1.0.
27 (See accompanying file LICENSE_1_0.txt or copy at
28 [@http://www.boost.org/LICENSE_1_0.txt])
33 [def __Boost_Ratio [*Boost.Ratio]]
35 [/===============================================]
37 [def __time_point `time_point`]
40 [/===============================================]
41 [def __ratio [link ratio.reference.std.ratio_hpp.ratio `ratio`]]
43 [template ratio_conf[link_text] [link ratio.reference.std.ratio_hpp.conf [link_text]]]
45 [def __BOOST_RATIO_USES_STATIC_ASSERT [link ratio.reference.config_hpp.assert `BOOST_RATIO_USES_STATIC_ASSERT`]]
46 [def __BOOST_RATIO_USES_MPL_ASSERT [link ratio.reference.config_hpp.assert `BOOST_RATIO_USES_MPL_ASSERT`]]
47 [def __BOOST_RATIO_USES_ARRAY_ASSERT [link ratio.reference.config_hpp.assert `BOOST_RATIO_USES_ARRAY_ASSERT`]]
49 [def __BOOST_RATIO_EXTENSIONS [link ratio.reference.config_hpp.ext `BOOST_RATIO_EXTENSIONS`]]
50 [def __BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0 [link ratio.reference.config_hpp.deprecated `BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0`]]
51 [def __BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 [link ratio.reference.config_hpp.deprecated `BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 `]]
52 [def __BOOST_RATIO_VERSION [link ratio.reference.config_hpp.version `BOOST_RATIO_VERSION `]]
55 [template ratio_arithmetic[link_text] [link ratio.reference.std.ratio_hpp.ratio_arithmetic [link_text]]]
56 [def __ratio_add [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_add`]]
57 [def __ratio_subtract [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_subtract`]]
58 [def __ratio_multiply [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_multiply`]]
59 [def __ratio_divide [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_divide`]]
60 [def __ratio_power [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_power`]]
61 [def __ratio_negate [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_negate`]]
62 [def __ratio_abs [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_abs`]]
63 [def __ratio_sign [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_sign`]]
64 [def __ratio_gcd [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_gcd`]]
65 [def __ratio_lcm [link ratio.reference.std.ratio_hpp.ratio_arithmetic `ratio_lcm`]]
68 [template ratio_comparison[link_text] [link ratio.reference.std.ratio_hpp.ratio_comparison [link_text]]]
69 [def __ratio_equal [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_equal`]]
70 [def __ratio_not_equal [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_not_equal`]]
71 [def __ratio_less [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_less`]]
72 [def __ratio_less_equal [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_less_equal`]]
73 [def __ratio_greater [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_greater`]]
74 [def __ratio_greater_equal [link ratio.reference.std.ratio_hpp.ratio_comparison `ratio_greater_equal`]]
77 [template ratio_si_typedefs[link_text] [link ratio.reference.std.ratio_hpp.ratio_si_typedefs [link_text]]]
78 [def __atto [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `atto`]]
79 [def __femto [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `femto`]]
80 [def __pico [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `pico`]]
81 [def __nano [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `nano`]]
82 [def __micro [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `micro`]]
83 [def __milli [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `milli`]]
84 [def __centi [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `centi`]]
85 [def __deci [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `deci`]]
86 [def __deca [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `deca`]]
87 [def __hecto [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `hecto`]]
88 [def __kilo [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `kilo`]]
89 [def __mega [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `mega`]]
90 [def __giga [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `giga`]]
91 [def __tera [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `tera`]]
92 [def __peta [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `peta`]]
93 [def __exa [link ratio.reference.std.ratio_hpp.ratio_si_typedefs `exa`]]
95 [def __kibi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `kibi`]]
96 [def __mebi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `mebi`]]
97 [def __gibi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `gibi`]]
98 [def __tebi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `tebi`]]
99 [def __pebi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `pebi`]]
100 [def __exbi [link ratio.reference.std.ratio_hpp.ratio_iec_typedefs `exbi`]]
102 [template mu[]'''μ'''] [/ ยต Greek small letter mu]
104 [def __Rational_Constant [link ratio.reference.mpl.rational_constant Rational Constant]]
107 [/warning Ratio is not part of the Boost libraries.]
114 [/====================================]
115 [heading How to Use This Documentation]
116 [/====================================]
118 This documentation makes use of the following naming and formatting conventions.
120 * Code is in `fixed width font` and is syntax-highlighted.
121 * Replaceable text that you will need to supply is in [~italics].
122 * Free functions are rendered in the code font followed by `()`, as in `free_function()`.
123 * 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.
124 * If a name refers to a function-like macro, it is specified like this: `MACRO()`;
125 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 `()`.
126 * Names that refer to /concepts/ in the generic programming sense are specified in CamelCase.
128 [note In addition, notes such as this one specify non-essential information that provides additional background or rationale.]
130 Finally, you can mentally add the following to any code fragments in this document:
132 // Include all of Ratio files
133 #include <boost/ratio.hpp>
134 using namespace boost;
140 __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.
144 [/==================]
145 [section Description]
146 [/==================]
148 The __Boost_Ratio library provides:
150 * 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.
152 * 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.
154 * Some extension related to the __Rational_Constant concept enabling the use of __ratio<> in the context of [*Boost.MPL] numeric metafunctions.
161 [/==============================]
162 [section:users_guide User's Guide]
163 [/==============================]
165 [/======================================]
166 [section:getting_started Getting Started]
167 [/======================================]
169 [/======================================]
170 [section:install Installing Ratio]
171 [/======================================]
173 [/=================================]
174 [heading Getting Boost.Ratio ]
175 [/=================================]
177 Boost.Ratio is in the latest Boost release in the folder `/boost/ratio`. Documentation, tests and examples folder are at `boost/libs/ratio/`.
179 You can also access the latest (unstable?) state from the [@http://svn.boost.org/svn/boost/trunk Boost trunk] directories `boost/ratio` and `libs/ratio`.
181 Just go to [@http://svn.boost.org/trac/boost/wiki/BoostSubversion the wiki] and follow the instructions there for anonymous SVN access.
183 [/==========================================]
184 [heading Where to install Boost.Ratio? ]
185 [/==========================================]
187 The simple way is to decompress (or checkout from SVN) the files in your BOOST_ROOT directory.
189 [/=================================]
190 [heading Building Boost.Ratio ]
191 [/=================================]
193 __Boost_Ratio is a header only library, so no need to compile anything, you just need to `include <boost/ratio.hpp>`.
196 [/===================]
197 [heading Requirements]
198 [/===================]
200 __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).
202 In particular, __Boost_Ratio depends on:
206 [[@http://www.boost.org/libs/config [*Boost.Config]]] [for configuration purposes, ...]
209 [[@http://www.boost.org/libs/integer [*Boost.Integer]]] [for cstdint conformance, and integer traits ...]
212 [[@http://www.boost.org/libs/mpl [*Boost.MPL]]] [for MPL Assert and bool, logical ...]
215 [[@http://www.boost.org/libs/static_assert [*Boost.StaticAssert]]] [for STATIC_ASSERT, ...]
218 [[@http://www.boost.org/libs/type_traits [*Boost.TypeTraits]]] [for is_base, is_convertible ...]
221 [[@http://www.boost.org/libs/utility [*Boost.Utility/EnableIf]]] [for enable_if, ...]
226 [/=========================================================]
227 [heading Building an executable that uses __Boost_Ratio ]
228 [/=========================================================]
233 [/=========================]
234 [heading Exception safety ]
235 [/=========================]
237 All functions in the library are exception-neutral, providing the strong exception safety guarantee.
239 [/=====================]
240 [heading Thread safety ]
241 [/=====================]
243 All functions in the library are thread-unsafe except when noted explicitly.
245 [/========================]
246 [heading Tested compilers ]
247 [/========================]
249 __Boost_Ratio should work with an C++03 conforming compiler. The current version has been tested on:
258 * GCC 4.5.0 -std=c++0x
260 * GCC 4.5.2 -std=c++0x
262 * GCC 4.6.0 -std=c++0x
266 * GCC 4.4.6 -std=c++0x
268 * GCC 4.5.4 -std=c++0x
270 * GCC 4.6.1 -std=c++0x
272 * Intel 12.1.3 -std=c++0x
278 * GCC 4.6.2 -std=c++0x
280 * GCC 4.7.0 -std=c++0x
282 * GCC 4.7.1 -std=c++0x
285 * clang 2.9 -std=c++0x
287 * clang 3.0 -std=c++0x
289 * clang 3.1 -std=c++0x
290 * clang 3.1 -std=c++0x -stdlib=libc++
292 * clang 3.2 -std=c++11
293 * clang 3.2 -std=c++11 -stdlib=libc++
295 [note Please let us know how this works on other platforms/compilers.]
297 [note Please send any questions, comments and bug reports to boost <at> lists <dot> boost <dot> org.]
307 __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.
309 __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.
313 typedef __ratio<5, 3> five_thirds;
314 // five_thirds::num == 5, five_thirds::den == 3
316 typedef __ratio<25, 15> also_five_thirds;
317 // also_five_thirds::num == 5, also_five_thirds::den == 3
319 typedef ratio_divide<five_thirds, also_five_thirds>::type one;
320 // one::num == 1, one::den == 1
322 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.
326 typedef ratio_multiply<__ratio<5>, giga>::type _5giga;
327 // _5giga::num == 5000000000, _5giga::den == 1
329 typedef ratio_multiply<__ratio<5>, nano>::type _5nano;
330 // _5nano::num == 1, _5nano::den == 200000000
334 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 [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes 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 `ratio`s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes 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 `ratio`s, both `prefix()` and `symbol()` return a `basic_string` containing "[`ratio::num/ratio::den`]".
336 `ratio_string<ratio<N, D>, CharT>` is only defined for four character types:
341 * `wchar_t`: UTF-16 (if wchar_t is 16 bits) or UTF-32
343 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.
345 The `symbol` (Greek mu or [mu]) for micro is defined by [@http://www.unicode.org/charts/PDF/U0080.pdf Unicode] to be U+00B5.
349 #include <boost/ratio/ratio_io.hpp>
355 using namespace boost;
357 cout << "ratio_string<deca, char>::prefix() = "
358 << ratio_string<deca, char>::prefix() << '\n';
359 cout << "ratio_string<deca, char>::symbol() = "
360 << ratio_string<deca, char>::symbol() << '\n';
362 cout << "ratio_string<giga, char>::prefix() = "
363 << ratio_string<giga, char>::prefix() << '\n';
364 cout << "ratio_string<giga, char>::symbol() = "
365 << ratio_string<giga, char>::symbol() << '\n';
367 cout << "ratio_string<ratio<4, 6>, char>::prefix() = "
368 << ratio_string<ratio<4, 6>, char>::prefix() << '\n';
369 cout << "ratio_string<ratio<4, 6>, char>::symbol() = "
370 << ratio_string<ratio<4, 6>, char>::symbol() << '\n';
375 ratio_string<deca, char>::prefix() = deca
376 ratio_string<deca, char>::symbol() = da
377 ratio_string<giga, char>::prefix() = giga
378 ratio_string<giga, char>::symbol() = G
379 ratio_string<ratio<4, 6>, char>::prefix() = [2/3]
380 ratio_string<ratio<4, 6>, char>::symbol() = [2/3]
383 [heading Ratio MPL Numeric Metafunctions]
385 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
387 typedef mpl::times<int_<5>, giga>::type _5giga;
388 // _5giga::num == 5000000000, _5giga::den == 1
390 typedef mpl::times<int_<5>, nano>::type _5nano;
391 // _5nano::num == 1, _5nano::den == 200000000
396 [section:Examples Example]
403 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.
405 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:
408 template <class Ratio>
414 length() : len_(1) {}
415 length(const double& len) : len_(len) {}
418 length(const length<R>& d)
419 : len_(d.count() * boost::ratio_divide<Ratio, R>::type::den /
420 boost::ratio_divide<Ratio, R>::type::num) {}
422 double count() const {return len_;}
424 length& operator+=(const length& d) {len_ += d.count(); return *this;}
425 length& operator-=(const length& d) {len_ -= d.count(); return *this;}
427 length operator+() const {return *this;}
428 length operator-() const {return length(-len_);}
430 length& operator*=(double rhs) {len_ *= rhs; return *this;}
431 length& operator/=(double rhs) {len_ /= rhs; return *this;}
435 Here's a small sampling of length units:
437 typedef length<boost::__ratio<1> > meter; // set meter as "unity"
438 typedef length<boost::__centi> centimeter; // 1/100 meter
439 typedef length<boost::__kilo> kilometer; // 1000 meters
440 typedef length<boost::__ratio<254, 10000> > inch; // 254/10000 meters
442 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:
444 typedef length<boost::ratio_multiply<boost::__ratio<12>, inch::__ratio>::type> foot; // 12 inchs
445 typedef length<boost::ratio_multiply<boost::__ratio<5280>, foot::__ratio>::type> mile; // 5280 feet
447 Now we need a floating point-based definition of seconds:
449 typedef boost::chrono::duration<double> seconds; // unity
451 We can even support sub-nanosecond durations:
453 typedef boost::chrono::duration<double, boost::__pico> picosecond; // 10^-12 seconds
454 typedef boost::chrono::duration<double, boost::__femto> femtosecond; // 10^-15 seconds
455 typedef boost::chrono::duration<double, boost::__atto> attosecond; // 10^-18 seconds
457 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:
459 template <class R1, class R2>
465 typedef R2 distance_dim;
466 quantity() : q_(1) {}
468 double get() const {return q_;}
469 void set(double q) {q_ = q;}
473 class quantity<boost::__ratio<1>, boost::__ratio<0> >
477 quantity() : q_(1) {}
478 quantity(seconds d) : q_(d.count()) {} // note: only User1::seconds needed here
480 double get() const {return q_;}
481 void set(double q) {q_ = q;}
485 class quantity<boost::__ratio<0>, boost::__ratio<1> >
489 quantity() : q_(1) {}
490 quantity(meter d) : q_(d.count()) {} // note: only User1::meter needed here
492 double get() const {return q_;}
493 void set(double q) {q_ = q;}
497 class quantity<boost::__ratio<0>, boost::__ratio<0> >
501 quantity() : q_(1) {}
502 quantity(double d) : q_(d) {}
504 double get() const {return q_;}
505 void set(double q) {q_ = q;}
508 That allows us to create some useful SI-based unit types:
510 typedef quantity<boost::__ratio<0>, boost::__ratio<0> > Scalar;
511 typedef quantity<boost::__ratio<1>, boost::__ratio<0> > Time; // second
512 typedef quantity<boost::__ratio<0>, boost::__ratio<1> > Distance; // meter
513 typedef quantity<boost::__ratio<-1>, boost::__ratio<1> > Speed; // meter/second
514 typedef quantity<boost::__ratio<-2>, boost::__ratio<1> > Acceleration; // meter/second^2
516 To make quantity useful, we need to be able to do arithmetic:
518 template <class R1, class R2, class R3, class R4>
519 quantity<typename boost::ratio_subtract<R1, R3>::type,
520 typename boost::ratio_subtract<R2, R4>::type>
521 operator/(const quantity<R1, R2>& x, const quantity<R3, R4>& y)
523 typedef quantity<typename boost::ratio_subtract<R1, R3>::type,
524 typename boost::ratio_subtract<R2, R4>::type> R;
526 r.set(x.get() / y.get());
530 template <class R1, class R2, class R3, class R4>
531 quantity<typename boost::ratio_add<R1, R3>::type,
532 typename boost::ratio_add<R2, R4>::type>
533 operator*(const quantity<R1, R2>& x, const quantity<R3, R4>& y)
535 typedef quantity<typename boost::ratio_add<R1, R3>::type,
536 typename boost::ratio_add<R2, R4>::type> R;
538 r.set(x.get() * y.get());
542 template <class R1, class R2>
544 operator+(const quantity<R1, R2>& x, const quantity<R1, R2>& y)
546 typedef quantity<R1, R2> R;
548 r.set(x.get() + y.get());
552 template <class R1, class R2>
554 operator-(const quantity<R1, R2>& x, const quantity<R1, R2>& y)
556 typedef quantity<R1, R2> R;
558 r.set(x.get() - y.get());
562 With all of the foregoing scaffolding, we can now write an exemplar of a type-safe physics function:
565 compute_distance(Speed v0, Time t, Acceleration a)
567 return v0 * t + Scalar(.5) * a * t * t; // if a units mistake is made here it won't compile
571 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.)
575 typedef boost::__ratio<8, BOOST_INTMAX_C(0x7FFFFFFFD)> R1;
576 typedef boost::__ratio<3, BOOST_INTMAX_C(0x7FFFFFFFD)> R2;
577 typedef User1::quantity<boost::ratio_subtract<boost::__ratio<0>, boost::__ratio<1> >::type,
578 boost::ratio_subtract<boost::__ratio<1>, boost::__ratio<0> >::type > RR;
579 typedef boost::ratio_subtract<R1, R2>::type RS;
580 std::cout << RS::num << '/' << RS::den << '\n';
583 std::cout << "*************\n";
584 std::cout << "* testUser1 *\n";
585 std::cout << "*************\n";
586 User1::Distance d( User1::mile(110) );
587 User1::Time t( boost::chrono::__hours(2) );
590 //r.set(d.get() / t.get());
594 User1::Speed s = d / t;
595 std::cout << "Speed = " << s.get() << " meters/sec\n";
596 User1::Acceleration a = User1::Distance( User1::foot(32.2) ) / User1::Time() / User1::Time();
597 std::cout << "Acceleration = " << a.get() << " meters/sec^2\n";
598 User1::Distance df = compute_distance(s, User1::Time( User1::seconds(0.5) ), a);
599 std::cout << "Distance = " << df.get() << " meters\n";
600 std::cout << "There are "
601 << User1::mile::ratio::den << '/' << User1::mile::ratio::num << " miles/meter";
604 std::cout << " which is approximately " << mi.count() << '\n';
605 std::cout << "There are "
606 << User1::mile::ratio::num << '/' << User1::mile::ratio::den << " meters/mile";
609 std::cout << " which is approximately " << mt.count() << '\n';
610 User1::attosecond as(1);
611 User1::seconds sec = as;
612 std::cout << "1 attosecond is " << sec.count() << " seconds\n";
613 std::cout << "sec = as; // compiles\n";
614 sec = User1::seconds(1);
616 std::cout << "1 second is " << as.count() << " attoseconds\n";
617 std::cout << "as = sec; // compiles\n";
622 ['See the source file [@boost:libs/ratio/example/si_physics.cpp example/si_physics.cpp]]
629 [/================================]
630 [section:ext_references External Resources]
631 [/================================]
636 [[@http://www.open-std.org/jtc1/sc22/wg21 [*C++ Standards Committee's current Working Paper]]]
637 [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"]
641 [[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*N2661 - A Foundation to Sleep On]]]
642 [From Howard E. Hinnant, Walter E. Brown, Jeff Garland and Marc Paterno. Is very informative and provides motivation for key design decisions]
647 [[@http://lwg.github.com/issues/lwg-defects.html#1281 [*LWG 1281. CopyConstruction and Assignment between ratios having the same normalized form]]]
648 [From Vicente Juan Botet Escriba.]
659 [section:reference Reference ]
662 [/=================================================]
663 [section:config_hpp Header `<boost/ratio/config.hpp>`]
664 [/=================================================]
667 // Configuration macros
668 #define __BOOST_RATIO_VERSION
669 #define __BOOST_RATIO_EXTENSIONS
670 #define __BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0
671 #define __BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0
672 #define __BOOST_RATIO_USES_STATIC_ASSERT
673 #define __BOOST_RATIO_USES_MPL_ASSERT
674 #define __BOOST_RATIO_USES_ARRAY_ASSERT
677 [section:ext Extensions]
679 When __BOOST_RATIO_EXTENSIONS is defined, __Boost_Ratio provides in addition some extension to the C++ standard, see below.
682 [section:deprecated Deprecated]
684 When __BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined the deprecated features stated as DEPRECATED V2 are provided.
686 When __BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined the deprecated features stated as DEPRECATED V2 are NOT provided.
689 [section:version Version]
691 __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.
693 When __BOOST_RATIO_VERSION is 1 __BOOST_RATIO_PROVIDES_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined by default.
695 When __BOOST_RATIO_VERSION is 2 __BOOST_RATIO_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V2_0_0 is defined by default.
698 [section:assert Static Assert]
700 When BOOST_NO_STATIC_ASSERT is defined, the user can select the way static assertions are reported. Define
702 * __BOOST_RATIO_USES_STATIC_ASSERT to use Boost.StaticAssert.
703 * __BOOST_RATIO_USES_MPL_ASSERT to use [*Boost.MPL] static assertions.
704 * __BOOST_RATIO_USES_ARRAY_ASSERT to use __Boost_Ratio internal static assertions.
706 The default behavior is as if __BOOST_RATIO_USES_ARRAY_ASSERT was defined.
708 When __BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are defined as shown:
710 #define BOOST_RATIO_OVERFLOW_IN_ADD "overflow in ratio add"
711 #define BOOST_RATIO_OVERFLOW_IN_SUB "overflow in ratio sub"
712 #define BOOST_RATIO_OVERFLOW_IN_MUL "overflow in ratio mul"
713 #define BOOST_RATIO_OVERFLOW_IN_DIV "overflow in ratio div"
714 #define BOOST_RATIO_NUMERATOR_IS_OUT_OF_RANGE "ratio numerator is out of range"
715 #define BOOST_RATIO_DIVIDE_BY_0 "ratio divide by 0"
716 #define BOOST_RATIO_DENOMINATOR_IS_OUT_OF_RANGE "ratio denominator is out of range"
718 Depending upon the static assertion system used, a hint as to the failing assertion will appear in some form in the compiler diagnostic output.
724 [/=================================================]
725 [section:std C++0x Recommendation]
726 [/=================================================]
728 [/=================================================]
729 [section:ratio_ratio_hpp Header `<boost/ratio.hpp>`]
730 [/=================================================]
732 This header includes all the ratio related header files
734 #include <boost/ratio/ratio.hpp>
735 #include <boost/ratio/ratio_io.hpp>
736 #include <boost/ratio/rational_constant.hpp>
740 [/========================================================]
741 [section:ratio_fwdhpp Header `<boost/ratio/ratio_fwd.hpp>`]
742 [/========================================================]
744 This header provides forward declarations for the `<boost/ratio/ratio.hpp>` file.
748 template <boost::intmax_t N, boost::intmax_t D = 1> class __ratio;
751 template <class R1, class R2> struct __ratio_add;
752 template <class R1, class R2> struct __ratio_subtract;
753 template <class R1, class R2> struct __ratio_multiply;
754 template <class R1, class R2> struct __ratio_divide;
755 #ifdef BOOST_RATIO_EXTENSIONS
756 template <class R,int P> struct __ratio_power;
757 template <class R> struct __ratio_negate;
758 template <class R> struct __ratio_sign;
759 template <class R> struct __ratio_abs;
760 template <class R1, class R2> struct __ratio_gcd;
761 template <class R1, class R2> struct __ratio_lcm;
765 template <class R1, class R2> struct __ratio_equal;
766 template <class R1, class R2> struct __ratio_not_equal;
767 template <class R1, class R2> struct __ratio_less;
768 template <class R1, class R2> struct __ratio_less_equal;
769 template <class R1, class R2> struct __ratio_greater;
770 template <class R1, class R2> struct __ratio_greater_equal;
772 // convenience SI typedefs
773 typedef ratio<1LL, 1000000000000000000LL> __atto;
774 typedef ratio<1LL, 1000000000000000LL> __femto;
775 typedef ratio<1LL, 1000000000000LL> __pico;
776 typedef ratio<1LL, 1000000000LL> __nano;
777 typedef ratio<1LL, 1000000LL> __micro;
778 typedef ratio<1LL, 1000LL> __milli;
779 typedef ratio<1LL, 100LL> __centi;
780 typedef ratio<1LL, 10LL> __deci;
781 typedef ratio< 10LL, 1LL> __deca;
782 typedef ratio< 100LL, 1LL> __hecto;
783 typedef ratio< 1000LL, 1LL> __kilo;
784 typedef ratio< 1000000LL, 1LL> __mega;
785 typedef ratio< 1000000000LL, 1LL> __giga;
786 typedef ratio< 1000000000000LL, 1LL> __tera;
787 typedef ratio< 1000000000000000LL, 1LL> __peta;
788 typedef ratio<1000000000000000000LL, 1LL> __exa;
790 #ifdef BOOST_RATIO_EXTENSIONS
791 // convenience IEC typedefs
792 typedef ratio< 1024LL> __kibi;
793 typedef ratio< 1024LL*1024LL> __mebi;
794 typedef ratio< 1024LL*1024LL*1024LL> __gibi;
795 typedef ratio< 1024LL*1024LL*1024LL*1024LL> __tebi;
796 typedef ratio< 1024LL*1024LL*1024LL*1024LL*1024LL> __pebi;
797 typedef ratio<1024LL*1024LL*1024LL*1024LL*1024LL*1024LL> __exbi;
804 [/=================================================]
805 [section:ratio_hpp Header `<boost/ratio/ratio.hpp>`]
806 [/=================================================]
808 __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).
810 [section:ratio Class Template `ratio<>`]
812 template <boost::intmax_t N, boost::intmax_t D>
815 static const boost::intmax_t num;
816 static const boost::intmax_t den;
817 typedef ratio<num, den> type;
819 #ifdef __BOOST_RATIO_EXTENSIONS
820 typedef mpl::rational_c_tag tag;
821 typedef boost::rational<boost::intmax_t> value_type;
822 typedef boost::intmax_t num_type;
823 typedef boost::intmax_t den_type;
827 template <intmax_t _N2, intmax_t _D2>
828 ratio(const ratio<_N2, _D2>&);
830 template <intmax_t _N2, intmax_t _D2>
831 ratio& operator=(const ratio<_N2, _D2>&);
833 static value_type value();
834 value_type operator()() const;
838 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.
840 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:
842 * `num` has the value `sign(N)*sign(D)*abs(N)/gcd`.
844 * `den` has the value `abs(D)/gcd`.
846 The nested typedef `type` denotes the normalized form of this __ratio type. It should be
847 used when the normalized form of the template arguments are required, since the arguments are not necessarily normalized.
849 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`
851 [section:ca Construction and Assignment]
853 Included only if __BOOST_RATIO_EXTENSIONS is defined.
855 [heading Default Constructor]
859 [*Effects:] Constructs a __ratio object.
861 [heading Copy Constructor]
863 template <intmax_t N2, intmax_t D2>
864 ratio(const __ratio<N2, D2>& r);
866 [*Effects:] Constructs a __ratio object.
868 [*Remarks:] This constructor will not participate in overload resolution unless `r` has the same normalized form as `*this`.
870 [heading Assignement]
872 template <intmax_t N2, intmax_t D2>
873 __ratio& operator=(const __ratio<N2, D2>& r);
875 [*Effects:] Assigns a __ratio object.
879 [*Remarks:] This operator will not participate in overload resolution unless `r` has the same normalized form as `*this`.
883 [section:mpl MPL Numeric Metafunctions]
885 Included only if __BOOST_RATIO_EXTENSIONS is defined.
887 In order to work with [*Boost.MPL] numeric metafunctions as a __Rational_Constant, the following has beed added:
889 typedef mpl::rational_c_tag tag;
890 typedef boost::rational<boost::intmax_t> value_type;
891 typedef boost::intmax_t num_type;
892 typedef boost::intmax_t den_type;
895 [section:obs Observers]
897 Included only if __BOOST_RATIO_EXTENSIONS is defined.
899 static value_type value();
900 value_type operator()() const;
902 [*Returns:] value_type(num,den);
909 [section:ratio_arithmetic `ratio` Arithmetic]
911 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.
913 [heading `ratio_add<>`]
915 template <class R1, class R2> struct ratio_add {
916 typedef [/see below] type;
919 The nested typedef `type` is a synonym for `__ratio<R1::num * R2::den + R2::num * R1::den, R1::den * R2::den>::type`.
921 [heading `ratio_subtract<>`]
923 template <class R1, class R2> struct ratio_subtract {
924 typedef [/see below] type;
927 The nested typedef `type` is a synonym for `__ratio<R1::num * R2::den - R2::num * R1::den, R1::den * R2::den>::type`.
929 [heading `ratio_multiply<>`]
931 template <class R1, class R2> struct ratio_multiply {
932 typedef [/see below] type;
935 The nested typedef `type` is a synonym for `__ratio<R1::num * R2::num, R1::den * R2::den>::type`.
937 [heading `ratio_divide<>`]
939 template <class R1, class R2> struct ratio_divide {
940 typedef [/see below] type;
943 The nested typedef `type` is a synonym for `__ratio<R1::num * R2::den, R2::num * R1::den>::type`.
945 [heading `ratio_power<>`]
947 Included only if __BOOST_RATIO_EXTENSIONS is defined.
949 template <class R, int P> struct ratio_power {
950 typedef [/see below] type;
953 The nested typedef `type` is a synonym for `R* *R` P times.
955 [heading `ratio_negate<>`]
957 Included only if __BOOST_RATIO_EXTENSIONS is defined.
959 This extension of the C++ standard helps in the definition of some [*Boost.MPL] numeric metafunctions.
962 template <class R> struct ratio_negate {
963 typedef [/see below] type;
966 The nested typedef `type` is a synonym for `__ratio<-R::num, R::den>::type`.
968 [heading `ratio_abs<>`]
970 Included only if __BOOST_RATIO_EXTENSIONS is defined.
972 This extension of the C++ standard helps in the definition of some [*Boost.MPL] numeric metafunctions.
974 template <class R> struct ratio_abs {
975 typedef [/see below] type;
978 The nested typedef `type` is a synonym for `__ratio<abs_c<intmax_t,R::num>::value, R::den>::type`.
980 [heading `ratio_sign<>`]
982 Included only if __BOOST_RATIO_EXTENSIONS is defined.
984 This extension of the C++ standard helps in the definition of some [*Boost.MPL] numeric metafunctions.
986 template <class R> struct ratio_sign {
987 typedef [/see below] type;
990 The nested typedef `type` is a synonym for `sign_c<intmax_t,R::num>::type`.
992 [heading `ratio_gcd<>`]
994 Included only if __BOOST_RATIO_EXTENSIONS is defined.
996 This extension of the C++ standard helps in the definition of some [*Boost.MPL] numeric metafunctions.
998 template <class R1, class R2> struct ratio_gcd {
999 typedef [/see below] type;
1002 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`.
1004 [heading `ratio_lcm<>`]
1006 Included only if __BOOST_RATIO_EXTENSIONS is defined.
1008 This extension of the C++ standard helps in the definition of some [*Boost.MPL] numeric metafunctions.
1010 template <class R1, class R2> struct ratio_lcm {
1011 typedef [/see below] type;
1014 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`.
1018 [section:ratio_comparison `ratio` Comparison]
1020 [heading `ratio_equal<>`]
1022 template <class R1, class R2> struct ratio_equal
1023 : public boost::integral_constant<bool, [/see below] > {};
1025 If R1::num == R2::num && R1::den == R2::den, ratio_equal derives from true_type, else derives from false_type.
1027 [heading `ratio_not_equal<>`]
1029 template <class R1, class R2> struct ratio_not_equal
1030 : public boost::integral_constant<bool, !ratio_equal<R1, R2>::value> {};
1032 [heading `ratio_less<>`]
1034 template <class R1, class R2>
1036 : public boost::integral_constant<bool, [/see below] > {};
1038 If R1::num * R2::den < R2::num * R1::den, ratio_less derives from true_type, else derives from false_type.
1040 [heading `ratio_less_equal<>`]
1042 template <class R1, class R2> struct ratio_less_equal
1043 : public boost::integral_constant<bool, !ratio_less<R2, R1>::value> {};
1045 [heading `ratio_greater<>`]
1047 template <class R1, class R2> struct ratio_greater
1048 : public boost::integral_constant<bool, ratio_less<R2, R1>::value> {};
1050 [heading `ratio_greater_equal<>`]
1052 template <class R1, class R2> struct ratio_greater_equal
1053 : public boost::integral_constant<bool, !ratio_less<R1, R2>::value> {};
1058 [section:ratio_si_typedefs SI typedefs]
1060 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`
1062 // convenience SI typedefs
1063 typedef __ratio<1LL, 1000000000000000000LL> atto;
1064 typedef __ratio<1LL, 1000000000000000LL> femto;
1065 typedef __ratio<1LL, 1000000000000LL> pico;
1066 typedef __ratio<1LL, 1000000000LL> nano;
1067 typedef __ratio<1LL, 1000000LL> micro;
1068 typedef __ratio<1LL, 1000LL> milli;
1069 typedef __ratio<1LL, 100LL> centi;
1070 typedef __ratio<1LL, 10LL> deci;
1071 typedef __ratio< 10LL, 1LL> deca;
1072 typedef __ratio< 100LL, 1LL> hecto;
1073 typedef __ratio< 1000LL, 1LL> kilo;
1074 typedef __ratio< 1000000LL, 1LL> mega;
1075 typedef __ratio< 1000000000LL, 1LL> giga;
1076 typedef __ratio< 1000000000000LL, 1LL> tera;
1077 typedef __ratio< 1000000000000000LL, 1LL> peta;
1078 typedef __ratio<1000000000000000000LL, 1LL> exa;
1082 [section:ratio_iec_typedefs IEC typedefs]
1084 Included only if __BOOST_RATIO_EXTENSIONS is defined.
1086 The [@http://http://en.wikipedia.org/wiki/Binary_prefix#Specific_units_of_IEC_60027-2_A.2_and_ISO.2FIEC_80000 Specific units of IEC 60027-2 A.2 and ISO/IEC 80000] specifies height IEC prefixes. __Boost_Ratio defines all except `zebi` and `yobi`
1088 // convenience ETC typedefs
1089 typedef ratio< 1024LL> kibi;
1090 typedef ratio< 1024LL*1024LL> mebi;
1091 typedef ratio< 1024LL*1024LL*1024LL> gibi;
1092 typedef ratio< 1024LL*1024LL*1024LL*1024LL> tebi;
1093 typedef ratio< 1024LL*1024LL*1024LL*1024LL*1024LL> pebi;
1094 typedef ratio<1024LL*1024LL*1024LL*1024LL*1024LL*1024LL> exbi;
1100 [section:limitations Limitations]
1102 The following are limitations of Boost.Ratio relative to the specification in the C++0x draft standard:
1104 * 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.
1105 * 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.
1106 * 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.
1110 [section:extensions Extensions]
1112 When __BOOST_RATIO_EXTENSIONS is defined __Boost_Ratio provides the following extensions:
1114 * 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]).
1115 * More C++ standard like metafunctions applied to ratio types, like __static_abs or __static_negate.
1116 * An __Boost_Mpl rational constant concept and the associated __Boost_Mpl arithmetic and comparison specializations including __numeric_cast, __plus, __equal_to between others.
1122 [section:io Ratio I/O]
1124 [/=======================================================]
1125 [section:ratio_io_hpp Header `<boost/ratio/ratio_io.hpp>`]
1126 [/=======================================================]
1128 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.
1131 template <class Ratio, class charT> struct ratio_string;
1133 template <> struct ratio_string<atto, char>;
1134 template <> struct ratio_string<atto, char16_t>;
1135 template <> struct ratio_string<atto, char32_t>;
1136 template <> struct ratio_string<atto, wchar_t>;
1138 template <> struct ratio_string<femto, char>;
1139 template <> struct ratio_string<femto, char16_t>;
1140 template <> struct ratio_string<femto, char32_t>;
1141 template <> struct ratio_string<femto, wchar_t>;
1143 template <> struct ratio_string<pico, char>;
1144 template <> struct ratio_string<pico, char16_t>;
1145 template <> struct ratio_string<pico, char32_t>;
1146 template <> struct ratio_string<pico, wchar_t>;
1148 template <> struct ratio_string<nano, char>;
1149 template <> struct ratio_string<nano, char16_t>;
1150 template <> struct ratio_string<nano, char32_t>;
1151 template <> struct ratio_string<nano, wchar_t>;
1153 template <> struct ratio_string<micro, char>;
1154 template <> struct ratio_string<micro, char16_t>;
1155 template <> struct ratio_string<micro, char32_t>;
1156 template <> struct ratio_string<micro, wchar_t>;
1158 template <> struct ratio_string<milli, char>;
1159 template <> struct ratio_string<milli, char16_t>;
1160 template <> struct ratio_string<milli, char32_t>;
1161 template <> struct ratio_string<milli, wchar_t>;
1163 template <> struct ratio_string<centi, char>;
1164 template <> struct ratio_string<centi, char16_t>;
1165 template <> struct ratio_string<centi, char32_t>;
1166 template <> struct ratio_string<centi, wchar_t>;
1168 template <> struct ratio_string<deci, char>;
1169 template <> struct ratio_string<deci, char16_t>;
1170 template <> struct ratio_string<deci, char32_t>;
1171 template <> struct ratio_string<deci, wchar_t>;
1173 template <> struct ratio_string<deca, char>;
1174 template <> struct ratio_string<deca, char16_t>;
1175 template <> struct ratio_string<deca, char32_t>;
1176 template <> struct ratio_string<deca, wchar_t>;
1178 template <> struct ratio_string<hecto, char>;
1179 template <> struct ratio_string<hecto, char16_t>;
1180 template <> struct ratio_string<hecto, char32_t>;
1181 template <> struct ratio_string<hecto, wchar_t>;
1183 template <> struct ratio_string<kilo, char>;
1184 template <> struct ratio_string<kilo, char16_t>;
1185 template <> struct ratio_string<kilo, char32_t>;
1186 template <> struct ratio_string<kilo, wchar_t>;
1188 template <> struct ratio_string<mega, char>;
1189 template <> struct ratio_string<mega, char16_t>;
1190 template <> struct ratio_string<mega, char32_t>;
1191 template <> struct ratio_string<mega, wchar_t>;
1193 template <> struct ratio_string<giga, char>;
1194 template <> struct ratio_string<giga, char16_t>;
1195 template <> struct ratio_string<giga, char32_t>;
1196 template <> struct ratio_string<giga, wchar_t>;
1198 template <> struct ratio_string<tera, char>;
1199 template <> struct ratio_string<tera, char16_t>;
1200 template <> struct ratio_string<tera, char32_t>;
1201 template <> struct ratio_string<tera, wchar_t>;
1203 template <> struct ratio_string<peta, char>;
1204 template <> struct ratio_string<peta, char16_t>;
1205 template <> struct ratio_string<peta, char32_t>;
1206 template <> struct ratio_string<peta, wchar_t>;
1208 template <> struct ratio_string<exa, char>;
1209 template <> struct ratio_string<exa, char16_t>;
1210 template <> struct ratio_string<exa, char32_t>;
1211 template <> struct ratio_string<exa, wchar_t>;
1213 template <> struct ratio_string<kibi, char>;
1214 template <> struct ratio_string<kibi, char16_t>;
1215 template <> struct ratio_string<kibi, char32_t>;
1216 template <> struct ratio_string<kibi, wchar_t>;
1218 template <> struct ratio_string<mebi, char>;
1219 template <> struct ratio_string<mebi, char16_t>;
1220 template <> struct ratio_string<mebi, char32_t>;
1221 template <> struct ratio_string<mebi, wchar_t>;
1223 template <> struct ratio_string<gibi, char>;
1224 template <> struct ratio_string<gibi, char16_t>;
1225 template <> struct ratio_string<gibi, char32_t>;
1226 template <> struct ratio_string<gibi, wchar_t>;
1228 template <> struct ratio_string<tebi, char>;
1229 template <> struct ratio_string<tebi, char16_t>;
1230 template <> struct ratio_string<tebi, char32_t>;
1231 template <> struct ratio_string<tebi, wchar_t>;
1233 template <> struct ratio_string<pebi, char>;
1234 template <> struct ratio_string<pebi, char16_t>;
1235 template <> struct ratio_string<pebi, char32_t>;
1236 template <> struct ratio_string<pebi, wchar_t>;
1238 template <> struct ratio_string<yobi, char>;
1239 template <> struct ratio_string<yobi, char16_t>;
1240 template <> struct ratio_string<yobi, char32_t>;
1241 template <> struct ratio_string<yobi, wchar_t>;
1245 [section:ratio_string Template Class `ratio_string<>`]
1247 template <class Ratio, class CharT>
1250 static std::basic_string<CharT> symbol();
1251 static std::basic_string<CharT> prefix();
1252 static std::basic_string<CharT> short_name(); // DEPRECATED V2
1253 static std::basic_string<CharT> long_name(); // DEPRECATED V2
1256 The class template ratio_string provides textual representations of the associated ratio appropriate for the character type charT.
1258 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.
1260 [section:prefix Static Member function `prefix()`]
1262 template<class Ratio, class CharT>
1264 ratio_string<Ratio, CharT>::prefix();
1266 [*Returns]: A basic_string of the form: [Ratio::num/Ratio::den]
1268 [*Example]: `ratio_string<ratio<2, 60>, wchar_t>::prefix()` returns `L"[1/30]"`.
1272 [section:symbol Static Member function `symbol()`]
1274 template<class Ratio, class CharT>
1276 ratio_string<Ratio, CharT>::symbol();
1278 [*Returns]: prefix().
1282 [section:long_name Static Member function `long_name()` DEPRECATED V2]
1284 template<class Ratio, class CharT>
1286 ratio_string<Ratio, CharT>::long_name();
1288 [*Returns]: prefix().
1291 [section:short_name Static Member function `short_name()` DEPRECATED V2]
1293 template<class Ratio, class CharT>
1295 ratio_string<Ratio, CharT>::short_name();
1297 [*Returns]: symbol().
1303 [section:spe Specializations for `ratio_string<>`]
1306 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
1307 define the macros BOOST_NO_CXX11_U16STRING and BOOST_NO_CXX11_U32STRING until Boost.Config defines them.
1309 For each specialization the table gives the return value for `prefix()` and `symbol()`.
1311 [table The return values of specializations of ratio_string
1312 [[Specialization][`prefix()`] [`symbol()`]]
1313 [[`ratio_string<atto, char>`][`"atto"`] [`"a"`]]
1314 [[`ratio_string<atto, char16_t>`][`u"atto"`] [`u"a"`]]
1315 [[`ratio_string<atto, char32_t>`][`U"atto"`] [`U"a"`]]
1316 [[`ratio_string<atto, wchar_t>`][`L"atto"`] [`L"a"`]]
1318 [[`ratio_string<femto, char>`][`"femto"`] [`"f"`]]
1319 [[`ratio_string<femto, char16_t>`][`u"femto"`] [`u"f"`]]
1320 [[`ratio_string<femto, char32_t>`][`U"femto"`] [`U"f"`]]
1321 [[`ratio_string<femto, wchar_t>`][`L"femto"`] [`L"f"`]]
1323 [[`ratio_string<pico, char>`][`"pico"`] [`"p"`]]
1324 [[`ratio_string<pico, char16_t>`][`u"pico"`] [`u"p"`]]
1325 [[`ratio_string<pico, char32_t>`][`U"pico"`] [`U"p"`]]
1326 [[`ratio_string<pico, wchar_t>`][`L"pico"`] [`L"p"`]]
1328 [[`ratio_string<nano, char>`][`"nano"`] [`"a"`]]
1329 [[`ratio_string<nano, char16_t>`][`u"nano"`] [`u"a"`]]
1330 [[`ratio_string<nano, char32_t>`][`U"nano"`] [`U"a"`]]
1331 [[`ratio_string<nano, wchar_t>`][`L"nano"`] [`L"a"`]]
1333 [[`ratio_string<micro, char>`][`"micro"`] [`u8"\u00B5"`]]
1334 [[`ratio_string<micro, char16_t>`][`u"micro"`] [`u"\u00B5"`]]
1335 [[`ratio_string<micro, char32_t>`][`U"micro"`] [`U"\u00B5"`]]
1336 [[`ratio_string<micro, wchar_t>`][`L"micro"`] [`Lu8"\u00B5"`]]
1338 [[`ratio_string<milli, char>`][`"milli"`] [`"m"`]]
1339 [[`ratio_string<milli, char16_t>`][`u"milli"`] [`u"m"`]]
1340 [[`ratio_string<milli, char32_t>`][`U"milli"`] [`U"m"`]]
1341 [[`ratio_string<milli, wchar_t>`][`L"milli"`] [`L"m"`]]
1343 [[`ratio_string<centi, char>`][`"centi"`] [`"c"`]]
1344 [[`ratio_string<centi, char16_t>`][`u"centi"`] [`u"c"`]]
1345 [[`ratio_string<centi, char32_t>`][`U"centi"`] [`U"c"`]]
1346 [[`ratio_string<centi, wchar_t>`][`L"centi"`] [`L"c"`]]
1348 [[`ratio_string<deci, char>`][`"deci"`] [`"d"`]]
1349 [[`ratio_string<deci, char16_t>`][`u"deci"`] [`u"d"`]]
1350 [[`ratio_string<deci, char32_t>`][`U"deci"`] [`U"d"`]]
1351 [[`ratio_string<deci, wchar_t>`][`L"deci"`] [`L"d"`]]
1353 [[`ratio_string<deca, char>`][`"deca"`] [`"da"`]]
1354 [[`ratio_string<deca, char16_t>`][`u"deca"`] [`u"da"`]]
1355 [[`ratio_string<deca, char32_t>`][`U"deca"`] [`U"da"`]]
1356 [[`ratio_string<deca, wchar_t>`][`L"deca"`] [`L"da"`]]
1358 [[`ratio_string<hecto, char>`][`"hecto"`] [`"h"`]]
1359 [[`ratio_string<hecto, char16_t>`][`u"hecto"`] [`u"h"`]]
1360 [[`ratio_string<hecto, char32_t>`][`U"hecto"`] [`U"h"`]]
1361 [[`ratio_string<hecto, wchar_t>`][`L"hecto"`] [`L"h"`]]
1363 [[`ratio_string<kilo, char>`][`"kilo"`] [`"k"`]]
1364 [[`ratio_string<kilo, char16_t>`][`u"kilo"`] [`u"k"`]]
1365 [[`ratio_string<kilo, char32_t>`][`U"kilo"`] [`U"k"`]]
1366 [[`ratio_string<kilo, wchar_t>`][`L"kilo"`] [`L"k"`]]
1368 [[`ratio_string<mega, char>`][`"mega"`] [`"M"`]]
1369 [[`ratio_string<mega, char16_t>`][`u"mega"`] [`u"M"`]]
1370 [[`ratio_string<mega, char32_t>`][`U"mega"`] [`U"M"`]]
1371 [[`ratio_string<mega, wchar_t>`][`L"mega"`] [`L"M"`]]
1373 [[`ratio_string<giga, char>`][`"giga"`] [`"G"`]]
1374 [[`ratio_string<giga, char16_t>`][`u"giga"`] [`u"G"`]]
1375 [[`ratio_string<giga, char32_t>`][`U"giga"`] [`U"G"`]]
1376 [[`ratio_string<giga, wchar_t>`][`L"giga"`] [`L"G"`]]
1378 [[`ratio_string<tera, char>`][`"tera"`] [`"T"`]]
1379 [[`ratio_string<tera, char16_t>`][`u"tera"`] [`u"T"`]]
1380 [[`ratio_string<tera, char32_t>`][`U"tera"`] [`U"T"`]]
1381 [[`ratio_string<tera, wchar_t>`][`L"tera"`] [`L"T"`]]
1383 [[`ratio_string<peta, char>`][`"peta"`] [`"P"`]]
1384 [[`ratio_string<peta, char16_t>`][`u"peta"`] [`u"P"`]]
1385 [[`ratio_string<peta, char32_t>`][`U"peta"`] [`U"P"`]]
1386 [[`ratio_string<peta, wchar_t>`][`L"peta"`] [`L"P"`]]
1388 [[`ratio_string<exa, char>`][`"exa"`] [`"E"`]]
1389 [[`ratio_string<exa, char16_t>`][`u"exa"`] [`u"E"`]]
1390 [[`ratio_string<exa, char32_t>`][`U"exa"`] [`U"E"`]]
1391 [[`ratio_string<exa, wchar_t>`][`L"exa"`] [`L"E"`]]
1398 [section:mpl Rational Constant]
1400 [/===========================================]
1401 [section:rational_constant Rational Constant Concept]
1402 [/===========================================]
1404 [heading Description]
1406 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.
1408 [heading Expression requirements]
1410 In the following table and subsequent specifications, r is a model of __Rational_Constant.
1413 [[Expression][Type] [Complexity]]
1414 [[`r::tag`][`rational_c_tag`] [Constant time]]
1415 [[`r::value_type`][A rational type] [Constant time]]
1416 [[`r::num_type`][An integral type] [Constant time]]
1417 [[`r::den_type`][An integral type] [Constant time]]
1418 [[`r::num`][An Integral constant expression] [Constant time]]
1419 [[`r::den`][An Integral constant expression] [Constant time]]
1420 [[`r::type`][__Rational_Constant] [Constant time]]
1421 [[`r::value_type const c=r()`][] [Constant time]]
1424 [heading Expression semantics]
1427 [[Expression][Semantics]]
1428 [[`r::tag`][r's tag type; r::tag::value is r's conversion rank.]]
1429 [[`r::value_type`][A cv-unqualified type of `r()`]]
1430 [[`r::num_type`][A cv-unqualified type of `r::num`]]
1431 [[`r::den_type`][A cv-unqualified type of `r::den`]]
1432 [[`r::num`][The numerator of the rational constant]]
1433 [[`r::den`][The denominator of the rational constant]]
1434 [[`r::type`][equal_to<n::type,n>::value == true.]]
1435 [[`r::value_type const c=r()`][`r::value_type const c=r::value_type(r::num,r::den)`]]
1444 [/===========================================]
1445 [section:rational_constant_hpp Header `<boost/ratio/mpl/rational_constant.hpp>`]
1446 [/===========================================]
1448 This header includes all the rational constant related header files
1450 #include <boost/ratio/mpl/rational_c_tag.hpp>
1451 #include <boost/ratio/mpl/numeric_cast.hpp>
1452 #include <boost/ratio/mpl/arithmetic.hpp>
1453 #include <boost/ratio/mpl/comparison.hpp>
1456 [endsect] [/section:rational_constant_hpp Header `<boost/ratio/rational_constant.hpp>`]
1458 [/===========================================]
1459 [section:mpl_rational_c_tag_hpp Header `<boost/ratio/mpl/rational_c_tag.hpp>`]
1460 [/===========================================]
1465 struct rational_c_tag : int_<10> {};
1470 [endsect] [/section:mpl_rational_c_tag_hpp Header `<boost/ratio/mpl/rational_c_tag.hpp>`]
1472 [/===========================================]
1473 [section:mpl_numeric_cast_hpp Header `<boost/ratio/mpl/numeric_cast.hpp>`]
1474 [/===========================================]
1479 template<> struct numeric_cast< integral_c_tag,rational_c_tag >;
1484 [section:numeric_cast `mpl::numeric_cast<>` Specialization]
1486 A Integral Constant is seen as a ratio with numerator the Integral Constant value and denominator 1.
1488 template<> struct numeric_cast< integral_c_tag,rational_c_tag >
1490 template< typename N > struct apply
1491 : ratio< N::value, 1 >
1496 [endsect] [/section:numeric_cast `mpl::numeric_cast<>` Specialization]
1498 [endsect] [/section:mpl_numeric_cast_hpp Header `<boost/ratio/mpl/numeric_cast.hpp>`]
1500 [/===========================================]
1501 [section:mpl_arithmetic_hpp Header `<boost/ratio/mpl/arithmetic.hpp>`]
1502 [/===========================================]
1504 This header includes all the rational constant arithmetic MPL specializations.
1506 #include <boost/ratio/mpl/plus.hpp>
1507 #include <boost/ratio/mpl/minus.hpp>
1508 #include <boost/ratio/mpl/times.hpp>
1509 #include <boost/ratio/mpl/divides.hpp>
1510 #include <boost/ratio/mpl/negate.hpp>
1511 #include <boost/ratio/mpl/abs.hpp>
1512 #include <boost/ratio/mpl/sign.hpp>
1513 #include <boost/ratio/mpl/gcd.hpp>
1514 #include <boost/ratio/mpl/lcm.hpp>
1517 [endsect] [/section:mpl_arithmetic_hpp Header `<boost/ratio/mpl/arithmetic.hpp>`]
1519 [/===========================================]
1520 [section:mpl_plus_hpp Header `<boost/ratio/mpl/plus.hpp>`]
1521 [/===========================================]
1526 struct plus_impl< rational_c_tag,rational_c_tag >;
1530 [section:plus_impl `mpl::plus_impl<>` Specialization]
1532 The specialization relays on the __ratio_add template class.
1535 struct plus_impl< rational_c_tag,rational_c_tag >
1537 template< typename R1, typename R2 > struct apply
1538 : __ratio_add<R1, R2>
1543 [endsect] [/section:plus_impl `mpl::plus_impl<>` Specialization]
1544 [endsect] [/section:mpl_plus_hpp Header `<boost/ratio/mpl/plus.hpp>`]
1546 [/===========================================]
1547 [section:mpl_minus_hpp Header `<boost/ratio/mpl/minus.hpp>`]
1548 [/===========================================]
1553 struct minus_impl< rational_c_tag,rational_c_tag >;
1557 [section:minus_impl `mpl::minus_impl<>` Specialization]
1559 The specialization relays on the __ratio_subtract template class.
1562 struct plus_impl< rational_c_tag,rational_c_tag >
1564 template< typename R1, typename R2 > struct apply
1565 : __ratio_subtract<R1, R2>
1570 [endsect] [/section:minus_impl `mpl::minus_impl<>` Specialization]
1571 [endsect] [/section:mpl_minus_hpp Header `<boost/ratio/mpl/minus.hpp>`]
1573 [/===========================================]
1574 [section:mpl_times_hpp Header `<boost/ratio/mpl/times.hpp>`]
1575 [/===========================================]
1580 struct times_impl< rational_c_tag,rational_c_tag >;
1584 [section:times_impl `mpl::times_impl<>` Specialization]
1586 The specialization relays on the __ratio_multiply template class.
1589 struct times_impl< rational_c_tag,rational_c_tag >
1591 template< typename R1, typename R2 > struct apply
1592 : __ratio_multiply<R1, R2>
1597 [endsect] [/section:times_impl `mpl::times_impl<>` Specialization]
1598 [endsect] [/section:mpl_times_hpp Header `<boost/ratio/mpl/times.hpp>`]
1600 [/===========================================]
1601 [section:mpl_divides_hpp Header `<boost/ratio/mpl/divides.hpp>`]
1602 [/===========================================]
1607 struct divides_impl< rational_c_tag,rational_c_tag >;
1611 [section:divides_impl `mpl::divides_impl<>` Specialization]
1613 The specialization relays on the __ratio_divide template class.
1616 struct divides_impl< rational_c_tag,rational_c_tag >
1618 template< typename R1, typename R2 > struct apply
1619 : __ratio_divide<R1, R2>
1624 [endsect] [/section:divides_impl `mpl::divides_impl<>` Specialization]
1625 [endsect] [/section:mpl_divides_hpp Header `<boost/ratio/mpl/divides.hpp>`]
1627 [/===========================================]
1628 [section:mpl_gcd_hpp Header `<boost/ratio/mpl/gcd.hpp>`]
1629 [/===========================================]
1634 struct gcd_impl< rational_c_tag,rational_c_tag >;
1638 [section:gcd_impl `mpl::gcd_impl<>` Specialization]
1640 The specialization relays on the __ratio_gcd template class.
1643 struct gcd_impl< rational_c_tag,rational_c_tag >
1645 template< typename R1, typename R2 > struct apply
1646 : __ratio_gcd<R1, R2>
1651 [endsect] [/section:gcd_impl `mpl::gcd_impl<>` Specialization]
1652 [endsect] [/section:mpl_gcd_hpp Header `<boost/ratio/mpl/gcd.hpp>`]
1654 [/===========================================]
1655 [section:mpl_lcm_hpp Header `<boost/ratio/mpl/lcm.hpp>`]
1656 [/===========================================]
1661 struct lcm_impl< rational_c_tag,rational_c_tag >;
1665 [section:lcm_impl `mpl::lcm_impl<>` Specialization]
1667 The specialization relays on the __ratio_lcm template class.
1670 struct lcm_impl< rational_c_tag,rational_c_tag >
1672 template< typename R1, typename R2 > struct apply
1673 : __ratio_lcm<R1, R2>
1678 [endsect] [/section:lcm_impl `mpl::lcm_impl<>` Specialization]
1679 [endsect] [/section:mpl_lcm_hpp Header `<boost/ratio/mpl/lcm.hpp>`]
1681 [/===========================================]
1682 [section:mpl_negate_hpp Header `<boost/ratio/mpl/negate.hpp>`]
1683 [/===========================================]
1688 struct negate_impl< rational_c_tag >;
1692 [section:negate_impl `mpl::negate_impl<>` Specialization]
1694 The specialization relays on the __ratio_negate template class.
1697 struct negate_impl< rational_c_tag >
1699 template< typename R > struct apply
1705 [endsect] [/section:negate_impl `mpl::negate_impl<>` Specialization]
1706 [endsect] [/section:mpl_negate_hpp Header `<boost/ratio/mpl/negate.hpp>`]
1708 [/===========================================]
1709 [section:mpl_abs_hpp Header `<boost/ratio/mpl/abs.hpp>`]
1710 [/===========================================]
1715 struct abs_impl< rational_c_tag >;
1719 [section:abs_impl `mpl::abs_impl<>` Specialization]
1721 The specialization relays on the __ratio_abs template class.
1724 struct abs_impl< rational_c_tag >
1726 template< typename R > struct apply
1732 [endsect] [/section:abs_impl `mpl::abs_impl<>` Specialization]
1733 [endsect] [/section:mpl_abs_hpp Header `<boost/ratio/mpl/abs.hpp>`]
1735 [/===========================================]
1736 [section:mpl_sign_hpp Header `<boost/ratio/mpl/sign.hpp>`]
1737 [/===========================================]
1742 struct sign_impl< rational_c_tag >;
1746 [section:sign_impl `mpl::sign_impl<>` Specialization]
1748 The specialization relays on the __ratio_sign template class.
1751 struct sign_impl< rational_c_tag >
1753 template< typename R > struct apply
1759 [endsect] [/section:sign_impl `mpl::sign_impl<>` Specialization]
1760 [endsect] [/section:mpl_sign_hpp Header `<boost/ratio/mpl/sign.hpp>`]
1762 [/===========================================]
1763 [section:mpl_comparison_hpp Header `<boost/ratio/mpl/comparison.hpp>`]
1764 [/===========================================]
1766 This header includes all the rational constant comparison MPL specializations.
1768 #include <boost/ratio/mpl/equal_to.hpp>
1769 #include <boost/ratio/mpl/not_equal_to.hpp>
1770 #include <boost/ratio/mpl/less.hpp>
1771 #include <boost/ratio/mpl/less_equal.hpp>
1772 #include <boost/ratio/mpl/greater.hpp>
1773 #include <boost/ratio/mpl/greater_equal.hpp>
1776 [endsect] [/section:mpl_comparison_hpp Header `<boost/ratio/mpl/mpl_comparison_hpp.hpp>`]
1778 [/===========================================]
1779 [section:mpl_equal_to_hpp Header `<boost/ratio/mpl/equal_to.hpp>`]
1780 [/===========================================]
1785 struct equal_to_impl< rational_c_tag,rational_c_tag >;
1789 [section:equal_to `mpl::equal_to_impl<>` Specialization]
1791 The specialization relays on the __ratio_equal template class.
1794 struct equal_to_impl< rational_c_tag,rational_c_tag >
1796 template< typename R1, typename R2 > struct apply
1797 : __ratio_equal<R1, R2>
1802 [endsect] [/section:equal_to `mpl::equal_to_impl<>` Specialization]
1803 [endsect] [/section:mpl_equal_to_hpp Header `<boost/ratio/mpl/equal_to.hpp>`]
1805 [/===========================================]
1806 [section:mpl_not_equal_to_hpp Header `<boost/ratio/mpl/not_equal_to.hpp>`]
1807 [/===========================================]
1812 struct not_equal_to_impl< rational_c_tag,rational_c_tag >;
1816 [section:not_equal_to `mpl::not_equal_to_impl<>` Specialization]
1818 The specialization relays on the __ratio_not_equal template class.
1821 struct not_equal_to_impl< rational_c_tag,rational_c_tag >
1823 template< typename R1, typename R2 > struct apply
1824 : __ratio_not_equal<R1, R2>
1829 [endsect] [/section:not_equal_to `mpl::not_equal_to_impl<>` Specialization]
1830 [endsect] [/section:mpl_not_equal_to_hpp Header `<boost/ratio/mpl/not_equal_to.hpp>`]
1832 [/===========================================]
1833 [section:mpl_less_hpp Header `<boost/ratio/mpl/less.hpp>`]
1834 [/===========================================]
1839 struct less_impl< rational_c_tag,rational_c_tag >;
1843 [section:less `mpl::less_impl<>` Specialization]
1845 The specialization relays on the __ratio_less template class.
1848 struct less_impl< rational_c_tag,rational_c_tag >
1850 template< typename R1, typename R2 > struct apply
1851 : ratio_less<R1, R2>
1856 [endsect] [/section:less `mpl::less_impl<>` Specialization]
1857 [endsect] [/section:mpl_less_hpp Header `<boost/ratio/mpl/less.hpp>`]
1859 [/===========================================]
1860 [section:mpl_less_equal_hpp Header `<boost/ratio/mpl/less_equal.hpp>`]
1861 [/===========================================]
1866 struct less_equal_impl< rational_c_tag,rational_c_tag >;
1870 [section:less_equal `mpl::less_equal_impl<>` Specialization]
1872 The specialization relays on the __ratio_less_equal template class.
1875 struct less_equal_impl< rational_c_tag,rational_c_tag >
1877 template< typename R1, typename R2 > struct apply
1878 : ratio_less_equal<R1, R2>
1883 [endsect] [/section:less_equal `mpl::less_equal_impl<>` Specialization]
1884 [endsect] [/section:mpl_less_equal_hpp Header `<boost/ratio/mpl/less_equal.hpp>`]
1886 [/===========================================]
1887 [section:mpl_greater_hpp Header `<boost/ratio/mpl/greater.hpp>`]
1888 [/===========================================]
1893 struct greater_impl< rational_c_tag,rational_c_tag >;
1897 [section:greater `mpl::greater_impl<>` Specialization]
1899 The specialization relays on the __ratio_greater template class.
1902 struct greater_impl< rational_c_tag,rational_c_tag >
1904 template< typename R1, typename R2 > struct apply
1905 : ratio_greater<R1, R2>
1910 [endsect] [/section:greater `mpl::greater_impl<>` Specialization]
1911 [endsect] [/section:mpl_greater_hpp Header `<boost/ratio/mpl/greater.hpp>`]
1914 [/===========================================]
1915 [section:mpl_greater_equal_hpp Header `<boost/ratio/mpl/greater_equal.hpp>`]
1916 [/===========================================]
1921 struct greater_equal_impl< rational_c_tag,rational_c_tag >;
1925 [section:greater_equal `mpl::greater_equal_impl<>` Specialization]
1927 The specialization relays on the __ratio_greater_equal template class.
1930 struct greater_equal_impl< rational_c_tag,rational_c_tag >
1932 template< typename R1, typename R2 > struct apply
1933 : ratio_greater_equal<R1, R2>
1938 [endsect] [/section:greater_equal `mpl::greater_equal_impl<>` Specialization]
1939 [endsect] [/section:mpl_greater_equal_hpp Header `<boost/ratio/mpl/greater_equal.hpp>`]
1946 [/=================]
1947 [section Appendices]
1948 [/=================]
1949 [/==================================]
1950 [section:history Appendix A: History]
1951 [/==================================]
1953 [section [*Version 2.1.0, Febreary 1, 2014 - 1.56] ]
1957 * [@http://svn.boost.org/trac/boost/ticket/XXXX #XXXX] Add ratio_power.
1958 * [@http://svn.boost.org/trac/boost/ticket/XXXX #XXXX] Add IEC binary prefixes.
1961 [section [*Version 2.0.1, Febreary 1, 2013 - 1.53] ]
1965 * [@http://svn.boost.org/trac/boost/ticket/7616 #7616] br_mul::nan - warning C4293: '<<' : shift count negative or too big, undefined behavior`.
1969 [section [*Version 2.0.0, November 1, 2012 - 1.52] ]
1973 * Replace the short_name and long_name functions by symbol and prefix functions respectively.
1977 The ratio_string<>::short_name and ratio_string<>::long_name are deprecated. Use ratio_string<>::symbol and ratio_string<>::prefix respectively. These functions be removed in 1.55.
1981 * [@http://svn.boost.org/trac/boost/ticket/7478 #7478] Compiles fails with compilers supporting char16_t and char32_t fails if the library doesn't provides std::u16string and std::u32string.
1985 [section [*Version 1.0.3, August 1, 2012 - 1.51] ]
1989 * [@http://svn.boost.org/trac/boost/ticket/7075 #7075] Workaround for error: the type of partial specialization template parameter constant "n1" depends on another template parameter.
1993 [section [*Version 1.0.2, April 1, 2012 - 1.50] ]
1997 * [@http://svn.boost.org/trac/boost/ticket/6498 #6498] boost::ratio won't compile with default settings.
2001 [section [*Version 1.0.1, Jan 8, 2011 ] ]
2005 * Added MPL Rational Constant and the associated numeric metafunction specializations.
2009 [section [*Version 1.0.0, Jan 2, 2011] ]
2011 * Moved ratio to trunk.
2012 * Documentation revision.
2016 [section [*Version 0.2.1, September 27, 2010] ]
2019 * Removal of LLVM adapted files due to incompatible License issue.
2023 [section [*Version 0.2.0, September 22, 2010] ]
2026 * Added ratio_string traits.
2030 * ratio_less overflow avoided following the algorithm from libc++.
2034 * A more complete test has been included adapted from the test of from libc++/ratio.
2038 [section [*Version 0.1.0, September 10, 2010] ]
2041 * Ratio has been extracted from Boost.Chrono.
2045 [endsect] [/section:history Appendix A: History]
2047 [/======================================]
2048 [section:rationale Appendix B: Rationale]
2050 [heading Why ratio needs CopyConstruction and Assignment from ratios having the same normalized form]
2052 Current [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n3000.pdf [*N3000]] doesn't allows to copy-construct or assign ratio instances of ratio classes having the same normalized form.
2060 fails to compile in (1). Other example
2063 __ratio_subtract<__ratio<2,3>,__ratio<1,3> > r2=r1; // (2)
2065 The type of `__ratio_subtract<__ratio<2,3>,__ratio<1,3> >` could be `__ratio<3,9>` so the compilation could fail in (2). It could also be __ratio<1,3> and the compilation succeeds.
2067 [heading Why ratio needs the nested normalizer typedef type]
2069 The current resolution of issue LWG 1281 acknowledges the need for a nested type typedef, so Boost.Ratio is tracking the likely final version of std::ratio.
2071 [endsect] [/section:rationale Appendix B: Rationale]
2074 [/======================================================]
2075 [section:implementation Appendix C: Implementation Notes]
2077 [heading How does Boost.Ratio try to avoid compile-time rational arithmetic overflow?]
2079 When the result is representable, but a simple application of arithmetic rules would result in overflow, e.g. `ratio_multiply<ratio<INTMAX_MAX,2>,ratio<2,INTMAX_MAX>>` can be reduced to `ratio<1,1>`, but the direct result of `ratio<INTMAX_MAX*2,INTMAX_MAX*2>` would result in overflow.
2081 Boost.Ratio implements some simplifications in order to reduce the possibility of overflow. The general ideas are:
2083 * The `num` and `den` `ratio<>` fields are normalized.
2084 * Use the gcd of some of the possible products that can overflow, and simplify before doing the product.
2085 * Use some equivalences relations that avoid addition or subtraction that can overflow or underflow.
2087 The following subsections cover each case in more detail.
2093 (n1/d1)+(n2/d2)=(n1*d2+n2*d1)/(d1*d2)
2095 either n1*d2+n2*d1 or d1*d2 can overflow.
2097 ( (n1 * d2) + (n2 * d1) )
2098 --------------------------
2101 Dividing by gcd(d1,d2) on both num and den
2103 ( (n1 * (d2/gcd(d1,d2))) + (n2 * (d1/gcd(d1,d2))) )
2104 ----------------------------------------------------
2105 ((d1 * d2) / gcd(d1,d2))
2108 Multiplying and diving by gcd(n1,n2) in numerator
2110 ( ((gcd(n1,n2)*(n1/gcd(n1,n2))) * (d2/gcd(d1,d2))) +
2111 ((gcd(n1,n2)*(n2/gcd(n1,n2))) * (d1/gcd(d1,d2)))
2113 --------------------------------------------------
2114 ( (d1 * d2) / gcd(d1,d2) )
2116 Factorizing gcd(n1,n2)
2119 ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
2121 -------------------------------------------------------------------------------
2122 ( (d1 * d2) / gcd(d1,d2) )
2127 ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
2129 -------------------------------------------------------------------------------
2130 ( (d1 / gcd(d1,d2)) * d2 )
2132 Dividing by (d1 / gcd(d1,d2))
2134 ( ( gcd(n1,n2) / (d1 / gcd(d1,d2)) ) *
2135 ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
2137 -------------------------------------------------------------------------------
2143 ( gcd(n1,n2) / (d1 / gcd(d1,d2)) ) *
2144 ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) / d2 )
2146 This expression correspond to the multiply of two ratios that have less risk of overflow as the initial numerators and denominators appear now in most of the cases divided by a gcd.
2149 For ratio_subtract the reasoning is the same.
2155 (n1/d1)*(n2/d2)=((n1*n2)/(d1*d2))
2157 either n1*n2 or d1*d2 can overflow.
2159 Dividing by gcc(n1,d2) numerator and denominator
2161 (((n1/gcc(n1,d2))*n2)
2162 ---------------------
2163 (d1*(d2/gcc(n1,d2))))
2165 Dividing by gcc(n2,d1)
2167 ((n1/gcc(n1,d2))*(n2/gcc(n2,d1)))
2168 ---------------------------------
2169 ((d1/gcc(n2,d1))*(d2/gcc(n1,d2)))
2171 And now all the initial numerator and denominators have been reduced, avoiding the overflow.
2173 For ratio_divide the reasoning is similar.
2177 In order to evaluate
2181 without moving to floating-point numbers, two techniques are used:
2183 * First compare the sign of the numerators.
2185 If sign(n1) < sign(n2) the result is true.
2187 If sign(n1) == sign(n2) the result depends on the following after making the numerators positive
2189 * When the sign is equal the technique used is to work with integer division and modulo when the signs are equal.
2191 Let call Qi the integer division of ni and di, and Mi the modulo of ni and di.
2193 ni = Qi * di + Mi and Mi < di
2201 (((Q1 * d1 + M1)*d2)<(d1*((Q2 * d2 + M2))))
2205 ((Q1 * d1 * d2)+ (M1*d2))<((d1 * Q2 * d2) + (d1*M2))
2209 Q1 + (M1/d1) < Q2 + (M2/d2)
2211 If Q1=Q2 the result depends on
2215 If M1==0==M2 the result is false
2217 If M1=0 M2!=0 the result is true
2219 If M1!=0 M2==0 the result is false
2221 If M1!=0 M2!=0 the result depends on
2225 If Q1!=Q2, the result of
2227 Q1 + (M1/d1) < Q2 + (M2/d2)
2229 depends only on Q1 and Q2 as Qi are integers and (Mi/di) <1 because Mi<di.
2231 if Q1>Q2, Q1==Q2+k, k>=1
2233 Q2+k + (M1/d1) < Q2 + (M2/d2)
2234 k + (M1/d1) < (M2/d2)
2235 k < (M2/d2) - (M1/d1)
2237 but the difference between two numbers between 0 and 1 can not be greater than 1, so the result is false.
2239 if Q2>Q1, Q2==Q1+k, k>=1
2241 Q1 + (M1/d1) < Q1+k + (M2/d2)
2242 (M1/d1) < k + (M2/d2)
2243 (M1/d1) - (M2/d2) < k
2245 which is always true, so the result is true.
2247 The following table recapitulates this analisys
2250 [[ratio<n1,d1>][ratio<n2,d2>] [Q1] [Q2] [M1] [M2] [Result]]
2251 [[ratio<n1,d1>][ratio<n2,d2>] [Q1] [Q2] [!=0] [!=0] [Q1 < Q2]]
2252 [[ratio<n1,d1>][ratio<n2,d2>] [Q] [Q] [0] [0] [false]]
2253 [[ratio<n1,d1>][ratio<n2,d2>] [Q] [Q] [0] [!=0] [true]]
2254 [[ratio<n1,d1>][ratio<n2,d2>] [Q] [Q] [!=0] [0] [false]]
2255 [[ratio<n1,d1>][ratio<n2,d2>] [Q] [Q] [!=0] [!=0] [ratio_less<ratio<d2,M2>, ratio<d1/M1>>]]
2258 [endsect] [/section:implementation Appendix C: Implementation Notes]
2260 [/======================================================]
2261 [section:faq Appendix D: FAQ]
2262 [/======================================================]
2264 [endsect] [/section:faq Appendix D: FAQ]
2267 [/====================================================]
2268 [section:acknowledgements Appendix E: Acknowledgements]
2269 [/====================================================]
2271 The library code was derived from Howard Hinnant's `time2_demo` prototype. Many thanks to Howard for making his code available under the Boost license. The original code was modified by Beman Dawes to conform to Boost conventions.
2273 `time2_demo` contained this comment:
2275 Much thanks to Andrei Alexandrescu, Walter Brown, Peter Dimov, Jeff Garland, Terry Golubiewski, Daniel Krugler, Anthony Williams.
2277 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.
2279 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.
2281 Thanks to Andrew Chinoff and Paul A. Bristol for his help polishing the documentation.
2283 [endsect] [/section:acknowledgements Appendix E: Acknowledgements]
2285 [/====================================================]
2286 [section:tests Appendix F: Tests]
2287 [/====================================================]
2289 In order to test you need to run
2291 bjam libs/ratio/test
2293 You can also run a specific suite of test by doing
2301 [[Name] [kind] [Description] [Result] [Ticket]]
2302 [[typedefs.pass] [run] [check the num/den are correct for the predefined typedefs] [Pass] [#]]
2303 [[ratio.pass] [run] [check the num/den are correctly simplified] [Pass] [#]]
2304 [[ratio1.fail] [compile-fails] [The template argument D shall not be zero] [Pass] [#]]
2305 [[ratio2.fail] [compile-fails] [the absolute values of the template arguments N and D shall be representable by type intmax_t] [Pass] [#]]
2306 [[ratio3.fail] [compile-fails] [the absolute values of the template arguments N and D shall be representable by type intmax_t] [Pass] [#]]
2310 [section `comparison`]
2312 [[Name] [kind] [Description] [Result] [Ticket]]
2313 [[ratio_equal.pass] [run] [check ratio_equal metafunction class] [Pass] [#]]
2314 [[ratio_not_equal.pass] [run] [check ratio_not_equal metafunction class] [Pass] [#]]
2315 [[ratio_less.pass] [run] [check ratio_less metafunction class] [Pass] [#]]
2316 [[ratio_less_equal.pass] [run] [check ratio_less_equal metafunction class] [Pass] [#]]
2317 [[ratio_greater.pass] [run] [check ratio_greater metafunction class] [Pass] [#]]
2318 [[ratio_greater_equal.pass] [run] [check ratio_greater_equal metafunction class] [Pass] [#]]
2322 [section `arithmetic`]
2324 [[Name] [kind] [Description] [Result] [Ticket]]
2325 [[ratio_add.pass] [run] [check ratio_add metafunction class] [Pass] [#]]
2326 [[ratio_subtract.pass] [run] [check ratio_subtract metafunction class] [Pass] [#]]
2327 [[ratio_multiply.pass] [run] [check ratio_multiply metafunction class] [Pass] [#]]
2328 [[ratio_divide.pass] [run] [check ratio_divide metafunction class] [Pass] [#]]
2329 [[ratio_add.fail] [compile-fails] [check ratio_add overflow metafunction class] [Pass] [#]]
2330 [[ratio_subtract.fail] [compile-fails] [check ratio_subtract underflow metafunction class] [Pass] [#]]
2331 [[ratio_multiply.fail] [compile-fails] [check ratio_multiply overflow metafunction class] [Pass] [#]]
2332 [[ratio_divide.fail] [compile-fails] [check ratio_divide overflow metafunction class] [Pass] [#]]
2336 [endsect] [/section:tests Appendix F: Tests]
2338 [/=====================================]
2339 [section:tickets Appendix G: Tickets]
2340 [/=====================================]
2343 [[Ticket] [Description] [Resolution] [State]]
2344 [[1] [result of metafunctions ratio_multiply and ratio_divide were not normalized ratios.] [Use of the nested ratio typedef type on ratio arithmetic operations.] [Closed]]
2345 [[2] [INTMAX_C is not always defined.] [Replace INTMAX_C by BOOST_INTMAX_C until boost/cstdint.hpp ensures INTMAX_C is always defined.] [Closed]]
2347 [[3] [MSVC reports a warning instead of an error when there is an integral constant overflow.] [manage with MSVC reporting a warning instead of an error when there is an integral constant overflow.] [Closed]]
2348 [[4] [ration_less overflow on cases where it can be avoided.] [Change the algorithm as implemented in libc++.] [Closed]]
2349 [/[#] [XXXX] [XXXX] [Closed]]
2352 [endsect] [/section:tickets Appendix G: Tickets]
2355 [/=====================================]
2356 [section:todo Appendix H: Future Plans]
2357 [/=====================================]
2359 [heading For later releases]
2361 * Use template aliases on compiler providing it.
2362 * Implement [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#3135 multiple arguments] ratio arithmetic.
2364 [endsect] [/section:todo Appendix H: Future Plans]
2367 [endsect] [/section Appendices]