Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r76044 - in sandbox/math_constants/libs/math/doc: . html
From: john_at_[hidden]
Date: 2011-12-18 11:34:22

Next message: steven_at_[hidden]: "[Boost-commit] svn:boost r76045 - in trunk/tools/build/v2: engine test"
Previous message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76043 - in sandbox/closure/boost/closure/aux_: . macro macro/code_"

Author: johnmaddock
Date: 2011-12-18 11:34:21 EST (Sun, 18 Dec 2011)
New Revision: 76044
URL: http://svn.boost.org/trac/boost/changeset/76044

Log:
Update docs to match code changes.
Text files modified:
   sandbox/math_constants/libs/math/doc/constants.qbk | 8
   sandbox/math_constants/libs/math/doc/html/index.html | 202 +++++++++++++++++++++++++++++++--------
   2 files changed, 165 insertions(+), 45 deletions(-)

Modified: sandbox/math_constants/libs/math/doc/constants.qbk
==============================================================================
--- sandbox/math_constants/libs/math/doc/constants.qbk (original)
+++ sandbox/math_constants/libs/math/doc/constants.qbk 2011-12-18 11:34:21 EST (Sun, 18 Dec 2011)
@@ -409,7 +409,7 @@

namespace boost{ namespace math{ namespace constants{

- BOOST_DEFINE_MATH_CONSTANT(my_constant, 0, 0, 0);
+ BOOST_DEFINE_MATH_CONSTANT(my_constant, 0, "0");

}}}

@@ -426,7 +426,7 @@

Then to `boost/math/constants/constants.hpp` add:

- BOOST_DEFINE_MATH_CONSTANT(half_pi, 0, 0, 0); // actual values are temporary, we'll replace them later
+ BOOST_DEFINE_MATH_CONSTANT(half_pi, 0, "0"); // actual values are temporary, we'll replace them later

[note Previously defined constants like pi and e can be used, but by not simply calling `pi<T>()`;
specifying the precision via the policy is essential to ensure full accuracy.]
@@ -457,7 +457,7 @@
into `boost/math/constants/constants.hpp` or else into your own code, for example:

[pre
- BOOST_DEFINE_MATH_CONSTANT(half_pi, 1.570796326794896619231321691639751442, 09858469968755291048747229615390820314310449931401741267105853399107404326, +00);
+ BOOST_DEFINE_MATH_CONSTANT(half_pi, 1.570796326794896619231321691639751442e+00, "1.57079632679489661923132169163975144209858469968755291048747229615390820314310449931401741267105853399107404326e+00");
]

This macro BOOST_DEFINE_MATH_CONSTANT inserts a code snippet that
@@ -556,7 +556,7 @@

So, for example, a constant like pi is internally defined as

- BOOST_DEFINE_MATH_CONSTANT(pi, 3.141592653589793238462643383279502884, 19716939937510582097494459230781640628620899862803482534211706798214808651, +00);
+ BOOST_DEFINE_MATH_CONSTANT(pi, 3.141592653589793238462643383279502884e+00, "3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651e+00");

In this case the significand is 109 decimal digits, ensuring 100 decimal digits are exact, and exponent is zero.

Modified: sandbox/math_constants/libs/math/doc/html/index.html
==============================================================================
--- sandbox/math_constants/libs/math/doc/html/index.html (original)
+++ sandbox/math_constants/libs/math/doc/html/index.html 2011-12-18 11:34:21 EST (Sun, 18 Dec 2011)
@@ -504,10 +504,15 @@
</tr>
</tbody>
</table></div>
+<h6>
+<a name="math_constants.tutorial.user_def.h0"></a>
+ <a name="math_constants.tutorial.user_def.custom_specializing_a_constant"></a><a class="link" href="index.html#math_constants.tutorial.user_def.custom_specializing_a_constant">Custom
+ Specializing a constant</a>
+ </h6>

- In addition, for user defined types that need special handling, it's possible
+ In addition, for user-defined types that need special handling, it's possible
 to [partially-] specialize the internal structure used by each constant.
- For example suppose we're using the C++ wrapper around MPFR <code class="computeroutput">mpfr_class</code>: this has it's own representation
+ For example, suppose we're using the C++ wrapper around MPFR <code class="computeroutput">mpfr_class</code>: this has its own representation
 of Pi which we may well wish to use in place of the above mechanism. We can
 achieve this by specialising the class template <code class="computeroutput">boost::math::constants::detail::constant_pi</code>:
 
@@ -519,9 +524,9 @@
 template<int N>
 inline T get(const mpl::int_<N>&)
 {
- // The tempate param N is one of the values in the table above,
- // we can either handle all cases in one as is the case here, or
- // overload "get" for the different options.
+ // The template param N is one of the values in the table above,
+ // we can either handle all cases in one as is the case here,
+ // or overload "get" for the different options.
 mpfr_class result;
 mpfr_const_pi(result.get_mpfr_t(), GMP_RNDN);
 return result;
@@ -530,6 +535,11 @@

}}}} // namespaces
</pre>
+<h6>
+<a name="math_constants.tutorial.user_def.h1"></a>
+ <a name="math_constants.tutorial.user_def.diagnosing_what_meta_programmed_code_is_doing"></a><a class="link" href="index.html#math_constants.tutorial.user_def.diagnosing_what_meta_programmed_code_is_doing">Diagnosing
+ what meta-programmed code is doing</a>
+ </h6>

 Finally, since it can be tricky to diagnose what meta-programmed code is
 doing, there is a diagnostic routine that prints information about how this
