[Boost-commit] svn:boost r42925 - in sandbox/math_toolkit/libs/math: doc/sf_and_dist test

From: john_at_[hidden]
Date: 2008-01-23 08:14:23

Author: johnmaddock
Date: 2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
New Revision: 42925
URL: http://svn.boost.org/trac/boost/changeset/42925

Log:
Adjusted error levels for non-central chi square for Minwg support.
Added rounding_error to docs.
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/error_handling.qbk  |    40 +++++++++++++++++++++++++++++++++       
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/math.qbk            |     7 +++++                                   
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy.qbk          |    26 +++++++++++++++++++++                   
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy_tutorial.qbk |     1                                         
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/rounding_func.qbk   |    48 ++++++++++++++++++++++++++++++++++++++++
   sandbox/math_toolkit/libs/math/test/test_nc_chi_squared.cpp        |     2                                         
   6 files changed, 123 insertions(+), 1 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/error_handling.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/error_handling.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/error_handling.qbk	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -26,6 +26,9 @@
    to be represented by any other value in the type being returned by 
    the function.]]
 [[Denormalisation Error][Occurs when the returned result would be a denormalised value.]]
+[[Rounding Error][Occurs when the argument to one of the rounding functions __trunc, 
+   __round and __modf can not be represented as an integer type, is is
+   outide the range of the result type.]]
 [[Evaluation Error][Occurs when an internal error occured that prevented the
    result from being evaluated: this should never occur, but if it does, then
    it's likely to be due to an iterative method not converging fast enough.]]
@@ -100,6 +103,16 @@
             this function must be defined by the user].]]
 ]
 
