[Boost-commit] svn:boost r7542

From: pbristow_at_[hidden]
Date: 2007-07-26 06:29:59

Author: pbristow
Date: 2007-07-26 06:29:59 EDT (Thu, 26 Jul 2007)
New Revision: 7542
URL: http://svn.boost.org/trac/boost/changeset/7542

Log:
re-organised and added overview.  No tutorial yet.

Text files modified: 
   sandbox/math_toolkit/libs/math/doc/policy.qbk |   442 +++++++++++++++++++++------------------ 
   1 files changed, 237 insertions(+), 205 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/policy.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/policy.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/policy.qbk	2007-07-26 06:29:59 EDT (Thu, 26 Jul 2007)
@@ -1,186 +1,51 @@
-
 [section:policy Policies]
 
-Policies are a powerful mechanism that allow you to customise the
-behaviour of this library according to your needs.  Policies are a
-compile-time mechanism that allow you to change the behaviour of 
-things such as error-handling or calculation precision either
-program wide, or at the call site.
-
-[section:pol_overview Policy Overview and Tutorial]
-
-[endsect]
-
-[section:pol_ref Policy Reference]
-
-[section:pol_ref_ref The Policy Class]
-
-There's very little to say here, the `policy` class is just a rag-bag
-compile-time container for a collection of policies:
-
-```#include <boost/math/policy/policy.hpp>```
-
-
-   namespace boost{
-   namespace math{
-   namespace policy{
-   
-   template <class A1 = default_policy, 
-             class A2 = default_policy, 
-             class A3 = default_policy,
-             class A4 = default_policy,
-             class A5 = default_policy,
-             class A6 = default_policy,
-             class A7 = default_policy,
-             class A8 = default_policy,
-             class A9 = default_policy,
-             class A10 = default_policy,
-             class A11 = default_policy>
-   struct policy
-   {
-   public:
-      typedef ``['computed-from-template-arguments]`` domain_error_type;
-      typedef ``['computed-from-template-arguments]`` pole_error_type;
-      typedef ``['computed-from-template-arguments]`` overflow_error_type;
-      typedef ``['computed-from-template-arguments]`` underflow_error_type;
-      typedef ``['computed-from-template-arguments]`` denorm_error_type;
-      typedef ``['computed-from-template-arguments]`` evaluation_error_type;
-      typedef ``['computed-from-template-arguments]`` precision_type;
-      typedef ``['computed-from-template-arguments]`` promote_float_type;
-      typedef ``['computed-from-template-arguments]`` promote_double_type;
-      typedef ``['computed-from-template-arguments]`` discrete_quantile_type;
-      typedef ``['computed-from-template-arguments]`` assert_undefined_type;
-   };
-
-   template <...argument list...>
-   typename normalise<policy<>, A1>::type make_policy(...argument list..);
-
-   template <class Policy, 
-             class A1 = default_policy, 
-             class A2 = default_policy, 
-             class A3 = default_policy,
-             class A4 = default_policy,
-             class A5 = default_policy,
-             class A6 = default_policy,
-             class A7 = default_policy,
-             class A8 = default_policy,
-             class A9 = default_policy,
-             class A10 = default_policy,
-             class A11 = default_policy>
-   struct normalise
-   {
-      typedef ``computed-from-template-arguments`` type;
-   };
-
-The member typedefs of class `policy` are intended for internal use
-but are documented briefly here for the sake of completeness.
-
-   policy<...>::domain_error_type
-   
-Specifies how domain errors are handled, will be an instance of
-`boost::math::policy::domain_error<>` with the template argument to
-`domain_error` one of the `error_policy_type` enumerated values.
-
-   policy<...>::pole_error_type
-   
-Specifies how pole-errors are handled, will be an instance of
-`boost::math::policy::pole_error<>` with the template argument to
-`pole_error` one of the `error_policy_type` enumerated values.
-
-   policy<...>::overflow_error_type
-   
-Specifies how overflow errors are handled, will be an instance of
-`boost::math::policy::overflow_error<>` with the template argument to
-`overflow_error` one of the `error_policy_type` enumerated values.
-
-   policy<...>::underflow_error_type
-   
-Specifies how underflow errors are handled, will be an instance of
-`boost::math::policy::underflow_error<>` with the template argument to
-`underflow_error` one of the `error_policy_type` enumerated values.
+[section:pol_overview Policy Overview]
 
-   policy<...>::denorm_error_type
-   
-Specifies how denorm errors are handled, will be an instance of
-`boost::math::policy::denorm_error<>` with the template argument to
-`denorm_error` one of the `error_policy_type` enumerated values.
+Policies are a powerful fine-grain mechanism that allow you to customise the
+behaviour of this library according to your needs.
 
-   policy<...>::evaluation_error_type
-   
-Specifies how evaluation errors are handled, will be an instance of
-`boost::math::policy::evaluation_error<>` with the template argument to
-`evaluation_error` one of the `error_policy_type` enumerated values.
-
-   policy<...>::precision_type
-   
-Specifies the internal precision to use in binary digits (uses zero
-to represent whatever the default precision is).  Will be an instance
-of `boost::math::policy::digits2<N>` which in turn inherits from 
-`boost::mpl::int_<N>`.
-
-   policy<...>::promote_float_type
-   
-Specifies whether or not to promote `float` arguments to `double` precision
-internally.  Will be an instance of `boost::math::policy::promote_float<B>`
-which in turn inherits from `boost::mpl::bool_<B>`.
-
-   policy<...>::promote_double_type
-   
-Specifies whether or not to promote `double` arguments to `long double` precision
-internally.  Will be an instance of `boost::math::policy::promote_float<B>`
-which in turn inherits from `boost::mpl::bool_<B>`.
-
-   policy<...>::discrete_quantile_type
-   
-Specifies how discrete quantiles are evaluated, will be an instance
-of `boost::math::policy::discrete_quantile<>` instantiated with one of
-the `discrete_quantile_policy_type` enumerated type.
-
-   policy<...>::assert_undefined_type
-   
-Specifies whether mathematically-undefined properties are
-asserted as compile-time errors, or treated as runtime errors
-instead.  Will be an instance of `boost::math::policy::assert_undefined<B>`
-which in turn inherits from `boost::math::mpl::bool_<B>`.
+Unless you find that the default policy behaviour
+when encountering 'bad' argument values does not meet your needs,
+you should not need to worry about policies.
 
+Policies are a compile-time mechanism that allow you to change 
+error-handling or calculation precision either
+program wide, or at the call site.
 
-   template <...argument list...>
-   typename normalise<policy<>, A1>::type make_policy(...argument list..);
+Although the policy mechanism itself is rather complicated,
+in practice it is easy to use, and very flexible.
 
-`make_policy` is a helper function that converts a list of policies into
-a normalised `policy` class.
+Using policies you can control:
 
-   template <class Policy, 
-             class A1 = default_policy, 
-             class A2 = default_policy, 
-             class A3 = default_policy,
-             class A4 = default_policy,
-             class A5 = default_policy,
-             class A6 = default_policy,
-             class A7 = default_policy,
-             class A8 = default_policy,
-             class A9 = default_policy,
-             class A10 = default_policy,
-             class A11 = default_policy>
-   struct normalise
-   {
-      typedef ``computed-from-template-arguments`` type;
-   };
-   
-The `normalise` class template converts one instantiation of the
-`policy` class into a normalised form.  This is used internally
-to reduce code bloat: so that instantiating a special function
-on `policy<A,B>` or `policy<B,A>` actually both generate the same
-code internally.
+* [link math_toolkit.policy.pol_ref.error_handling_policies How results from 'bad' arguments are handled],
+   including those that cannot be fully evaluated.
+* How [link math_toolkit.policy.pol_ref.internal_promotion accuracy is controlled by internal promotion] to use more precise types.
+* What working [link math_toolkit.policy.pol_ref.precision_pol precision] should be used to calculate results.
+* What do to when a [link math_toolkit.policy.pol_ref.assert_undefined mathematically undefined function]
+  is used. Compile or not?
+* Whether [link math_toolkit.policy.pol_ref.discrete_quant_ref discrete functions],
+  like the binomial, should return real or only integral values, and how they are rounded.
+  
+You can control policies:
+
+* Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to change any default policy.
+* At your chosen [link math_toolkit.policy.pol_ref.namespace_pol namespace scope] for distributions and/or functions.
+
+[endsect][/section:pol_overview Policy Overview]
+
+[section:pol_tutorial Policy Tutorial]
+TODO??
+[endsect][/section:pol_Tutorial Policy Tutorial]
 
-[endsect]
+[section:pol_ref Policy Reference]
 
-[section Error Handling Policies]
+[section:error_handling_policies Error Handling Policies]
 
 There are two orthogonal aspects to error handling:
 
-# What to do (if anything) with the error.
-# What kind of error is being raised.
+* What to do (if anything) with the error.
+* What kind of error is being raised.
 
 [h4 Available Actions When an Error is Raised]
 
@@ -190,10 +55,10 @@
    
    enum error_policy_type
    {
-      throw_on_error = 0,
-      errno_on_error = 1,
-      ignore_error = 2,
-      user_error = 3
+      throw_on_error = 0, // throw an exception.
+      errno_on_error = 1, // set ::errno & return 0, NaN, infinity or best guess.
+      ignore_error = 2, // return 0, NaN, infinity or best guess.
+      user_error = 3  // call a user-defined error handler.
    };
 
    }}} // namespaces
@@ -216,7 +81,7 @@
 
 [h5 errno_on_error]
 
-Will set ::errno to one of the following values depending 
+Will set global ::errno to one of the following values depending 
 upon the error type, and then return the same value as if the error
 had been ignored:
  [table
@@ -231,7 +96,7 @@
 
 [h5 ignore_error]
 
-Will return a one of the values below depending on the error type:
+Will return a one of the values below depending on the error type (::errno is NOT changed)::
  [table
     [[Error Type][errno value]]
     [[Domain Error][std::numeric_limits<T>::quiet_NaN()]]
@@ -245,7 +110,7 @@
 
 [h5 user_error]
 
-Will call a user defined error handler, these are forward declared
+Will call a user defined error handler: these are forward declared
 in boost/math/policy/error_handling.hpp, but the actual definitions
 must be provided by the user:
 
@@ -341,8 +206,8 @@
 
 [h4 Examples]
 
-Suppose we want a call to `tgamma` to behave in a C-compatible way and set
-`errno` rather than throw an exception, we can achieve this at the call site
+Suppose we want a call to `tgamma` to behave in a C-compatible way and set global
+`::errno` rather than throw an exception, we can achieve this at the call site
 using:
 
    #include <boost/math/special_functions/gamma.hpp>
@@ -369,7 +234,7 @@
             evaluation_error<errno_on_error>() 
          ));
    
-Suppose we want a statistical distribution to return infinities
+Suppose we want a statistical distribution to return infinities,
 rather than throw exceptions, then we can use:
 
    #include <boost/math/distributions/normal.hpp>
@@ -382,13 +247,13 @@
          overflow_error<ignore_error>
          > my_policy;
          
-   // define the distribution:
+   // Define the distribution:
    typedef normal_distribution<double, my_policy> my_norm;
    
-   // get a quantile:
+   // Get a quantile:
    double q = quantile(my_norm(), 0.05);
 
-[endsect]
+[endsect][/section:error_handling_policies Error Handling Policies]
 
 [section:internal_promotion Internal Promotion Policies]
 
@@ -422,7 +287,7 @@
          promote_double<false> 
          > my_policy;
          
-   // call the function:
+   // Call the function:
    double t = tgamma(some_value, my_policy());
    
    // Alternatively we could use make_policy and define everything at the call site:
@@ -441,21 +306,21 @@
          promote_float<false>
          > my_policy;
          
-   // define the distribution:
+   // Define the distribution:
    typedef normal_distribution<float, my_policy> my_norm;
    
-   // get a quantile:
+   // Get a quantile:
    float q = quantile(my_norm(), 0.05f);
    
-[endsect]
+[endsect][/section:internal_promotion Internal Promotion Policies]
 
 [section:assert_undefined Mathematically Undefined Function Policies]
 
-There are some functions that are generic - which is to say they are
-present for all the statistical distributions supported - but which
-may be mathematically undefined for certain distributions, but not others.
+There are some functions that are generic
+(they are present for all the statistical distributions supported)
+but which may be mathematically undefined for certain distributions, but defined for others.
 
-For example the Cauchy distribution does not have a mean, so what should
+For example, the Cauchy distribution does not have a mean, so what should
 
    mean(cauchy<>());
    
@@ -465,8 +330,8 @@
  - in fact they will raise a 
 [@http://www.boost.org/libs/static_assert/index.html static assertion]
  - but by changing the policy
-we can have them return the result of a domain error instead (which may well
-throw an exception). 
+we can have them return the result of a domain error instead
+(which may well throw an exception, depending on the error handling policy). 
 
 This behaviour is controlled by the `assert_undefined<>` policy:
 
@@ -490,14 +355,14 @@
    // This will compile, but raises a domain error!
    double m2 = mean(cauchy_distribution<double, policy<assert_undefined<false> > >());
  
-[endsect]
+[endsect][/section:assert_undefined Mathematically Undefined Function Policies]
 
 [section:discrete_quant_ref Discrete Quantile Policies]
 
 If a statistical distribution is ['discrete] then the random variable
 can only have integer values - this leaves us with a problem when calculating
 quantiles - we can either ignore the discreteness of the distribution and return
-a real value, or we can round to an integer.  As it happens computing integer
+a real value, or we can round to an integer.  As it happens, computing integer
 values can be substantially faster than calculating a real value, so there are
 definite advantages to returning an integer, but we do then need to decide
 how best to round the result.  The `discrete_quantile` policy defines how
@@ -651,7 +516,7 @@
 
 Results in `x = 27` (rounded from 27.3898) and `y = 68` (rounded from 68.1584).
 
-[endsect]
+[endsect][/section:discrete_quant_ref Discrete Quantile Policies]
 
 [section:precision_pol Precision Policies]
 
@@ -710,9 +575,9 @@
          normal_distribution<double, policy<digits2<25> >(), 
          0.05);
 
-[endsect]
+[endsect][/section:precision_pol Precision Policies]
 
-[section Changing the Policy Defaults]
+[section:policy_defaults Changing the Policy Defaults]
 
 If you want to alter the defaults for any of 
 the policies then you can do so by defining various macros in
@@ -739,7 +604,6 @@
 actions for error handing: `throw_on_error`, `errno_on_error`, 
 `ignore_error` or `user_error`.
 
-
 [h5 BOOST_MATH_EVALUATION_ERROR_POLICY]
 
 Defines what happens when an internal evaluation error occurs, if not defined then
@@ -812,7 +676,7 @@
    #define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
    #define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
 
-[endsect]
+[endsect][/section:policy_defaults Changing the Policy Defaults]
 
 [section:namespace_pol Setting Polices at Namespace Scope]
 
@@ -865,7 +729,7 @@
 linker errors from undefined functions.
 
 We can do the same thing with the distributions, but this time we need to
-specify the floating point type to use:
+specify the floating-point type to use:
 
    #include <boost/math/distributions/cauchy.hpp>
    
@@ -882,7 +746,6 @@
    
    }
    
-   //
    // Now we can use myspace::cauchy etc, which will use policy
    // myspace::mypolicy:
    //
@@ -899,8 +762,177 @@
 and so on.  The name given to each typedef is the name of the distribution
 with the "_distribution" suffix removed.
 
-[endsect]
+[endsect][/section Changing the Policy Defaults]
+
+[section:pol_ref_ref Policy Class Reference]
+
+There's very little to say here, the `policy` class is just a rag-bag
+compile-time container for a collection of policies:
+
+```#include <boost/math/policy/policy.hpp>```
+
+
+   namespace boost{
+   namespace math{
+   namespace policy
+   
+   template <class A1 = default_policy, 
+             class A2 = default_policy, 
+             class A3 = default_policy,
+             class A4 = default_policy,
+             class A5 = default_policy,
+             class A6 = default_policy,
+             class A7 = default_policy,
+             class A8 = default_policy,
+             class A9 = default_policy,
+             class A10 = default_policy,
+             class A11 = default_policy>
+   struct policy
+   {
+   public:
+      typedef ``['computed-from-template-arguments]`` domain_error_type;
+      typedef ``['computed-from-template-arguments]`` pole_error_type;
+      typedef ``['computed-from-template-arguments]`` overflow_error_type;
+      typedef ``['computed-from-template-arguments]`` underflow_error_type;
+      typedef ``['computed-from-template-arguments]`` denorm_error_type;
+      typedef ``['computed-from-template-arguments]`` evaluation_error_type;
+      typedef ``['computed-from-template-arguments]`` precision_type;
+      typedef ``['computed-from-template-arguments]`` promote_float_type;
+      typedef ``['computed-from-template-arguments]`` promote_double_type;
+      typedef ``['computed-from-template-arguments]`` discrete_quantile_type;
+      typedef ``['computed-from-template-arguments]`` assert_undefined_type;
+   };
+
+   template <...argument list...>
+   typename normalise<policy<>, A1>::type make_policy(...argument list..);
+
+   template <class Policy, 
+             class A1 = default_policy, 
+             class A2 = default_policy, 
+             class A3 = default_policy,
+             class A4 = default_policy,
+             class A5 = default_policy,
+             class A6 = default_policy,
+             class A7 = default_policy,
+             class A8 = default_policy,
+             class A9 = default_policy,
+             class A10 = default_policy,
+             class A11 = default_policy>
+   struct normalise
+   {
+      typedef ``computed-from-template-arguments`` type;
+   };
+
+The member typedefs of class `policy` are intended for internal use
+but are documented briefly here for the sake of completeness.
+
+   policy<...>::domain_error_type
+   
+Specifies how domain errors are handled, will be an instance of
+`boost::math::policy::domain_error<>` with the template argument to
+`domain_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::pole_error_type
+   
+Specifies how pole-errors are handled, will be an instance of
+`boost::math::policy::pole_error<>` with the template argument to
+`pole_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::overflow_error_type
+   
+Specifies how overflow errors are handled, will be an instance of
+`boost::math::policy::overflow_error<>` with the template argument to
+`overflow_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::underflow_error_type
+   
+Specifies how underflow errors are handled, will be an instance of
+`boost::math::policy::underflow_error<>` with the template argument to
+`underflow_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::denorm_error_type
+   
+Specifies how denorm errors are handled, will be an instance of
+`boost::math::policy::denorm_error<>` with the template argument to
+`denorm_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::evaluation_error_type
+   
+Specifies how evaluation errors are handled, will be an instance of
+`boost::math::policy::evaluation_error<>` with the template argument to
+`evaluation_error` one of the `error_policy_type` enumerated values.
+
+   policy<...>::precision_type
+   
+Specifies the internal precision to use in binary digits (uses zero
+to represent whatever the default precision is).  Will be an instance
+of `boost::math::policy::digits2<N>` which in turn inherits from 
+`boost::mpl::int_<N>`.
+
+   policy<...>::promote_float_type
+   
+Specifies whether or not to promote `float` arguments to `double` precision
+internally.  Will be an instance of `boost::math::policy::promote_float<B>`
+which in turn inherits from `boost::mpl::bool_<B>`.
+
+   policy<...>::promote_double_type
+   
+Specifies whether or not to promote `double` arguments to `long double` precision
+internally.  Will be an instance of `boost::math::policy::promote_float<B>`
+which in turn inherits from `boost::mpl::bool_<B>`.
+
+   policy<...>::discrete_quantile_type
+   
+Specifies how discrete quantiles are evaluated, will be an instance
+of `boost::math::policy::discrete_quantile<>` instantiated with one of
+the `discrete_quantile_policy_type` enumerated type.
 
-[endsect]
+   policy<...>::assert_undefined_type
+   
+Specifies whether mathematically-undefined properties are
+asserted as compile-time errors, or treated as runtime errors
+instead.  Will be an instance of `boost::math::policy::assert_undefined<B>`
+which in turn inherits from `boost::math::mpl::bool_<B>`.
+
+
+   template <...argument list...>
+   typename normalise<policy<>, A1>::type make_policy(...argument list..);
+
+`make_policy` is a helper function that converts a list of policies into
+a normalised `policy` class.
+
+   template <class Policy, 
+             class A1 = default_policy, 
+             class A2 = default_policy, 
+             class A3 = default_policy,
+             class A4 = default_policy,
+             class A5 = default_policy,
+             class A6 = default_policy,
+             class A7 = default_policy,
+             class A8 = default_policy,
+             class A9 = default_policy,
+             class A10 = default_policy,
+             class A11 = default_policy>
+   struct normalise
+   {
+      typedef ``computed-from-template-arguments`` type;
+   };
+   
+The `normalise` class template converts one instantiation of the
+`policy` class into a normalised form.  This is used internally
+to reduce code bloat: so that instantiating a special function
+on `policy<A,B>` or `policy<B,A>` actually both generate the same
+code internally.
+
+[endsect][/section:pol_ref_ref Policy Class Reference]
+
+[endsect][/section:pol_ref Policy Reference]
+[endsect][/section:policy Policies]
+
+[/ math.qbk
+  Copyright 2007 John Maddock and Paul A. Bristow.
+  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).
+]
 
-[endsect]