|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r67616 - trunk/libs/ratio/doc
From: pbristow_at_[hidden]
Date: 2011-01-03 08:19:31
Author: pbristow
Date: 2011-01-03 08:19:15 EST (Mon, 03 Jan 2011)
New Revision: 67616
URL: http://svn.boost.org/trac/boost/changeset/67616
Log:
Many minor editorial changes to reflect move to trunk etc.
Binary files modified:
trunk/libs/ratio/doc/ratio.pdf
Text files modified:
trunk/libs/ratio/doc/ratio.qbk | 129 +++++++++++++++++++--------------------
1 files changed, 63 insertions(+), 66 deletions(-)
Modified: trunk/libs/ratio/doc/ratio.pdf
==============================================================================
Binary files. No diff available.
Modified: trunk/libs/ratio/doc/ratio.qbk
==============================================================================
--- trunk/libs/ratio/doc/ratio.qbk (original)
+++ trunk/libs/ratio/doc/ratio.qbk 2011-01-03 08:19:15 EST (Mon, 03 Jan 2011)
@@ -1,7 +1,7 @@
[/
/ Copyright (c) 2008 Howard Hinnant
/ Copyright (c) 2006, 2008 Beman Dawes
- / Copyright (c) 2009-20010 Vicente J. Botet Escriba
+ / Copyright (c) 2009-2011 Vicente J. Botet Escriba
/
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -15,7 +15,7 @@
[authors [Botet Escriba, Vicente J.]]
[copyright 2008 Howard Hinnant]
[copyright 2006, 2008 Beman Dawes]
- [copyright 2009-2010 Vicente J. Botet Escriba]
+ [copyright 2009-2011 Vicente J. Botet Escriba]
[license
Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
@@ -74,8 +74,9 @@
[def __peta [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `peta`]]
[def __exa [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `exa`]]
+[template mu[]'''μ'''] [/ µ Greek small letter mu]
-[warning Ratio is not part of the Boost libraries.]
+[/warning Ratio is not part of the Boost libraries.]
[/===============]
[section Overview]
@@ -118,7 +119,7 @@
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
+* 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.
@@ -143,31 +144,28 @@
[heading Getting Boost.Ratio ]
[/=================================]
-You can get the last stable release of __Boost_Ratio__ by downloading [^ratio.zip] from the
-[@http://www.boostpro.com/vault/index.php?action=downloadfile&filename=ratio.zip&directory=Math%20-%20Numerics&PHPSESSID=2d7859f3e812c993f5a9e2d9900dfee8 Boost Vault].
+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/sandbox/chrono Boost Sandbox] 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/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.
[/==========================================]
[heading Where to install Boost.Ratio? ]
[/==========================================]
-The simple way is to decompress (or checkout from SVN) the file in your BOOST_ROOT directory.
-
-Othesewise, if you decompress in a different directory, you will need to comment some lines, and uncomment and change others in the build/Jamfile and test/Jamfile. Sorry for this, but I have not reached yet to write a Jamfile that is able to work in both environements and use the BOOST_ROOT variable. Any help is welcome.
+The simple way is to decompress (or checkout from SVN) the files in your BOOST_ROOT directory.
[/=================================]
[heading Building Boost.Ratio ]
[/=================================]
-__Boost_Ratio__ is a header only library, so no need to compile anything.
+__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 if older versions should works also).
+__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:
@@ -270,9 +268,9 @@
[heading Ratio]
-__ratio is a general purpose utility inspired by Walter Brown allowing one to easily and safely compute rational values at compile time. The __ratio class catches all errors (such as divide by zero and overflow) at compile time. It is used in the duration and __time_point classes to efficiently create units of time. It can also be used in other "quantity" libraries or anywhere there is a rational constant which is known at compile time. The use of this utility can greatly reduce the chances of run time overflow because the __ratio (and any ratios resulting from __ratio arithmetic) are always reduced to lowest terms.
+__ratio is a general purpose utility inspired by Walter Brown allowing one to easily and safely compute rational values at compile-time. The __ratio class catches all errors (such as divide by zero and overflow) at compile time. It is used in the duration and __time_point classes to efficiently create units of time. It can also be used in other "quantity" libraries or anywhere there is a rational constant which is known at compile-time. The use of this utility can greatly reduce the chances of run-time overflow because the __ratio (and any ratios resulting from __ratio arithmetic) are always reduced to the lowest terms.
-__ratio is a template taking two intmax_ts, with the second defaulted to 1. In addition to copy constructors and assignment, it only has two public members, both of which are static const intmax_t. One is the numerator of the __ratio and the other is the denominator. The __ratio is always normalized such that it is expressed in lowest terms, and the denominator is always positive. When the numerator is 0, the denominator is always 1.
+__ratio is a template taking two `intmax_ts`, with the second defaulted to 1. In addition to copy constructors and assignment, it only has two public members, both of which are `static const intmax_t`. One is the numerator of the __ratio and the other is the denominator. The __ratio is always normalized such that it is expressed in lowest terms, and the denominator is always positive. When the numerator is 0, the denominator is always 1.
[*Example:]
@@ -297,7 +295,7 @@
[heading Ratio I/O]
-For each `ratio<N, D>` there exists a `ratio_string<ratio<N, D>, CharT>` for which you can query two strings: `short_name` and `long_name`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] long_name corresponds to the internationally recognized prefix, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::long_name()` returns `string("mega")`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] `short_name` corresponds to the internationally recognized symbol, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::short_name()` returns `string("M")`. For all other `ratio`'s, both `long_name()` and `short_name()` return a `basic_string` containing "[`ratio::num/ratio::den`]".
+For each `ratio<N, D>` there exists a `ratio_string<ratio<N, D>, CharT>` for which you can query two strings: `short_name` and `long_name`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] long_name corresponds to the internationally recognized prefix, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::long_name()` returns `string("mega")`. For those `ratio`s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] `short_name` corresponds to the internationally recognized symbol, stored as a `basic_string<CharT>`. For example, `ratio_string<mega, char>::short_name()` returns `string("M")`. For all other `ratio`s, both `long_name()` and `short_name()` return a `basic_string` containing "[`ratio::num/ratio::den`]".
`ratio_string<ratio<N, D>, CharT>` is only defined for four character types:
@@ -308,7 +306,7 @@
When the character is char, UTF-8 will be used to encode the names. When the character is `char16_t`, UTF-16 will be used to encode the names. When the character is `char32_t`, UTF-32 will be used to encode the names. When the character is `wchar_t`, the encoding will be UTF-16 if `wchar_t` is 16 bits, and otherwise UTF-32.
-The `short_name` for micro is defined by [@http://www.unicode.org/charts/PDF/U0080.pdf Unicode] to be U+00B5.
+The `short_name` (Greek mu or [mu]) for micro is defined by [@http://www.unicode.org/charts/PDF/U0080.pdf Unicode] to be U+00B5.
[*Examples:]
@@ -598,7 +596,7 @@
[
- [[@http://home.roadrunner.com/~hinnant/issue_review/lwg-active.html#1281 [*LWG 1281. CopyConstruction and Assignment between ratios having the same normalized form]]]
+ [[@http://lwg.github.com/issues/lwg-defects.html#1281 [*LWG 1281. CopyConstruction and Assignment between ratios having the same normalized form]]]
[From Vicente Juan Botet Escriba.]
]
@@ -662,26 +660,24 @@
[section:ratio_hpp Header `<boost/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 when needing to efficiently represent 1/3 of a nanosecond, or specifying an inch in terms of meters (for example 254/10000 meters - which __ratio will reduce to 127/5000 meters).
+__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).
- // configuration macros
+ // Configuration macros
#define __BOOST_RATIO_USES_STATIC_ASSERT
#define __BOOST_RATIO_USES_MPL_ASSERT
#define __BOOST_RATIO_USES_ARRAY_ASSERT
-
[section:conf Configuration Macros]
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_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.
The default behavior is as if BOOST_RATIO_USES_ARRAY_ASSERT is defined.
-
When BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are defined as shown:
#define BOOST_RATIO_OVERFLOW_IN_ADD "overflow in ratio add"
@@ -714,9 +710,9 @@
ratio& operator=(const ratio<_N2, _D2>&) {return *this;}
};
-A diagnostic will be emitted if __ratio is instantiated with `D == 0`, or if the absolute value of `N` or `D` can not 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.
+A diagnostic will be emitted if __ratio is instantiated with `D == 0`, or if the absolute value of `N` or `D` cannot be represented. [*Note:] These rules ensure that infinite ratios are avoided and that for any negative input, there exists a representable value of its absolute value which is positive. In a two's complement representation, this excludes the most negative value.
-The members num and den will be normalized values of the template arguments N and D computed as follows. Let `gcd` denote the greatest common divisor of `N`'s absolute value and of `D`'s absolute value. Then:
+The members num and den will be normalized values of the template arguments N and D computed as follows. Let `gcd` denote the greatest common divisor of `N`'s absolute value and of `D`'s absolute value. Then:
* `num` has the value `sign(N)*sign(D)*abs(N)/gcd`.
@@ -872,7 +868,7 @@
[section:ratio_io_hpp Header `<boost/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."
+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 {
@@ -896,12 +892,14 @@
[section:history Appendix A: History]
[/==================================]
-[section [*Version 1.0.0, ?? ??, 2010] ]
+[section [*Version 1.0.0, Jan 2, 2011] ]
+
+* Moved ratio to trunk.
+* Documentation revision.
+
[endsect]
-[/
[section [*Version 0.2.1, September 27, 2010] ]
-
[*Fixes:]
* Removal of LLVM adapted files due to incompatible License issue.
@@ -909,8 +907,7 @@
[endsect]
[section [*Version 0.2.0, September 22, 2010] ]
-
-[*Featurs:]
+[*Features:]
* Added ratio_string traits.
@@ -925,16 +922,13 @@
[endsect]
[section [*Version 0.1.0, September 10, 2010] ]
-
[*Features:]
* Ratio has been extracted from Boost.Chrono.
[endsect]
-]
-
-[endsect]
+[endsect] [/section:history Appendix A: History]
[/======================================]
[section:rationale Appendix B: Rationale]
@@ -960,16 +954,17 @@
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.
-[endsect]
+[endsect] [/section:rationale Appendix B: Rationale]
+
[/======================================================]
[section:implementation Appendix C: Implementation Notes]
-[heading How Boost.Ratio manage with compile-time rational arithmetic overflow?]
+[heading How does Boost.Ratio try to avoid compile-time rational arithmetic overflow?]
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.
-Boost.Ratio implementes some simplifications in order to reduce the possibility of overflow. The general ideas are:
+Boost.Ratio implements some simplifications in order to reduce the possibility of overflow. The general ideas are:
* The `num` and `den` `ratio<>` fields are normalized.
* Use the gcd of some of the possible products that can overflow, and simplify before doing the product.
@@ -1034,10 +1029,10 @@
( gcd(n1,n2) / (d1 / gcd(d1,d2)) ) *
( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) / d2 )
-This expression correspond to the multiply of two ratios that have less risk of overflow as the initial numerators and denomitators appear now in most of the cases divided by a gcd.
+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.
-For ratio_subtract the reasoning is the same
+For ratio_subtract the reasoning is the same.
[*ratio_multiply]
@@ -1069,9 +1064,9 @@
(n1/d1)<(n2/d2)
-without moving to floating point numbers, two techniques are used:
+without moving to floating-point numbers, two techniques are used:
-* First compare the sign of the numerators
+* First compare the sign of the numerators.
If sign(n1) < sign(n2) the result is true.
@@ -1079,7 +1074,7 @@
* When the sign is equal the technique used is to work with integer division and modulo when the signs are equal.
-Let call Qi the integer division of ni and di and Mi the modulo of ni and di.
+Let call Qi the integer division of ni and di, and Mi the modulo of ni and di.
ni = Qi * di + Mi and Mi < di
@@ -1146,36 +1141,36 @@
[[ratio<n1,d1>][ratio<n2,d2>] [Q] [Q] [!=0] [!=0] [ratio_less<ratio<d2,M2>, ratio<d1/M1>>]]
]
-
-
-[endsect]
+[endsect] [/section:implementation Appendix C: Implementation Notes]
[/======================================================]
[section:faq Appendix D: FAQ]
+[/======================================================]
+[endsect] [/section:faq Appendix D: FAQ]
-[endsect]
[/====================================================]
[section:acknowledgements Appendix E: Acknowledgements]
+[/====================================================]
-The library's 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.
+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.
-time2_demo contained this comment:
+`time2_demo` contained this comment:
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.
-Thanks to Adrew Chinnoff for his help polishing the documentation.
+Thanks to Andrew Chinnoff for his help polishing the documentation.
-[endsect]
+[endsect] [/section:acknowledgements Appendix E: Acknowledgements]
-[/
[/====================================================]
[section:tests Appendix F: Tests]
+[/====================================================]
-In order to test you need to do.
+In order to test you need to run
bjam libs/ratio/test
@@ -1222,35 +1217,37 @@
]
[endsect]
+[endsect] [/section:tests Appendix F: Tests]
-[endsect]
[/=====================================]
[section:tickets Appendix G: Tickets]
+[/=====================================]
[table
[[Ticket] [Description] [Resolution] [State]]
- [[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]]
- [[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]]
+ [[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]]
+ [[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]]
- [[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]]
- [[4] [ration_less overflow on cases where it can be avoided] [Change the algorithm as implemented in libc++] [Closed]]
+ [[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]]
+ [[4] [ration_less overflow on cases where it can be avoided.] [Change the algorithm as implemented in libc++.] [Closed]]
[/[#] [XXXX] [XXXX] [Closed]]
]
+[endsect] [/section:tickets Appendix G: Tickets]
-[endsect]
-]
[/=====================================]
-[section:todo Appendix F: Future Plans]
+[section:todo Appendix H: Future Plans]
[/=====================================]
[heading For later releases]
-* Use constexpr on compilers providing it
-* Use template aliases on compiler providing it
+* 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.
-[endsect]
+[endsect] [/section:todo Appendix H: Future Plans]
+
+
+[endsect] [/section Appendices]
-[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk