Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r84608 - in trunk/libs/math/doc: . background html html/indexes html/math_toolkit
From: john_at_[hidden]
Date: 2013-06-02 14:14:58

Next message: andrey.semashev_at_[hidden]: "[Boost-commit] svn:boost r84609 - trunk/boost/utility"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r84607 - in trunk: boost/thread libs/thread/test/sync/futures/async"

Author: johnmaddock
Date: 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
New Revision: 84608
URL: http://svn.boost.org/trac/boost/changeset/84608

Log:
Add a quick and dirty tutorial on writing a new special function.
Regenerate docs.
Added:
   trunk/libs/math/doc/background/special_tut.qbk (contents, props changed)
   trunk/libs/math/doc/html/math_toolkit/special_tut.html (contents, props changed)
Text files modified:
   trunk/libs/math/doc/html/backgrounders.html | 2 ++
   trunk/libs/math/doc/html/index.html | 2 +-
   trunk/libs/math/doc/html/indexes/s01.html | 9 +++++++--
   trunk/libs/math/doc/html/indexes/s02.html | 5 +++--
   trunk/libs/math/doc/html/indexes/s03.html | 9 +++++++--
   trunk/libs/math/doc/html/indexes/s04.html | 10 +++++++---
   trunk/libs/math/doc/html/indexes/s05.html | 35 ++++++++++++++++++++++++++++++++---
   trunk/libs/math/doc/html/math_toolkit/conventions.html | 2 +-
   trunk/libs/math/doc/html/math_toolkit/navigation.html | 2 +-
   trunk/libs/math/doc/html/math_toolkit/relative_error.html | 6 +++---
   trunk/libs/math/doc/html/math_toolkit/sf_implementation.html | 6 +++---
   trunk/libs/math/doc/math.qbk | 1 +
   12 files changed, 68 insertions(+), 21 deletions(-)