+[table Possible Actions for Rounding Errors
+[[Action]   [Behaviour]]
+[[throw_on_error][Throws `boost::math::rounding_error`]]
+[[errno_on_error][Sets `::errno` to `ERANGE` and returns an unspecified value.]]
+[[ignore_error][[*Returns the an unspecified value.]]]
+[[user_error][Returns the result of `boost::math::policies::user_rounding_error`: 
+            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
+            this function must be defined by the user].]]
+]
+
 [table Possible Actions for Internal Evaluation Errors
 [[Action]   [Behaviour]]
 [[throw_on_error][[*Throws `boost::math::evaluation_error`]]]
@@ -291,6 +304,33 @@
 `val` to the full precision of T, where as "%.3g" would contain the value of
 `val` to 3 digits.  See the __format documentation for more details.
 
+[heading [#rounding_error]Rounding Errors]
+
+When one of the rounding functions __round, __trunc or __modf is
+called with an argument that has no integer representation, or
+is too large to be represented in the result type then the 
+value returned is the result of a call to:
+
+   boost::math::policies::raise_rounding_error<T>(FunctionName, Message, Val, __Policy);
+   
+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,
+`Val` is the erroneous argument,
+and __Policy is the current policy
+in use for the called function.
+
+The default behaviour of this function is to throw a `boost::math::rounding_error`.
+
+Note that in order to support information rich error messages when throwing
+exceptions, `Message` must contain
+a __format recognised format specifier: the argument `val` is inserted into
+the error message according to the specifier used.
+
+For example if `Message` contains a "%1%" then it is replaced by the value of
+`val` to the full precision of T, where as "%.3g" would contain the value of
+`val` to 3 digits.  See the __format documentation for more details.
+
 [heading [#checked_narrowing_cast]Errors from typecasts]
 
 Many special functions evaluate their results at a higher precision

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/math.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/math.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/math.qbk	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -65,6 +65,7 @@
 [def __underflow_error [link underflow_error underflow_error]]
 [def __denorm_error [link denorm_error denorm_error]]
 [def __evaluation_error [link evaluation_error evaluation_error]]
+[def __rounding_error [link rounding_error rounding_error]]
 [def __checked_narrowing_cast [link checked_narrowing_cast checked_narrowing_cast]]
 
 [def __arg_pomotion_rules [link math_toolkit.main_overview.result_type ['result type calculation rules]]]
@@ -170,6 +171,12 @@
 [def __expint_i [link math_toolkit.special.expint.expint_i zeta]]
 [def __expint_n [link math_toolkit.special.expint.expint_n zeta]]
 
+[/rounding]
+[def __round [link math_toolkit.special.rounding.round round]]
+[def __trunc [link math_toolkit.special.rounding.trunc trunc]]
+[def __modf [link math_toolkit.special.rounding.modf modf]]
+
+
 
 
 [/ distribution non-members]

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy.qbk	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -100,6 +100,9 @@
    T user_denorm_error(const char* function, const char* message, const T& val);
    
    template <class T>
+   T user_rounding_error(const char* function, const char* message, const T& val);
+   
+   template <class T>
    T user_evaluation_error(const char* function, const char* message, const T& val);
    
    }}} // namespaces
@@ -168,6 +171,15 @@
       Defaults to `boost::math::policies::denorm_error<ignore_error>`
 
       When the action is ['throw_on_error] then throws a `std::underflow_error`]]
+[[Rounding Error]
+   [boost::math::policies::rounding_error<['action]>]
+      [Raised When one of the rounding functions __round, __trunc or __modf is
+      called with an argument that has no integer representation, or
+      is too large to be represented in the result type
+
+      Defaults to `boost::math::policies::rounding_error<throw_on_error>`
+
+      When the action is ['throw_on_error] then throws `boost::math::rounding_error`]]
 [[Evaluation Error]
    [boost::math::policies::evaluation_error<['action]>]
       [Raised when the result of the function is well defined and
@@ -497,6 +509,13 @@
 actions for error handing: `throw_on_error`, `errno_on_error`, 
 `ignore_error` or `user_error`.
 
+[h5 BOOST_MATH_ROUNDING_ERROR_POLICY]
+
+Defines what happens when a rounding error occurs, if not defined then
+defaults to `throw_on_error`, but can be set to any of the enumerated
+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
@@ -674,6 +693,7 @@
       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]`` rounding_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;
@@ -735,6 +755,12 @@
 `boost::math::policies::denorm_error<>` with the template argument to
 `denorm_error` one of the `error_policy_type` enumerated values.
 
+   policy<...>::rounding_error_type
+   
+Specifies how rounding errors are handled, will be an instance of
+`boost::math::policies::rounding_error<>` with the template argument to
+`rounding_error` one of the `error_policy_type` enumerated values.
+
    policy<...>::evaluation_error_type
    
 Specifies how evaluation errors are handled, will be an instance of

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy_tutorial.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy_tutorial.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy_tutorial.qbk	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -44,6 +44,7 @@
 [[Overflow Error][Throws a `std::overflow_error` exception.]]
 [[Underflow][Ignores the underflow, and returns zero.]]
 [[Denormalised Result][Ignores the fact that the result is denormalised, and returns it.]]
+[[Rounding Error][Throws a `boost::math::rounding_error` exception.]]
 [[Internal Evaluation Error][Throws a `boost::math::evaluation_error` exception.]]
 [[Promotion of float to double][Does occur by default - gives full float precision results.]]
 [[Promotion of double to long double][Does occur by default if long double offers

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/rounding_func.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/rounding_func.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/rounding_func.qbk	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -6,20 +6,36 @@
    template <class T>
    T round(const T& v);
    
+   template <class T, class Policy>
+   T round(const T& v, const Policy&);
+   
    template <class T>
    int iround(const T& v);
 
+   template <class T, class Policy>
+   int iround(const T& v, const Policy&);
+
    template <class T>
    long lround(const T& v);
 
+   template <class T, class Policy>
+   long lround(const T& v, const Policy&);
+
    template <class T>
    long long llround(const T& v);
 
+   template <class T, class Policy>
+   long long llround(const T& v, const Policy&);
+
 These functions return the closest integer to the argument /v/.
 
 Halfway cases are rounded away from zero, regardless of the current rounding
 direction.
 
+If the argument /v/ is either non-finite or else outside the range
+of the result type, then returns the result of __rounding_error: by
+default this throws an instance of boost::math::rounding_error.
+
 [endsect]
 
 [section:trunc Truncation Functions]
@@ -27,21 +43,37 @@
    template <class T>
    T trunc(const T& v);
 
+   template <class T, class Policy>
+   T trunc(const T& v, const Policy&);
+
    template <class T>
    int itrunc(const T& v);
 
+   template <class T, class Policy>
+   int itrunc(const T& v, const Policy&);
+
    template <class T>
    long ltrunc(const T& v);
 
+   template <class T, class Policy>
+   long ltrunc(const T& v, const Policy&);
+
    template <class T>
    long long lltrunc(const T& v);
 
+   template <class T, class Policy>
+   long long lltrunc(const T& v, const Policy&);
+
 The trunc functions round their argument to the integer value,
 nearest to but no larger in magnitude than the argument.
 
 For example `itrunc(3.7)` would return `3` and `ltrunc(-4.6)` 
 would return `-4`.
 
+If the argument /v/ is either non-finite or else outside the range
+of the result type, then returns the result of __rounding_error: by
+default this throws an instance of boost::math::rounding_error.
+
 [endsect]
 
 [section:modf Integer and Fractional Part Splitting (modf)]
@@ -49,18 +81,34 @@
    template <class T>
    T modf(const T& v, T* ipart);
 
+   template <class T, class Policy>
+   T modf(const T& v, T* ipart, const Policy&);
+
    template <class T>
    T modf(const T& v, int* ipart);
 
+   template <class T, class Policy>
+   T modf(const T& v, int* ipart, const Policy&);
+
    template <class T>
    T modf(const T& v, long* ipart);
 
+   template <class T, class Policy>
+   T modf(const T& v, long* ipart, const Policy&);
+
    template <class T>
    T modf(const T& v, long long* ipart);
 
+   template <class T, class Policy>
+   T modf(const T& v, long long* ipart, const Policy&);
+
 The `modf` functions store the integer part of /v/ in `*ipart` 
 and return the fractional part of /v/.
 
+If the argument /v/ is either non-finite or else outside the range
+of the result type, then returns the result of __rounding_error: by
+default this throws an instance of boost::math::rounding_error.
+
 [endsect]
 
 

Modified: sandbox/math_toolkit/libs/math/test/test_nc_chi_squared.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/test/test_nc_chi_squared.cpp	(original)
+++ sandbox/math_toolkit/libs/math/test/test_nc_chi_squared.cpp	2008-01-23 08:14:22 EST (Wed, 23 Jan 2008)
@@ -96,7 +96,7 @@
       "[^|]*",                          // platform
       largest_type,                     // test type(s)
       "[^|]*large[^|]*",                   // test data group
-      "[^|]*", 10000, 3000);                  // test function
+      "[^|]*", 15000, 3000);                  // test function
 
    //
    // Allow some long double error to creep into