Boost-Commit mailing page: [Boost-commit] svn:boost r65506 - in sandbox/chrono/libs/ratio/doc: . html

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r65506 - in sandbox/chrono/libs/ratio/doc: . html
From: vicente.botet_at_[hidden]
Date: 2010-09-21 03:56:26

Author: viboes
Date: 2010-09-21 03:56:25 EDT (Tue, 21 Sep 2010)
New Revision: 65506
URL: http://svn.boost.org/trac/boost/changeset/65506

Log:
Ratio Updated doc 0.2.0
Binary files modified:
   sandbox/chrono/libs/ratio/doc/ratio.pdf
Text files modified:
   sandbox/chrono/libs/ratio/doc/html/index.html | 179 +++++++++++++++++++++++++++++++++++----
   sandbox/chrono/libs/ratio/doc/ratio.qbk | 104 ++++++++++++++++++++++
   2 files changed, 260 insertions(+), 23 deletions(-)

Modified: sandbox/chrono/libs/ratio/doc/html/index.html
==============================================================================
--- sandbox/chrono/libs/ratio/doc/html/index.html (original)
+++ sandbox/chrono/libs/ratio/doc/html/index.html 2010-09-21 03:56:25 EDT (Tue, 21 Sep 2010)
@@ -1,10 +1,10 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Boost.Ratio 0.1.0</title>
+<title>Boost.Ratio 0.2.0</title>
<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
-<link rel="start" href="index.html" title="Boost.Ratio 0.1.0">
+<link rel="start" href="index.html" title="Boost.Ratio 0.2.0">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -21,7 +21,7 @@
<div class="titlepage">
<div>
<div><h2 class="title">
-<a name="boost_ratio"></a>Boost.Ratio 0.1.0</h2></div>
+<a name="boost_ratio"></a>Boost.Ratio 0.2.0</h2></div>
<div><div class="authorgroup">
<div class="author"><h3 class="author">
Howard Hinnant
@@ -61,7 +61,10 @@
<dt> External Resources</dt>
</dl></dd>
<dt> Reference </dt>
-<dd><dl><dt> Header <boost/ratio.hpp></dt></dl></dd>
+<dd><dl>
+<dt> Header <boost/ratio.hpp></dt>
+<dt> Header <boost/ratio_io.hpp></dt>
+</dl></dd>
<dt>Appendices</dt>
<dd><dl>
<dt> Appendix A: History</dt>
@@ -164,7 +167,8 @@

 The Boost.Ratio library provides:
 
-<div class="itemizedlist"><ul type="disc"><li>
+<div class="itemizedlist"><ul type="disc">
+<li>
 A class template, <a href="index.html#boost_ratio.reference.ratio_hpp.ratio" title=" Class Template
 ratio<>"><code class="computeroutput">ratio</code></a>, for specifying compile
 time rational constants such as 1/3 of a nanosecond or the number of
@@ -172,7 +176,13 @@
 ratio<>"><code class="computeroutput">ratio</code></a> represents a compile time
 ratio of compile time constants with support for compile time arithmetic
 with overflow and division by zero protection
- </li></ul></div>
+ </li>
+<li>
+ It provides a textual representation of <code class="computeroutput">boost::ratio<N, D></code> in the form of a <code class="computeroutput">std::basic_string</code>.
+ Other types such as <code class="computeroutput">boost::duration</code>
+ can use these strings to aid in their I/O.
+ </li>
+</ul></div>
</div>
</div>
<div class="section" lang="en">
@@ -201,7 +211,7 @@
 Ratio</a>
</h4></div></div></div>
<a name="boost_ratio.users_guide.getting_started.install.getting_boost_ratio_"></a><h5>
-<a name="id4948974"></a>
+<a name="id4949064"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.getting_boost_ratio_">Getting
 Boost.Ratio </a>
 </h5>
@@ -216,7 +226,7 @@
 and follow the instructions there for anonymous SVN access.
 