@@ -1714,12 +1724,12 @@
<tr>
<td>
 
- gamma
+ euler
 
 </td>
<td>
 
- Γ
+ euler
 
 </td>
<td>
@@ -1737,12 +1747,12 @@
<tr>
<td>
 
- one_div_gamma
+ one_div_euler
 
 </td>
<td>
 
- 1/Γ
+ 1/euler
 
 </td>
<td>
@@ -1756,12 +1766,12 @@
<tr>
<td>
 
- gamma_sqr
+ euler_sqr
 
 </td>
<td>
 
- Γ2
+ euler2
 
 </td>
<td>
@@ -1788,29 +1798,6 @@
<tr>
<td>
 
- cf10
- 
- </td>
-<td>
- 
- 1/10 ...
- 
- </td>
-<td>
- 
- 1.03064
- 
- </td>
-<td>
- 
- <a href="http://en.wikipedia.org/wiki/Continued_fraction" target="_top">Continued
- fraction</a>
- 
- </td>
-</tr>
-<tr>
-<td>
- 
 zeta_two
 
 </td>
@@ -2028,7 +2015,7 @@
 
<pre class="programlisting">namespace boost{ namespace math{ namespace constants{

-BOOST_DEFINE_MATH_CONSTANT(my_constant, 0, 0, 0);
+BOOST_DEFINE_MATH_CONSTANT(my_constant, 0, "0");

}}}
</pre>
@@ -2046,7 +2033,7 @@

 Then to <code class="computeroutput">boost/math/constants/constants.hpp</code> add:
 
-<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(half_pi, 0, 0, 0); // actual values are temporary, we'll replace them later
+<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(half_pi, 0, "0"); // actual values are temporary, we'll replace them later
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
@@ -2096,7 +2083,7 @@
 The output from the program is a snippet of C++ code (actually a macro call)
 that can be cut and pasted into <code class="computeroutput">boost/math/constants/constants.hpp</code> or else into your own code, for example:
 
-<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(half_pi, 1.570796326794896619231321691639751442, 09858469968755291048747229615390820314310449931401741267105853399107404326, +00);
+<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(half_pi, 1.570796326794896619231321691639751442e+00, "1.57079632679489661923132169163975144209858469968755291048747229615390820314310449931401741267105853399107404326e+00");
</pre>

 This macro BOOST_DEFINE_MATH_CONSTANT inserts a code snippet that declares
@@ -2106,6 +2093,101 @@
 to 100 decimal digits, and all the meta-programming machinary needed to select
 between them.
 
+
+ The result of an expanded macro for Pi is shown below.
+ 
+
+
+<pre class="programlisting">// Preprocessed pi constant, annotated.
+
+namespace boost
+{
+ namespace math
+ {
+ namespace constants
+ {
+ namespace detail
+ {
+ template <class T> struct constant_pi
+ {
+ private:
+ // Default implementations from string of decimal digits:
+ static inline T get_from_string()
+ {
+ static const T result
+ = detail::convert_from_string<T>("3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651e+00",
+ boost::is_convertible<const char*, T>());
+ return result;
+ }
+ template <int N> static T compute();
+
+ public:
+ // Default implementations from string of decimal digits:
+ static inline T get(const mpl::int_<construct_from_string>&)
+ {
+ constant_initializer<T, & constant_pi<T>::get_from_string >::do_nothing();
+ return get_from_string();
+ }
+ // Float, double and long double versions:
+ static inline T get(const mpl::int_<construct_from_float>)
+ {
+ return 3.141592653589793238462643383279502884e+00F;
+ }
+ static inline T get(const mpl::int_<construct_from_double>&)
+ {
+ return 3.141592653589793238462643383279502884e+00;
+ }
+ static inline T get(const mpl::int_<construct_from_long_double>&)
+ {
+ return 3.141592653589793238462643383279502884e+00L;
+ }
+ // For very high precision that is nonetheless can be calculated at compile time:
+ template <int N> static inline T get(const mpl::int_<N>& n)
+ {
+ constant_initializer2<T, N, & constant_pi<T>::template compute<N> >::do_nothing();
+ return compute<N>();
+ }
+ //For true arbitrary precision, which may well vary at runtime.
+ static inline T get(const mpl::int_<0>&)
+ {
+ return tools::digits<T>() > max_string_digits ? compute<0>() : get(mpl::int_<construct_from_string>());
+ }
+ }; // template <class T> struct constant_pi
+ } // namespace detail
+
+ // The actual forwarding function (including policy to control precision).
+ template <class T, class Policy> inline T pi( )
+ {
+ return detail:: constant_pi<T>::get(typename construction_traits<T, Policy>::type());
+ }
+ // The actual forwarding function (using default policy to control precision).
+ template <class T> inline T pi()
+ {
+ return pi<T, boost::math::policies::policy<> >()
+ }
+ } // namespace constants
+
+ // Namespace specific versions, for the three built-in floats:
+ namespace float_constants
+ {
+ static const float pi = 3.141592653589793238462643383279502884e+00F;
+ }
+ namespace double_constants
+ {
+ static const double pi = 3.141592653589793238462643383279502884e+00;
+ }
+ namespace long_double_constants
+ {
+ static const long double pi = 3.141592653589793238462643383279502884e+00L;
+ }
+ namespace constants{;
+ } // namespace constants
+ } // namespace math
+} // namespace boost
+
+</pre>
+
+ 
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -2136,6 +2218,10 @@
 Requested by users.
 </li>