Added: trunk/libs/math/doc/background/special_tut.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/background/special_tut.qbk 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -0,0 +1,167 @@
+[section:special_tut Tutorial: How to Write a New Special Function]
+
+In this section we'll provide a "recipe" for adding a new special function to this library to make life easier for
+future authors wishing to contribute. We'll assume the function returns a single floating point result, and takes
+two floating point arguments. For the sake of exposistion we'll give the function the name "my_special".
+
+Normally the implementation of such a function is split into two layers - a public user layer, and an internal
+implementation layer that does the actual work. The implementation layer is declared inside a "detail" namespace
+and has a simple signature:
+
+ namespace boost{ namespace math{ namespace detail{
+
+ template <class T, class Policy>
+ T my_special_imp(const T& a, const T&b, const Policy& pol)
+ {
+ /* Implementation goes here */
+ }
+
+ }}} // namespaces
+
+We'll come back to what can go inside the implementation later, but first lets look at the user layer.
+This consists of two overloads of the function, with and without a __Policy argument:
+
+ namespace boost{ namespace math{
+
+ template <class T, class U>
+ typename tools::promote_args<T, U>::type my_special(const T& a, const U& b);
+
+ template <class T, class U, class Policy>
+ typename tools::promote_args<T, U>::type my_special(const T& a, const U& b, const Policy& pol);
+
+ }} // namespaces
+
+Note how each argument has a different template type - this allows for mixed type arguments - the return
+type is computed from a traits class and is the "common type" of all the arguments after any integer
+arguments have been promoted to type `double`.
+
+The implementation of the non-policy overload is trivial:
+
+ namespace boost{ namespace math{
+
+ template <class T, class U>
+ inline typename tools::promote_args<T, U>::type my_special(const T& a, const U& b)
+ {
+ // Simply forward with a default policy:
+ return my_special(a, b, policies::policy<>();
+ }
+
+ }} // namespaces
+
+The implementation of the other overload is somewhat more complex, as there's some meta-programming to do,
+but from a runtime perspective is still a one-line forwarding function. Here it is with comments explaining
+what each line does:
+
+ namespace boost{ namespace math{
+
+ template <class T, class U, class Policy>
+ inline typename tools::promote_args<T, U>::type my_special(const T& a, const U& b, const Policy& pol)
+ {
+ //
+ // We've found some standard library functions to misbehave if any FPU exception flags
+ // are set prior to their call, this code will clear those flags, then reset them
+ // on exit:
+ //
+ BOOST_FPU_EXCEPTION_GUARD
+ //
+ // The type of the result - the common type of T and U after
+ // any integer types have been promoted to double:
+ //
+ typedef typename tools::promote_args<T, U>::type result_type;
+ //
+ // The type used for the calculation. This may be a wider type than
+ // the result in order to ensure full precision:
+ //
+ typedef typename policies::evaluation<result_type, Policy>::type value_type;
+ //
+ // The type of the policy to forward to the actual implementation.
+ // We disable promotion of float and double as that's [possibly]
+ // happened already in the line above. Also reset to the default
+ // any policies we don't use (reduces code bloat if we're called
+ // multiple times with differing policies we don't actually use).
+ // Also normalise the type, again to reduce code bloat in case we're
+ // called multiple times with functionally identical policies that happen
+ // to be different types.
+ //
+ typedef typename policies::normalise<
+ Policy,
+ policies::promote_float<false>,
+ policies::promote_double<false>,
+ policies::discrete_quantile<>,
+ policies::assert_undefined<> >::type forwarding_policy;
+ //
+ // Whew. Now we can make the actual call to the implementation.
+ // Arguments are explicitly cast to the evaluation type, and the result
+ // passed through checked_narrowing_cast which handles things like overflow
+ // according to the policy passed:
+ //
+ return policies::checked_narrowing_cast<result_type, forwarding_policy>(
+ detail::my_special_imp(
+ static_cast<value_type>(a),
+ static_cast<value_type>(x),
+ forwarding_policy()),
+ "boost::math::my_special<%1%>(%1%, %1%)");
+ }
+
+ }} // namespaces
+
+We're now almost there, we just need to flesh out the details of the implementation layer:
+
+ namespace boost{ namespace math{ namespace detail{
+
+ template <class T, class Policy>
+ T my_special_imp(const T& a, const T&b, const Policy& pol)
+ {
+ /* Implementation goes here */
+ }
+
+ }}} // namespaces
+
+The following guidelines indicate what (other than basic arithmetic) can go in the implementation:
+
+* Error conditions (for example bad arguments) should be handled by calling one of the
+[link math_toolkit.error_handling.finding_more_information policy based error handlers].
+* Calls to standard library functions should be made unqualified (this allows argument
+dependent lookup to find standard library functions for user-defined floating point
+types such as those from Boost.Multiprecision). In addition the macro `BOOST_MATH_STD_USING`
+should appear at the start of the function (note no semi-colon afterwards!) so that
+all the math functions in `namespace std` are visible in the current scope.
+* Calls to other special functions should be made as fully qualified calls, and include the
+policy parameter as the last argument, for example `boost::math::tgamma(a, pol)`.
+* Where possible, evaluation of series, continued fractions, polynomials, or root
+finding should use one of the [link toolkit boiler plate functions]. In any case, after
+any iterative method, you should verify that the number of iterations did not exceed the
+maximum specified in the __Policy type, and if it did terminate as a result of exceeding the
+maximum, then the appropriate error handler should be called (see existing code for examples).
+* Numeric constants such as [pi] etc should be obtained via a call to the [link toolkit.constants appropriate function],
+for example: `constants::pi<T>()`.
+* Where tables of coefficients are used (for example for rational approximations), care should be taken
+to ensure these are initialized at program startup to ensure thread safety when using user-defined number types.
+See for example the use of `erf_initializer` in boost/math/special_functions/erf.hpp.
+
+Here are some other useful internal functions:
+
+[table
+[[function][Meaning]]
+[[`policies::digits<T, Policy>()`][Returns number of binary digits in T (possible overridden by the policy).]]
+[[`policies::get_max_series_iterations<Policy>()`][Maximum number of iterations for series evaluation.]]
+[[`policies::get_max_root_iterations<Policy>()`][Maximum number of iterations for root finding.]]
+[[`polices::get_epsilon<T, Policy>()`][Epsilon for type T, possibly overridden by the Policy.]]
+[[`tools::digits<T>()`][Returns the number of binary digits in T.]]
+[[`tools::max_value<T>()`][Equivalent to `std::numeric_limits<T>::max()`]]
+[[`tools::min_value<T>()`][Equivalent to `std::numeric_limits<T>::min()`]]
+[[`tools::log_max_value<T>()`][Equivalent to the natural logarithm of `std::numeric_limits<T>::max()`]]
+[[`tools::log_min_value<T>()`][Equivalent to the natural logarithm of `std::numeric_limits<T>::min()`]]
+[[`tools::epsilon<T>()`][Equivalent to `std::numeric_limits<T>::epsilon()`.]]
+[[`tools::root_epsilon<T>()`][Equivalent to the square root of `std::numeric_limits<T>::epsilon()`.]]
+[[`tools::forth_root_epsilon<T>()`][Equivalent to the forth root of `std::numeric_limits<T>::epsilon()`.]]
+]
+
+[endsect]
+
+[/
+ Copyright 2013 John Maddock.
+ 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).
+]