<a name="boost_ratio.users_guide.getting_started.install.where_to_install_boost_ratio__"></a><h5>
-<a name="id4949037"></a>
+<a name="id4949126"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.where_to_install_boost_ratio__">Where
 to install Boost.Ratio? </a>
 </h5>
@@ -232,7 +242,7 @@
 variable. Any help is welcome.
 
<a name="boost_ratio.users_guide.getting_started.install.building_boost_ratio_"></a><h5>
-<a name="id4949074"></a>
+<a name="id4949164"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.building_boost_ratio_">Building
 Boost.Ratio </a>
 </h5>
@@ -241,7 +251,7 @@
 so no need to compile anything.
 
<a name="boost_ratio.users_guide.getting_started.install.requirements"></a><h5>
-<a name="id4949105"></a>
+<a name="id4949194"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.requirements">Requirements</a>
 </h5>

@@ -282,7 +292,7 @@
</dl>
</div>
<a name="boost_ratio.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_ratio__emphasis__"></a><h5>
-<a name="id4949283"></a>
+<a name="id4949373"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.building_an_executable_that_uses__emphasis_role__bold__boost_ratio__emphasis__">Building
 an executable that uses Boost.Ratio </a>
 </h5>
@@ -290,7 +300,7 @@
 No link is needed.
 
<a name="boost_ratio.users_guide.getting_started.install.exceptions_safety_"></a><h5>
-<a name="id4949316"></a>
+<a name="id4949406"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.exceptions_safety_">Exceptions
 safety </a>
 </h5>
@@ -299,7 +309,7 @@
 of exception safety as long as the underlying parameters provide it.
 
<a name="boost_ratio.users_guide.getting_started.install.thread_safety_"></a><h5>
-<a name="id4949344"></a>
+<a name="id4949434"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.thread_safety_">Thread
 safety </a>
 </h5>
@@ -307,7 +317,7 @@
 All functions in the library are thread-unsafe except when noted explicitly.
 
<a name="boost_ratio.users_guide.getting_started.install.tested_compilers_"></a><h5>
-<a name="id4949370"></a>
+<a name="id4949459"></a>
 <a href="index.html#boost_ratio.users_guide.getting_started.install.tested_compilers_">Tested
 compilers </a>
 </h5>
@@ -762,6 +772,10 @@
<dd>
 From Vicente Juan Botet Escriba.
 </dd>
+<dt>N3131: Compile-time rational arithmetic and overflow</dt>
+<dd>
+ From Anthony Williams.
+ </dd>
</dl>
</div>
</div>
@@ -786,6 +800,7 @@
<dt><a href="index.html#boost_ratio.reference.ratio_hpp.limitations"> Limitations
 and Extensions</a></dt>
</dl></dd>
+<dt> Header <boost/ratio_io.hpp></dt>
</dl></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
@@ -1204,6 +1219,122 @@
 </li></ul></div>