<li class="listitem">
+ <a href="http://en.wikipedia.org/wiki/Mathematical_constant" target="_top">Used in
+ science and mathematics.</a>
+ </li>
+<li class="listitem">
 No integer values (because so cheap to construct). (You can easily
 define your own if found convenient, for example: <code class="computeroutput">FPT
 one =static_cast<FPT>(42);</code>).
@@ -2272,7 +2358,7 @@

 So, for example, a constant like pi is internally defined as
 
-<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(pi, 3.141592653589793238462643383279502884, 19716939937510582097494459230781640628620899862803482534211706798214808651, +00);
+<pre class="programlisting">BOOST_DEFINE_MATH_CONSTANT(pi, 3.141592653589793238462643383279502884e+00, "3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651e+00");
</pre>

 In this case the significand is 109 decimal digits, ensuring 100 decimal digits
@@ -2393,6 +2479,40 @@
 
<h6>
<a name="math_constants.FAQ.h12"></a>
+ <a name="math_constants.FAQ.what_happened_to_a_previous_collection_of_constants_proposed_for_boost_"></a><a class="link" href="index.html#math_constants.FAQ.what_happened_to_a_previous_collection_of_constants_proposed_for_boost_">What
+ happened to a previous collection of constants proposed for Boost?</a>
+ </h6>
+
+ A review concluded that the way in which the constants were presented did not
+ meet many peoples needs. None of the methods proposed met many users' essential
+ requirement to allow writing simply <code class="computeroutput">pi</code>
+ rather than <code class="computeroutput">pi()</code>.
+ Many science and engineering equations look difficult to read when because
+ function call brackets can be confused with the many other brackets often needed.
+ All the methods then proposed of avoiding the brackets failed to meet all needs,
+ often on grounds of complexity and lack of applicability to various realistic
+ scenarios.
+ 
+
+ So the simple namespace method, proposed on its own, but rejected at the first
+ review, has been added to allow users to have convenient access to float, double
+ and long double values, but combined with template struct and functions to
+ allow simultaneous use with other non-built-in floating-point types.
+ 
+<h6>
+<a name="math_constants.FAQ.h13"></a>
+ <a name="math_constants.FAQ.why_do_the_constants__internally__have_a_struct_rather_than_a_simple_function_"></a><a class="link" href="index.html#math_constants.FAQ.why_do_the_constants__internally__have_a_struct_rather_than_a_simple_function_">Why
+ do the constants (internally) have a struct rather than a simple function?</a>
+ </h6>
+
+ A function mechanism was provided by in previous versions of Boost.Math.
+ 
+
+ The new mechanism is to permit partial specialization. See Custom Specializing
+ a constant above. It should also allow use with other packages like ttmath Bignum C++ library.
+ 
+<h6>
+<a name="math_constants.FAQ.h14"></a>
 <a name="math_constants.FAQ.where_can_i_find_other_high_precision_constants_"></a><a class="link" href="index.html#math_constants.FAQ.where_can_i_find_other_high_precision_constants_">Where
 can I find other high precision constants?</a>
 </h6>
@@ -2429,12 +2549,12 @@
 </li>
</ol></div>
<h5>
-<a name="math_constants.FAQ.h13"></a>
+<a name="math_constants.FAQ.h15"></a>
 <a name="math_constants.FAQ.where_are_physical_constants_"></a><a class="link" href="index.html#math_constants.FAQ.where_are_physical_constants_">Where
 are Physical Constants?</a>
 </h5>

- Not here in this Boost.Math collection because physical constants:
+ Not here in this Boost.Math collection, because physical constants:
 
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
@@ -2457,7 +2577,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: December 16, 2011 at 12:13:48 GMT</td>
+<td align="left">Last revised: December 18, 2011 at 16:33:06 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Next message: steven_at_[hidden]: "[Boost-commit] svn:boost r76045 - in trunk/tools/build/v2: engine test"
Previous message: lorcaminiti_at_[hidden]: "[Boost-commit] svn:boost r76043 - in sandbox/closure/boost/closure/aux_: . macro macro/code_"

Date view	Thread view	Subject view	Author view

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