Modified: trunk/libs/math/doc/html/backgrounders.html
==============================================================================
--- trunk/libs/math/doc/html/backgrounders.html (original)
+++ trunk/libs/math/doc/html/backgrounders.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -30,6 +30,8 @@
<dl class="toc">
<dt><a href="math_toolkit/sf_implementation.html">Additional Implementation
Notes</a></dt>
+<dt><a href="math_toolkit/special_tut.html">Tutorial: How to Write a New
+ Special Function</a></dt>
<dt>Relative Error</dt>
<dt>The Lanczos Approximation</dt>
<dt>The Remez Method</dt>

Modified: trunk/libs/math/doc/html/index.html
==============================================================================
--- trunk/libs/math/doc/html/index.html (original)
+++ trunk/libs/math/doc/html/index.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -100,7 +100,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: May 25, 2013 at 11:21:01 GMT</td>
+<td align="left">Last revised: June 02, 2013 at 18:02:30 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: trunk/libs/math/doc/html/indexes/s01.html
==============================================================================
--- trunk/libs/math/doc/html/indexes/s01.html (original)
+++ trunk/libs/math/doc/html/indexes/s01.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -22,9 +22,9 @@
<div class="spirit-nav">
<a accesskey="p" href="../indexes.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s02.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
-<div class="section id1444738">
+<div class="section id1431117">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id1444738"></a>Function Index</h2></div></div></div>
+<a name="id1431117"></a>Function Index</h2></div></div></div>
<a class="link" href="s01.html#idx_id_0">A</a> <a class="link" href="s01.html#idx_id_1">B</a> <a class="link" href="s01.html#idx_id_2">C</a> <a class="link" href="s01.html#idx_id_3">D</a> <a class="link" href="s01.html#idx_id_4">E</a> <a class="link" href="s01.html#idx_id_5">F</a> <a class="link" href="s01.html#idx_id_6">G</a> <a class="link" href="s01.html#idx_id_7">H</a> <a class="link" href="s01.html#idx_id_8">I</a> <a class="link" href="s01.html#idx_id_9">J</a> <a class="link" href="s01.html#idx_id_10">K</a> <a class="link" href="s01.html#idx_id_11">L</a> <a class="link" href="s01.html#idx_id_12">M</a> <a class="link" href="s01.html#idx_id_13">N</a> <a class="link" href="s01.html#idx_id_14">O</a> <a class="link" href="s01.html#idx_id_15">P</a> <a class="link" href="s01.html#idx_id_16">Q</a> <a class="link" href="s01.html#idx_id_17">R</a> <a class="link" href="s01.html#idx_id_18">S</a> <a class="link" href="s01.html#idx_id_19">T</a> <a class="link" href="s01.html#idx_id_20">U</a> <a class="link" href=
"s01.html#idx_id_21">V</a> <a class="link" href="s01.html#idx_id_22">W</a> <a class="link" href="s01.html#idx_id_23">Z</a>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -235,6 +235,10 @@
<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/triangular_dist.html" title="Triangular Distribution">Triangular Distribution</a></li></ul></div>
</li>
<li class="listitem" style="list-style-type: none">
+called
+<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li></ul></div>
+</li>
+<li class="listitem" style="list-style-type: none">
cbrt
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/overview_tr1.html" title="C99 and C++ TR1 C-style Functions">C99 and C++ TR1 C-style Functions</a></li>
@@ -2249,6 +2253,7 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/issues.html" title="Known Issues, and TODO List">Known Issues, and TODO List</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/internals1/rational.html" title="Polynomial and Rational Function Evaluation">Polynomial and Rational Function Evaluation</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/skew_normal_dist.html" title="Skew Normal Distribution">Skew Normal Distribution</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">