</div>
</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_ratio.reference.ratio_io_hpp"></a> Header <boost/ratio_io.hpp>
+</h3></div></div></div>
+
+ It provides a textual representation of <code class="computeroutput">boost::ratio<N,
+ D></code>
+ in the form of a <code class="computeroutput">std::basic_string</code>. Other types such as <code class="computeroutput">boost::duration</code> can use these strings to aid in
+ their I/O.
+ 
+
+ This source is has been adapted from the experimental header <code class="computeroutput"><ratio_io></code> from Howard Hinnant. The current implementation
+ makes use of a few utilities in libc++. Porting to Boost has been trivial.
+ 
+<pre class="programlisting">namespace boost {
+
+ template <class Ratio, class CharT>
+ struct ratio_string
+ {
+ static std::basic_string<CharT> short_name() {return long_name();}
+ static std::basic_string<CharT> long_name();
+ };
+
+}
+</pre>
+
+ For each <code class="computeroutput">ratio<N, D></code> there exists a <code class="computeroutput">ratio_string<ratio<N,
+ D>,
+ CharT></code>
+ for which you can query two strings: <code class="computeroutput">short_name</code>
+ and <code class="computeroutput">long_name</code>. For those
+ <code class="computeroutput">ratio</code>'s that correspond to
+ an <a href="http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes" target="_top">SI
+ prefix</a> long_name corresponds to the internationally recognized prefix,
+ stored as a <code class="computeroutput">basic_string<CharT></code>. For example <code class="computeroutput">ratio_string<mega, char>::long_name()</code>
+ returns <code class="computeroutput">string("mega")</code>.
+ For those <code class="computeroutput">ratio</code>'s that correspond
+ to an <a href="http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes" target="_top">SI
+ prefix</a> <code class="computeroutput">short_name</code>
+ corresponds to the internationally recognized symbol, stored as a <code class="computeroutput">basic_string<CharT></code>.
+ For example <code class="computeroutput">ratio_string<mega, char>::short_name()</code>
+ returns <code class="computeroutput">string("M")</code>.
+ For all other <code class="computeroutput">ratio</code>'s, both
+ <code class="computeroutput">long_name()</code>
+ and <code class="computeroutput">short_name()</code>
+ return a <code class="computeroutput">basic_string</code> containing
+ "[<code class="computeroutput">ratio::num/ratio::den</code>]".
+ 
+
+ <code class="computeroutput">ratio_string<ratio<N, D>, CharT></code> is only defined for four character types:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <code class="computeroutput">char</code>
+ </li>
+<li>
+ <code class="computeroutput">char16_t</code>
+ </li>
+<li>
+ <code class="computeroutput">char32_t</code>
+ </li>
+<li>
+ <code class="computeroutput">wchar_t</code>
+ </li>
+</ul></div>
+
+ When the character is char, UTF-8 will be used to encode the names. When
+ the character is <code class="computeroutput">char16_t</code>,
+ UTF-16 will be used to encode the names. When the character is <code class="computeroutput">char32_t</code>, UTF-32 will be used to encode
+ the names. When the character is <code class="computeroutput">wchar_t</code>,
+ the encoding will be UTF-16 if <code class="computeroutput">wchar_t</code>
+ is 16 bits, and otherwise UTF-32.
+ 
+
+ The <code class="computeroutput">short_name</code> for micro
+ is defined by Unicode
+ to be U+00B5.
+ 
+
+ Examples:
+ 
+<pre class="programlisting">#include <boost/ratio/ratio_io.hpp>
+#include <iostream>
+
+int main()
+{
+ using namespace std;
+ using namespace boost;
+
+ cout << "ratio_string<deca, char>::long_name() = "
+ << ratio_string<deca, char>::long_name() << '\n';
+ cout << "ratio_string<deca, char>::short_name() = "
+ << ratio_string<deca, char>::short_name() << '\n';
+
+ cout << "ratio_string<giga, char>::long_name() = "
+ << ratio_string<giga, char>::long_name() << '\n';
+ cout << "ratio_string<giga, char>::short_name() = "
+ << ratio_string<giga, char>::short_name() << '\n';
+
+ cout << "ratio_string<ratio<4, 6>, char>::long_name() = "
+ << ratio_string<ratio<4, 6>, char>::long_name() << '\n';
+ cout << "ratio_string<ratio<4, 6>, char>::short_name() = "
+ << ratio_string<ratio<4, 6>, char>::short_name() << '\n';
+}
+</pre>
+
+ The output will be
+ 
+<pre class="programlisting">ratio_string<deca, char>::long_name() = deca
+ratio_string<deca, char>::short_name() = da
+ratio_string<giga, char>::long_name() = giga
+ratio_string<giga, char>::short_name() = G
+ratio_string<ratio<4, 6>, char>::long_name() = [2/3]
+ratio_string<ratio<4, 6>, char>::short_name() = [2/3]
+</pre>
+</div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -1212,7 +1343,7 @@
<div class="toc"><dl>
<dt> Appendix A: History</dt>
<dd><dl>
-<dt>Version 0.1.1, September 20, 2010 </dt>
+<dt>Version 0.2.0, September 20, 2010 </dt>
<dt>Version 0.1.0, September 10, 2010 </dt>
</dl></dd>
<dt> Appendix B: Rationale</dt>
@@ -1235,14 +1366,20 @@
<a name="boost_ratio.appendices.history"></a> Appendix A: History
</h3></div></div></div>
<div class="toc"><dl>
-<dt>Version 0.1.1, September 20, 2010 </dt>
+<dt>Version 0.2.0, September 20, 2010 </dt>
<dt>Version 0.1.0, September 10, 2010 </dt>
</dl></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
-<a name="boost_ratio.appendices.history.__version_0_1_1__september_20__2010__"></a>Version 0.1.1, September 20, 2010
+<a name="boost_ratio.appendices.history.__version_0_2_0__september_20__2010__"></a>Version 0.2.0, September 20, 2010
</h4></div></div></div>

