[Boost-commit] svn:boost r38628 - sandbox/math_toolkit/libs/math/doc

From: pbristow_at_[hidden]
Date: 2007-08-13 16:09:08

Author: pbristow
Date: 2007-08-13 16:09:04 EDT (Mon, 13 Aug 2007)
New Revision: 38628
URL: http://svn.boost.org/trac/boost/changeset/38628

Log:
Updated for policy error handling
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/error_handling.qbk |    98 +++++++++++++++++---------------------- 
   1 files changed, 42 insertions(+), 56 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/error_handling.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/error_handling.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/error_handling.qbk	2007-08-13 16:09:04 EDT (Mon, 13 Aug 2007)
@@ -1,46 +1,36 @@
 [section:error_handling Error Handling]
 
-[caution This documentation is out of date.  
-
-TODO: rewrite me please!! ]
-
 [def __format [@../../libs/format/index.html Boost.Format]]
 
 [h4 synopsis]
 
-``
-#include <boost/math/tools/error_handling.hpp>
-``
-   
-   template <class T>
-   T __domain_error(const char* function, const char* message, const T& val);
-   
-   template <class T>
-   T __pole_error(const char* function, const char* message, const T& val);
-   
-   template <class T>
-   T __overflow_error(const char* function, const char* message);
-   
-   template <class T>
-   T __underflow_error(const char* function, const char* message);
-   
-   template <class T>
-   T __denorm_error(T const& t, const char* function, const char* message);
-   
-   template <class T>
-   T __logic_error(const char* function, const char* message, const T& val);
-   
-   template <class T, class U>
-   T __checked_narrowing_cast(U const& val, const char* function);
+Several __error_policy are provided to allow fine-grained control of the behaviour
+when arguments are passed for which values cannot be computed, for example,
+causing overflow, underflow, at a pole, or when accurate evaluation proves impossible.
+Defaults behaviour is provided that should be suitable for most applications.
+To provide ultimate control a user-defined error policy also can be implemented
+to provide specific __user_error_handling.
 
 The functions in this header are designed to be user-replaceable error
 handlers that define how errors are handled by the special functions
-in this library.  There are also some pre-processor defines that can be 
-set to activate the throwing of C++ exceptions from the default
-versions of the functions.  The various kind of errors are described 
-in more detail below.
+in this library. See __user_error_handling.
+
+There are also some pre-processor macro defines that can be used to
+__changing_policy_defaults changing policies defaults.
+
+The various kind of errors are described in more detail below.
+
+[h4 Example - using the macro BOOST_MATH_DOMAIN_ERROR_POLICY]
+
+[/import ../../example/error_handling_example.cpp] [/ already imported so use a link instead.]
+[/error_handling_example]
+
+An example is at the Policy tutorial in
+[link math_toolkit.policy.pol_tutorial.changing_policy_defaults Changing the Policy Defaults].
 
-See also [@../../example/error_handling_example.cpp error_handling_example.cpp]
+Full source code of this typical example of passing a 'bad' argument
+(negative degrees of freedom) to Student's t distribution 
+is at [@../../example/error_handling_example.cpp error_handling_example.cpp].
 
 [#domain_error][h4 Domain Errors]
 
@@ -55,10 +45,9 @@
 name of the function, `Message` is an error message describing the problem, 
 and Val is the value that was out of range.
 
-The default behaviour of this function is to return a NaN.  However, if type
-`T` does not support NaN's or if the macro BOOST_MATH_THROW_ON_DOMAIN_ERROR
-is defined when building the library, then a std::domain_error C++ exception 
-is thrown.
+The default policy behaviour of this function is to throw a 
+std::domain_error C++ exception.  But if the policy is to ignore
+the error, or set global ::errno, then a NaN will be returned.
 
 This behaviour is chosen to assist compatibility with the behaviour of 
 ['ISO/IEC 9899:1999 Programming languages - C]
@@ -103,8 +92,9 @@
 name of the function, `Message` is an error message describing the problem, 
 and `Val` is the value of the argument that is at a pole.
 
-The default behaviour of this function is to return the result of
-`domain_error<T>(FunctionName, Message, Val)`.
+The default behaviour of this function is to throw a std::domain_error exception.
+But __error_policy can be used to change this, for example to ignore_error
+and return NaN.
 
 Note that in order to support information-rich error messages when throwing
 exceptions, `Message` must contain
@@ -118,7 +108,7 @@
 [#overflow_error][h4 Numeric Overflow]
 
 When the result of a special function is too large to fit in the argument
-floating point type, then the function returns the result of:
+floating-point type, then the function returns the result of:
 
    boost::math::tools::overflow_error<T>(FunctionName, Message);
    
@@ -126,11 +116,11 @@
 `T` is the floating-point type passed to the function, `FunctionName` is the 
 name of the function, and `Message` is an error message describing the problem.
 
-The default version of this function returns 
-`std::numeric_limits<T>::infinity()`.  However if the type `T` doesn't
-support infinities, or the macro BOOST_MATH_THROW_ON_OVERFLOW_ERROR
-is defined when building the library, then a `std::overflow_error` 
-C++ exception is thrown.
+The default policy for this function is that `std::overflow_error` 
+C++ exception is thrown. But if, for example, an ignore_error policy 
+is used, then returns `std::numeric_limits<T>::infinity()`.
+However if the type `T` doesn't support infinities,
+the maximum value for the type is returned.
 
 [#underflow_error][h4 Numeric Underflow]
 
@@ -143,10 +133,8 @@
 `T` is the floating point type passed to the function, `FunctionName` is the 
 name of the function, and `Message` is an error message describing the problem.
 
-The default version of this function returns zero.
-However if the macro BOOST_MATH_THROW_ON_UNDERFLOW_ERROR
-is defined when building the library, then a `std::underflow_error` 
-C++ exception is thrown.
+The default version of this function throws an `std::underflow_error` 
+C++ exception.  But with another policy, like ignore_error, returns zero.
 
 [#denorm_error][h4 Denormalisation Errors]
 
@@ -159,24 +147,22 @@
 `T` is the floating point type passed to the function, `FunctionName` is the 
 name of the function, and `Message` is an error message describing the problem.
 
-The default version of this function returns 
-/z/.  However if the macro BOOST_MATH_THROW_ON_DENORM_ERROR
-is defined when building the library, then a `std::underflow_error` 
-C++ exception is thrown.
+The default version of this function throws an `std::underflow_error` 
+C++ exception.  But with another policy, like ignore_error, returns /z/. 
 
-[#logic_error][h4 Internal Logic Errors]
+[#evaluation_error][h4 Evaluation Errors]
 
 When a special function calculates a result that is known to be erroneous,
 or where the result is incalculable then it calls:
 
-   boost::math::tools::logic_error<T>(FunctionName, Message, Val);
+   boost::math::tools::evaluation_error<T>(FunctionName, Message, Val);
    
 Where
 `T` is the floating point type passed to the function, `FunctionName` is the 
 name of the function, `Message` is an error message describing the problem,
 and `Val` is the erroneous value.
 
-The default behaviour of this function is to throw a `std::logic_error`.
+The default behaviour of this function is to throw a `std::evaluation_error`.
 
 Note that in order to support information rich error messages when throwing
 exceptions, `Message` must contain