Modified: trunk/libs/math/doc/html/indexes/s02.html
==============================================================================
--- trunk/libs/math/doc/html/indexes/s02.html (original)
+++ trunk/libs/math/doc/html/indexes/s02.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -22,9 +22,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s01.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s03.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
-<div class="section id1462569">
+<div class="section id1448989">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id1462569"></a>Class Index</h2></div></div></div>
+<a name="id1448989"></a>Class Index</h2></div></div></div>
<a class="link" href="s02.html#idx_id_25">B</a> <a class="link" href="s02.html#idx_id_26">C</a> <a class="link" href="s02.html#idx_id_27">D</a> <a class="link" href="s02.html#idx_id_28">E</a> <a class="link" href="s02.html#idx_id_29">F</a> <a class="link" href="s02.html#idx_id_30">G</a> <a class="link" href="s02.html#idx_id_31">H</a> <a class="link" href="s02.html#idx_id_32">I</a> <a class="link" href="s02.html#idx_id_35">L</a> <a class="link" href="s02.html#idx_id_36">M</a> <a class="link" href="s02.html#idx_id_37">N</a> <a class="link" href="s02.html#idx_id_38">O</a> <a class="link" href="s02.html#idx_id_39">P</a> <a class="link" href="s02.html#idx_id_40">Q</a> <a class="link" href="s02.html#idx_id_41">R</a> <a class="link" href="s02.html#idx_id_42">S</a> <a class="link" href="s02.html#idx_id_43">T</a> <a class="link" href="s02.html#idx_id_44">U</a> <a class="link" href="s02.html#idx_id_46">W</a>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -201,6 +201,7 @@
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">Calling User Defined Error Handlers</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/pol_tutorial/namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">Setting Policies at Namespace or Translation Unit Scope</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
</ul></div></dd>

Modified: trunk/libs/math/doc/html/indexes/s03.html
==============================================================================
--- trunk/libs/math/doc/html/indexes/s03.html (original)
+++ trunk/libs/math/doc/html/indexes/s03.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -22,9 +22,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s02.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s04.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
-<div class="section id1463649">
+<div class="section id1450077">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id1463649"></a>Typedef Index</h2></div></div></div>
+<a name="id1450077"></a>Typedef Index</h2></div></div></div>
<a class="link" href="s03.html#idx_id_48">A</a> <a class="link" href="s03.html#idx_id_49">B</a> <a class="link" href="s03.html#idx_id_50">C</a> <a class="link" href="s03.html#idx_id_51">D</a> <a class="link" href="s03.html#idx_id_52">E</a> <a class="link" href="s03.html#idx_id_53">F</a> <a class="link" href="s03.html#idx_id_54">G</a> <a class="link" href="s03.html#idx_id_55">H</a> <a class="link" href="s03.html#idx_id_56">I</a> <a class="link" href="s03.html#idx_id_59">L</a> <a class="link" href="s03.html#idx_id_61">N</a> <a class="link" href="s03.html#idx_id_62">O</a> <a class="link" href="s03.html#idx_id_63">P</a> <a class="link" href="s03.html#idx_id_65">R</a> <a class="link" href="s03.html#idx_id_66">S</a> <a class="link" href="s03.html#idx_id_67">T</a> <a class="link" href="s03.html#idx_id_68">U</a> <a class="link" href="s03.html#idx_id_69">V</a> <a class="link" href="s03.html#idx_id_70">W</a>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -131,6 +131,10 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/c99.html" title="C99 C Functions">C99 C Functions</a></li>
</ul></div>
</li>
+<li class="listitem" style="list-style-type: none">
+forwarding_policy
+<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li></ul></div>
+</li>
</ul></div></dd>
<dt>
<a name="idx_id_54"></a>G
@@ -390,6 +394,7 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/octonion.html" title="Template Class octonion">Template Class octonion</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/quat.html" title="Template Class quaternion">Template Class quaternion</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/triangular_dist.html" title="Triangular Distribution">Triangular Distribution</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/uniform_dist.html" title="Uniform Distribution">Uniform Distribution</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/weibull_dist.html" title="Weibull Distribution">Weibull Distribution</a></li>
</ul></div>

Modified: trunk/libs/math/doc/html/indexes/s04.html
==============================================================================
--- trunk/libs/math/doc/html/indexes/s04.html (original)
+++ trunk/libs/math/doc/html/indexes/s04.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -22,9 +22,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s03.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="s05.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
-<div class="section id1466627">
+<div class="section id1454465">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id1466627"></a>Macro Index</h2></div></div></div>
+<a name="id1454465"></a>Macro Index</h2></div></div></div>
<a class="link" href="s04.html#idx_id_73">B</a> <a class="link" href="s04.html#idx_id_77">F</a>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -45,7 +45,10 @@
</li>
<li class="listitem" style="list-style-type: none">
BOOST_FPU_EXCEPTION_GUARD
-<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li></ul></div>
+<div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
+</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
BOOST_HAS_LOG1P
@@ -247,6 +250,7 @@
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/new_const.html" title="Defining New Constants">Defining New Constants</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">