+ Featurs:
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Added ratio_string traits.
+ </li></ul></div>
+
 Fixes:
 
<div class="itemizedlist"><ul type="disc"><li>
@@ -1273,7 +1410,7 @@
<a name="boost_ratio.appendices.rationale"></a> Appendix B: Rationale
</h3></div></div></div>
<a name="boost_ratio.appendices.rationale.why_ratio_needs_copyconstruction_and_assignment_from_ratios_having_the_same_normalized_form"></a><h4>
-<a name="id5009215"></a>
+<a name="id5011421"></a>
 <a href="index.html#boost_ratio.appendices.rationale.why_ratio_needs_copyconstruction_and_assignment_from_ratios_having_the_same_normalized_form">Why
 ratio needs CopyConstruction and Assignment from ratios having the same normalized
 form</a>
@@ -1308,7 +1445,7 @@
 succeeds.
 
<a name="boost_ratio.appendices.rationale.why_ratio_needs_the_nested_normalizer_typedef_type"></a><h4>
-<a name="id5009620"></a>
+<a name="id5011826"></a>
 <a href="index.html#boost_ratio.appendices.rationale.why_ratio_needs_the_nested_normalizer_typedef_type">Why
 ratio needs the nested normalizer typedef type</a>
 </h4>
@@ -2171,7 +2308,7 @@
<a name="boost_ratio.appendices.todo"></a> Appendix H: Future plans
</h3></div></div></div>
<a name="boost_ratio.appendices.todo.for_later_releases"></a><h4>
-<a name="id5011285"></a>
+<a name="id5013492"></a>
 <a href="index.html#boost_ratio.appendices.todo.for_later_releases">For later
 releases</a>
 </h4>
@@ -2183,7 +2320,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: September 20, 2010 at 11:23:48 GMT</td>
+<td align="left">Last revised: September 21, 2010 at 07:53:11 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/chrono/libs/ratio/doc/ratio.pdf
==============================================================================
Binary files. No diff available.

Modified: sandbox/chrono/libs/ratio/doc/ratio.qbk
==============================================================================
--- sandbox/chrono/libs/ratio/doc/ratio.qbk (original)
+++ sandbox/chrono/libs/ratio/doc/ratio.qbk 2010-09-21 03:56:25 EDT (Tue, 21 Sep 2010)
@@ -9,7 +9,7 @@

[article Boost.Ratio
 [quickbook 1.5]
- [version 0.1.0]
+ [version 0.2.0]
 [authors [Hinnant, Howard]]
 [authors [Dawes, Beman]]
 [authors [Botet Escriba, Vicente J.]]
@@ -221,6 +221,8 @@

* 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`. Other types such as `boost::duration` can use these strings to aid in their I/O.
+
[endsect]

[endsect]
@@ -652,6 +654,13 @@
 [[@http://home.roadrunner.com/~hinnant/issue_review/lwg-active.html#1281 [*LWG 1281. CopyConstruction and Assignment between ratios having the same normalized form]]]
 [From Vicente Juan Botet Escriba.]
]
+
+[
+ [[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3131.html [*N3131: Compile-time rational arithmetic and overflow]]]
+ [From Anthony Williams.]
+]
+
+
]

[endsect]
@@ -895,8 +904,75 @@

[endsect]

+[/===========================================]
+[section:ratio_io_hpp Header `<boost/ratio_io.hpp>`]
+[/===========================================]
+
+It provides a textual representation of `boost::ratio<N, D>` in the form of a `std::basic_string`. Other types such as `boost::duration` can use these strings to aid in their I/O.
+
+This source is has been adapted from the experimental header `<ratio_io>` from Howard Hinnant. The current implementation makes use of a few utilities in libc++. Porting to Boost has been trivial.
+
+ namespace boost {
+
+ template <class Ratio, class CharT>
+ struct ratio_string
+ {
+ static std::basic_string<CharT> short_name() {return long_name();}
+ static std::basic_string<CharT> long_name();
+ };
+
+ }
+
+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:
+
+* `char`
+* `char16_t`
+* `char32_t`
+* `wchar_t`
+
+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.
+
+[*Examples:]
+
+ #include <boost/ratio/ratio_io.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ using namespace std;
+ using namespace boost;
+
+ cout << "ratio_string<deca, char>::long_name() = "
+ << ratio_string<deca, char>::long_name() << '\n';
+ cout << "ratio_string<deca, char>::short_name() = "
+ << ratio_string<deca, char>::short_name() << '\n';
+
+ cout << "ratio_string<giga, char>::long_name() = "
+ << ratio_string<giga, char>::long_name() << '\n';
+ cout << "ratio_string<giga, char>::short_name() = "
+ << ratio_string<giga, char>::short_name() << '\n';
+
+ cout << "ratio_string<ratio<4, 6>, char>::long_name() = "
+ << ratio_string<ratio<4, 6>, char>::long_name() << '\n';
+ cout << "ratio_string<ratio<4, 6>, char>::short_name() = "
+ << ratio_string<ratio<4, 6>, char>::short_name() << '\n';
+ }
+
+The output will be
+
+ ratio_string<deca, char>::long_name() = deca
+ ratio_string<deca, char>::short_name() = da
+ ratio_string<giga, char>::long_name() = giga
+ ratio_string<giga, char>::short_name() = G
+ ratio_string<ratio<4, 6>, char>::long_name() = [2/3]
+ ratio_string<ratio<4, 6>, char>::short_name() = [2/3]

[endsect]
+[endsect]

[/=================]
@@ -906,7 +982,11 @@
[section:history Appendix A: History]
[/==================================]

-[section [*Version 0.1.1, September 20, 2010] ]
+[section [*Version 0.2.0, September 20, 2010] ]
+
+[*Featurs:]
+
+* Added ratio_string traits.

[*Fixes:]

@@ -969,7 +1049,27 @@
[/======================================================]
[section:implementation Appendix C: Implementation Notes]

+[/
+How compile-time rational arithmetic has been done in Boost.Ratio 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.
+
+The Boost.Ratio implementation try to handle with such overflow if the final result can be representable. In order to do that a simplify operation on the product of intmax_t is used.

+simplify< times<A,B>, times<C,D> >::value
+ if gcd(A,C) > 1 symplify< times<A/gcd(A,C),B>, times<C/gcd(A,C),D> >
+ if gcd(A,D) > 1 symplify< times<A/gcd(A,D),B>, times<C,D/gcd(A,D)> >
+ if gcd(B,C) > 1 symplify< times<A,B/gcd(B,C)>, times<C/gcd(B,C),D> >
+ if gcd(B,D) > 1 symplify< times<A,B/gcd(B,D)>, times<C,D/gcd(B,D)> >
+ ratio<A*B, C*D>
+
+factorize<0> = 0
+factorize<1> = 2
+
+factorize<N> = factorize_n<N, 2>
+
+factorize_n<N, A, R=N%2> = factorize_n<N, A+1>
+factorize_n<N, N, 1> N
+factorize_n<N, A, 0> = times<A, factorize_n<N/A>, A>
+]
[endsect]

[/======================================================]

Date view	Thread view	Subject view	Author view