Modified: trunk/libs/math/doc/html/indexes/s05.html
==============================================================================
--- trunk/libs/math/doc/html/indexes/s05.html (original)
+++ trunk/libs/math/doc/html/indexes/s05.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -21,9 +21,9 @@
<div class="spirit-nav">
<a accesskey="p" href="s04.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../indexes.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
</div>
-<div class="section id1470265">
+<div class="section id1456738">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id1470265"></a>Index</h2></div></div></div>
+<a name="id1456738"></a>Index</h2></div></div></div>
<a class="link" href="s05.html#idx_id_96">A</a> <a class="link" href="s05.html#idx_id_97">B</a> <a class="link" href="s05.html#idx_id_98">C</a> <a class="link" href="s05.html#idx_id_99">D</a> <a class="link" href="s05.html#idx_id_100">E</a> <a class="link" href="s05.html#idx_id_101">F</a> <a class="link" href="s05.html#idx_id_102">G</a> <a class="link" href="s05.html#idx_id_103">H</a> <a class="link" href="s05.html#idx_id_104">I</a> <a class="link" href="s05.html#idx_id_105">J</a> <a class="link" href="s05.html#idx_id_106">K</a> <a class="link" href="s05.html#idx_id_107">L</a> <a class="link" href="s05.html#idx_id_108">M</a> <a class="link" href="s05.html#idx_id_109">N</a> <a class="link" href="s05.html#idx_id_110">O</a> <a class="link" href="s05.html#idx_id_111">P</a> <a class="link" href="s05.html#idx_id_112">Q</a> <a class="link" href="s05.html#idx_id_113">R</a> <a class="link" href="s05.html#idx_id_114">S</a> <a class="link" href="s05.html#idx_id_115">T</a> <a class="link" href="s05.html#idx_id_116">
U</a> <a class="link" href="s05.html#idx_id_117">V</a> <a class="link" href="s05.html#idx_id_118">W</a> <a class="link" href="s05.html#idx_id_119">Z</a>
<div class="variablelist"><dl class="variablelist">
<dt>
@@ -378,7 +378,10 @@
</li>
<li class="listitem" style="list-style-type: none">
BOOST_FPU_EXCEPTION_GUARD
-<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li></ul></div>
+<div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
+</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
BOOST_HAS_LOG1P
@@ -580,6 +583,7 @@
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/config_macros.html#math_toolkit.config_macros.boost_math_macros" title="Table 1.11. Boost.Math Macros">Boost.Math Macros</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/new_const.html" title="Defining New Constants">Defining New Constants</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
@@ -1034,6 +1038,10 @@
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
+called
+<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li></ul></div>
+</li>
+<li class="listitem" style="list-style-type: none">
Calling User Defined Error Handlers
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</a></li>
@@ -1348,6 +1356,7 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/lanczos.html" title="The Lanczos Approximation">The Lanczos Approximation</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/constants.html" title="The Mathematical Constants">The Mathematical Constants</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/remez.html" title="The Remez Method">The Remez Method</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/uniform_dist.html" title="Uniform Distribution">Uniform Distribution</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/tutorial/non_templ.html" title="Use in non-template code">Use in non-template code</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/tutorial/templ.html" title="Use in template code">Use in template code</a></li>
@@ -2392,6 +2401,10 @@
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
+forwarding_policy
+<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li></ul></div>
+</li>
+<li class="listitem" style="list-style-type: none">
fpclassify
<div class="index"><ul class="index" style="list-style-type: none; "><li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/fpclass.html" title="Floating-Point Classification: Infinities and NaNs">Floating-Point Classification: Infinities and NaNs</a></li></ul></div>
</li>
@@ -4118,6 +4131,7 @@
<div class="index"><ul class="index" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">Calling User Defined Error Handlers</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/pol_tutorial/namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">Setting Policies at Namespace or Translation Unit Scope</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
@@ -4798,6 +4812,7 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/issues.html" title="Known Issues, and TODO List">Known Issues, and TODO List</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/internals1/rational.html" title="Polynomial and Rational Function Evaluation">Polynomial and Rational Function Evaluation</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/skew_normal_dist.html" title="Skew Normal Distribution">Skew Normal Distribution</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
</ul></div>
</li>
<li class="listitem" style="list-style-type: none">
@@ -5027,6 +5042,19 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/c99.html" title="C99 C Functions">C99 C Functions</a></li>
</ul></div>
</li>
+<li class="listitem" style="list-style-type: none">
+Tutorial: How to Write a New Special Function
+<div class="index"><ul class="index" style="list-style-type: none; ">
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">BOOST_FPU_EXCEPTION_GUARD</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">BOOST_MATH_STD_USING</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">called</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">constants</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">forwarding_policy</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">promote_args</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">T</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">value_type</a></li>
+</ul></div>
+</li>
</ul></div></dd>
<dt>
<a name="idx_id_116"></a>U
@@ -5251,6 +5279,7 @@
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/octonion.html" title="Template Class octonion">Template Class octonion</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/quat.html" title="Template Class quaternion">Template Class quaternion</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/triangular_dist.html" title="Triangular Distribution">Triangular Distribution</a></li>
+<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New Special Function</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/uniform_dist.html" title="Uniform Distribution">Uniform Distribution</a></li>
<li class="listitem" style="list-style-type: none"><a class="link" href="../math_toolkit/dist_ref/dists/weibull_dist.html" title="Weibull Distribution">Weibull Distribution</a></li>
</ul></div>

Modified: trunk/libs/math/doc/html/math_toolkit/conventions.html
==============================================================================
--- trunk/libs/math/doc/html/math_toolkit/conventions.html (original)
+++ trunk/libs/math/doc/html/math_toolkit/conventions.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -27,7 +27,7 @@
<a name="math_toolkit.conventions"></a><a class="link" href="conventions.html" title="Document Conventions">Document Conventions</a>
</h2></div></div></div>

- <a class="indexterm" name="id862102"></a>
+ <a class="indexterm" name="id845718"></a>


This documentation aims to use of the following naming and formatting conventions.

Modified: trunk/libs/math/doc/html/math_toolkit/navigation.html
==============================================================================
--- trunk/libs/math/doc/html/math_toolkit/navigation.html (original)
+++ trunk/libs/math/doc/html/math_toolkit/navigation.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -27,7 +27,7 @@
<a name="math_toolkit.navigation"></a><a class="link" href="navigation.html" title="Navigation">Navigation</a>
</h2></div></div></div>

- <a class="indexterm" name="id861974"></a>
+ <a class="indexterm" name="id845590"></a>


Boost.Math documentation is provided in both HTML and PDF formats.

Modified: trunk/libs/math/doc/html/math_toolkit/relative_error.html
==============================================================================
--- trunk/libs/math/doc/html/math_toolkit/relative_error.html (original)
+++ trunk/libs/math/doc/html/math_toolkit/relative_error.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../index.html" title="Math Toolkit">
<link rel="up" href="../backgrounders.html" title="Chapter 15. Backgrounders">
-<link rel="prev" href="sf_implementation.html" title="Additional Implementation Notes">
+<link rel="prev" href="special_tut.html" title="Tutorial: How to Write a New Special Function">
<link rel="next" href="lanczos.html" title="The Lanczos Approximation">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="sf_implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="special_tut.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section math_toolkit_relative_error">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -116,7 +116,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="sf_implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="special_tut.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="lanczos.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: trunk/libs/math/doc/html/math_toolkit/sf_implementation.html
==============================================================================
--- trunk/libs/math/doc/html/math_toolkit/sf_implementation.html (original)
+++ trunk/libs/math/doc/html/math_toolkit/sf_implementation.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -7,7 +7,7 @@
<link rel="home" href="../index.html" title="Math Toolkit">
<link rel="up" href="../backgrounders.html" title="Chapter 15. Backgrounders">
<link rel="prev" href="../backgrounders.html" title="Chapter 15. Backgrounders">
-<link rel="next" href="relative_error.html" title="Relative Error">
+<link rel="next" href="special_tut.html" title="Tutorial: How to Write a New Special Function">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="../backgrounders.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../backgrounders.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section math_toolkit_sf_implementation">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -841,7 +841,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="../backgrounders.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../backgrounders.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="special_tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Added: trunk/libs/math/doc/html/math_toolkit/special_tut.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/html/math_toolkit/special_tut.html 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -0,0 +1,389 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Tutorial: How to Write a New Special Function</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../index.html" title="Math Toolkit">
+<link rel="up" href="../backgrounders.html" title="Chapter 15. Backgrounders">
+<link rel="prev" href="sf_implementation.html" title="Additional Implementation Notes">
+<link rel="next" href="relative_error.html" title="Relative Error">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section math_toolkit_special_tut">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="math_toolkit.special_tut"></a><a class="link" href="special_tut.html" title="Tutorial: How to Write a New Special Function">Tutorial: How to Write a New
+ Special Function</a>
+</h2></div></div></div>
+
+ In this section we'll provide a "recipe" for adding a new special
+ function to this library to make life easier for future authors wishing to
+ contribute. We'll assume the function returns a single floating point result,
+ and takes two floating point arguments. For the sake of exposistion we'll give
+ the function the name "my_special".
+ 
+
+ Normally the implementation of such a function is split into two layers - a
+ public user layer, and an internal implementation layer that does the actual
+ work. The implementation layer is declared inside a "detail" namespace
+ and has a simple signature:
+ 
+<pre class="programlisting">namespace boost{ namespace math{ namespace detail{
+
+template <class T, class Policy>
+T my_special_imp(const T& a, const T&b, const Policy& pol)
+{
+ /* Implementation goes here */
+}
+
+}}} // namespaces
+</pre>
+
+ We'll come back to what can go inside the implementation later, but first lets
+ look at the user layer. This consists of two overloads of the function, with
+ and without a <a class="link" href="../policy.html" title="Chapter 13. Policies: Controlling Precision, Error Handling etc">Policy</a> argument:
+ 
+<pre class="programlisting">namespace boost{ namespace math{
+
+template <class T, class U>
+typename tools::promote_args<T, U>::type my_special(const T& a, const U& b);
+
+template <class T, class U, class Policy>
+typename tools::promote_args<T, U>::type my_special(const T& a, const U& b, const Policy& pol);
+
+}} // namespaces
+</pre>
+
+ Note how each argument has a different template type - this allows for mixed
+ type arguments - the return type is computed from a traits class and is the
+ "common type" of all the arguments after any integer arguments have
+ been promoted to type <code class="computeroutput">double</code>.
+ 
+
+ The implementation of the non-policy overload is trivial:
+ 
+<pre class="programlisting">namespace boost{ namespace math{
+
+template <class T, class U>
+inline typename tools::promote_args<T, U>::type my_special(const T& a, const U& b)
+{
+ // Simply forward with a default policy:
+ return my_special(a, b, policies::policy<>();
+}
+
+}} // namespaces
+</pre>
+
+ The implementation of the other overload is somewhat more complex, as there's
+ some meta-programming to do, but from a runtime perspective is still a one-line
+ forwarding function. Here it is with comments explaining what each line does:
+ 
+<pre class="programlisting">namespace boost{ namespace math{
+
+template <class T, class U, class Policy>
+inline typename tools::promote_args<T, U>::type my_special(const T& a, const U& b, const Policy& pol)
+{
+ //
+ // We've found some standard library functions to misbehave if any FPU exception flags
+ // are set prior to their call, this code will clear those flags, then reset them
+ // on exit:
+ //
+ BOOST_FPU_EXCEPTION_GUARD
+ //
+ // The type of the result - the common type of T and U after
+ // any integer types have been promoted to double:
+ //
+ typedef typename tools::promote_args<T, U>::type result_type;
+ //
+ // The type used for the calculation. This may be a wider type than
+ // the result in order to ensure full precision:
+ //
+ typedef typename policies::evaluation<result_type, Policy>::type value_type;
+ //
+ // The type of the policy to forward to the actual implementation.
+ // We disable promotion of float and double as that's [possibly]
+ // happened already in the line above. Also reset to the default
+ // any policies we don't use (reduces code bloat if we're called
+ // multiple times with differing policies we don't actually use).
+ // Also normalise the type, again to reduce code bloat in case we're
+ // called multiple times with functionally identical policies that happen
+ // to be different types.
+ //
+ typedef typename policies::normalise<
+ Policy,
+ policies::promote_float<false>,
+ policies::promote_double<false>,
+ policies::discrete_quantile<>,
+ policies::assert_undefined<> >::type forwarding_policy;
+ //
+ // Whew. Now we can make the actual call to the implementation.
+ // Arguments are explicitly cast to the evaluation type, and the result
+ // passed through checked_narrowing_cast which handles things like overflow
+ // according to the policy passed:
+ //
+ return policies::checked_narrowing_cast<result_type, forwarding_policy>(
+ detail::my_special_imp(
+ static_cast<value_type>(a),
+ static_cast<value_type>(x),
+ forwarding_policy()),
+ "boost::math::my_special<%1%>(%1%, %1%)");
+}
+
+}} // namespaces
+</pre>
+
+ We're now almost there, we just need to flesh out the details of the implementation
+ layer:
+ 
+<pre class="programlisting">namespace boost{ namespace math{ namespace detail{
+
+template <class T, class Policy>
+T my_special_imp(const T& a, const T&b, const Policy& pol)
+{
+ /* Implementation goes here */
+}
+
+}}} // namespaces
+</pre>
+
+ The following guidelines indicate what (other than basic arithmetic) can go
+ in the implementation:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem">
+ Error conditions (for example bad arguments) should be handled by calling
+ one of the <a class="link" href="error_handling.html#math_toolkit.error_handling.finding_more_information">policy
+ based error handlers</a>.
+ </li>
+<li class="listitem">
+ Calls to standard library functions should be made unqualified (this allows
+ argument dependent lookup to find standard library functions for user-defined
+ floating point types such as those from Boost.Multiprecision). In addition
+ the macro <code class="computeroutput">BOOST_MATH_STD_USING</code>
+ should appear at the start of the function (note no semi-colon afterwards!)
+ so that all the math functions in <code class="computeroutput">namespace
+ std</code> are visible in the current
+ scope.
+ </li>
+<li class="listitem">
+ Calls to other special functions should be made as fully qualified calls,
+ and include the policy parameter as the last argument, for example <code class="computeroutput">boost::math::tgamma(a, pol)</code>.
+ </li>
+<li class="listitem">
+ Where possible, evaluation of series, continued fractions, polynomials,
+ or root finding should use one of the <a class="link" href="../toolkit.html" title="Chapter 11. Internals (Series, Rationals and Continued Fractions, Root Finding, Function Minimization, Testing and Development Tools)">boiler plate
+ functions</a>. In any case, after any iterative method, you should verify
+ that the number of iterations did not exceed the maximum specified in the
+ <a class="link" href="../policy.html" title="Chapter 13. Policies: Controlling Precision, Error Handling etc">Policy</a> type, and if it did terminate as a
+ result of exceeding the maximum, then the appropriate error handler should
+ be called (see existing code for examples).
+ </li>
+<li class="listitem">
+ Numeric constants such as π etc should be obtained via a call to the <a class="link" href="../">appropriate function</a>, for example:
+ <code class="computeroutput">constants::pi<T>()</code>.
+ </li>
+<li class="listitem">
+ Where tables of coefficients are used (for example for rational approximations),
+ care should be taken to ensure these are initialized at program startup
+ to ensure thread safety when using user-defined number types. See for example
+ the use of <code class="computeroutput">erf_initializer</code>
+ in boost/math/special_functions/erf.hpp.
+ </li>
+</ul></div>
+
+ Here are some other useful internal functions:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ function
+ 
+ </th>
+<th>
+ 
+ Meaning
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ <code class="computeroutput">policies::digits<T, Policy>()</code>
+ 
+ </td>
+<td>
+ 
+ Returns number of binary digits in T (possible overridden by the
+ policy).
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">policies::get_max_series_iterations<Policy>()</code>
+ 
+ </td>
+<td>
+ 
+ Maximum number of iterations for series evaluation.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">policies::get_max_root_iterations<Policy>()</code>
+ 
+ </td>
+<td>
+ 
+ Maximum number of iterations for root finding.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">polices::get_epsilon<T, Policy>()</code>
+ 
+ </td>
+<td>
+ 
+ Epsilon for type T, possibly overridden by the Policy.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::digits<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Returns the number of binary digits in T.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::max_value<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to <code class="computeroutput">std::numeric_limits<T>::max()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::min_value<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to <code class="computeroutput">std::numeric_limits<T>::min()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::log_max_value<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to the natural logarithm of <code class="computeroutput">std::numeric_limits<T>::max()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::log_min_value<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to the natural logarithm of <code class="computeroutput">std::numeric_limits<T>::min()</code>
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::epsilon<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to <code class="computeroutput">std::numeric_limits<T>::epsilon()</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::root_epsilon<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to the square root of <code class="computeroutput">std::numeric_limits<T>::epsilon()</code>.
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ <code class="computeroutput">tools::forth_root_epsilon<T>()</code>
+ 
+ </td>
+<td>
+ 
+ Equivalent to the forth root of <code class="computeroutput">std::numeric_limits<T>::epsilon()</code>.
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012, 2013 Paul A. Bristow, Christopher Kormanyos,
+ Hubert Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin
+ Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang
+ 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)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sf_implementation.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../backgrounders.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="relative_error.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: trunk/libs/math/doc/math.qbk
==============================================================================
--- trunk/libs/math/doc/math.qbk (original)
+++ trunk/libs/math/doc/math.qbk 2013-06-02 14:14:56 EDT (Sun, 02 Jun 2013)
@@ -553,6 +553,7 @@

[mathpart backgrounders Backgrounders]
[include background/implementation.qbk]
+[include background/special_tut.qbk]
[include background/error.qbk] [/relative error NOT handling]
[include background/lanczos.qbk]
[include background/remez.qbk]

Next message: andrey.semashev_at_[hidden]: "[Boost-commit] svn:boost r84609 - trunk/boost/utility"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r84607 - in trunk: boost/thread libs/thread/test/sync/futures/async"

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