|
|
Boost-Commit : |
From: bruno.lalande_at_[hidden]
Date: 2008-06-22 14:03:55
Author: bruno.lalande
Date: 2008-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
New Revision: 46617
URL: http://svn.boost.org/trac/boost/changeset/46617
Log:
Documented the new indeterminate_result_error.
Fixed an error about ignore_error and errno_on_error bahavior on an evaluation error.
Text files modified:
sandbox/math_toolkit/libs/math/doc/sf_and_dist/error_handling.qbk | 33 ++++++++++++++++++++++-
sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy.qbk | 54 ++++++++++++++++++++++++++++++---------
sandbox/math_toolkit/libs/math/doc/sf_and_dist/policy_tutorial.qbk | 1
sandbox/math_toolkit/libs/math/doc/sf_and_dist/pow.qbk | 23 +++++++++++++---
sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp | 2 +
5 files changed, 93 insertions(+), 20 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-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
@@ -32,6 +32,8 @@
[[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.]]
+[[Indeterminate Result Error][Occurs when the result of a function is not
+ defined for the values that were passed to it.]]
]
The action undertaken by each error condition is determined by the current
@@ -116,13 +118,23 @@
[table Possible Actions for Internal Evaluation Errors
[[Action] [Behaviour]]
[[throw_on_error][[*Throws `boost::math::evaluation_error`]]]
-[[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::infinity()`.]]
-[[ignore_error][Returns `std::numeric_limits<T>::infinity()`.]]
+[[errno_on_error][Sets `::errno` to `EDOM` and returns the closest approximation found.]]
+[[ignore_error][Returns the closest approximation found.]]
[[user_error][Returns the result of `boost::math::policies::user_evaluation_error`:
[link math_toolkit.policy.pol_tutorial.user_def_err_pol
this function must be defined by the user].]]
]
+[table Possible Actions for Indeterminate Result Errors
+[[Action] [Behaviour]]
+[[throw_on_error][[*Throws `std::domain_error`]]]
+[[errno_on_error][Sets `::errno` to `EDOM` and returns the same value as `ignore_error`.]]
+[[ignore_error][Returns a default result that depends on the function where the error occurred.]]
+[[user_error][Returns the result of `boost::math::policies::user_indeterminate_result_error`:
+ [link math_toolkit.policy.pol_tutorial.user_def_err_pol
+ this function must be defined by the user].]]
+]
+
[heading Rationale]
The flexibility of the current implementation should be reasonably obvious, the
@@ -304,6 +316,23 @@
`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 [#indeterminate_result_error]Indeterminate Result Errors]
+
+When the result of a special function is indeterminate for the value that was
+passed to it, then the function returns the result of:
+
+ boost::math::policies::raise_overflow_error<T>(FunctionName, Message, Val, Default, __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 value for which the result is indeterminate, Default is an
+alternative default result that must be returned for ignore_error and
+errno_on_error policies, and __Policy is the current policy in use for the
+function that was called.
+
+The default policy for this function is `ignore_error`.
+
[heading [#rounding_error]Rounding Errors]
When one of the rounding functions __round, __trunc or __modf is
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-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
@@ -45,6 +45,7 @@
[[Underflow Error][std::underflow_error]]
[[Denorm Error][std::underflow_error]]
[[Evaluation Error][boost::math::evaluation_error]]
+ [[Indeterminate Result Error][std::domain_error]]
]
[h5 errno_on_error]
@@ -60,11 +61,12 @@
[[Underflow Error][ERANGE]]
[[Denorm Error][ERANGE]]
[[Evaluation Error][EDOM]]
+ [[Indeterminate Result Error][EDOM]]
]
[h5 ignore_error]
-Will return a one of the values below depending on the error type (`::errno` is NOT changed)::
+Will return one of the values below depending on the error type (`::errno` is NOT changed)::
[table
[[Error Type][Returned Value]]
[[Domain Error][std::numeric_limits<T>::quiet_NaN()]]
@@ -74,6 +76,7 @@
[[Denorm Error][The denormalised value.]]
[[Evaluation Error][The best guess as to the result: which
may be significantly in error.]]
+ [[Indeterminate Result Error][Depends on the function where the error occurred]]
]
[h5 user_error]
@@ -83,28 +86,31 @@
must be provided by the user:
namespace boost{ namespace math{ namespace policies{
-
+
template <class T>
T user_domain_error(const char* function, const char* message, const T& val);
-
+
template <class T>
T user_pole_error(const char* function, const char* message, const T& val);
-
+
template <class T>
T user_overflow_error(const char* function, const char* message, const T& val);
-
+
template <class T>
T user_underflow_error(const char* function, const char* message, const T& val);
-
+
template <class T>
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);
-
+
+ template <class T>
+ T user_indeterminate_result_error(const char* function, const char* message, const T& val);
+
}}} // namespaces
Note that the strings ['function] and ['message] may contain "%1%" format specifiers
@@ -121,7 +127,7 @@
[h4 Kinds of Error Raised]
-There are five kinds of error reported by this library,
+There are six kinds of error reported by this library,
which are summarised in the following table:
[table
@@ -191,6 +197,14 @@
Defaults to `boost::math::policies::evaluation_error<throw_on_error>`
When the action is ['throw_on_error] then throws `boost::math::evaluation_error`]]
+[[Indeterminate Result Error]
+ [boost::math::policies::indeterminate_result_error<['action]>]
+ [Raised when the result of a function is not defined for the values that
+ were passed to it.
+
+ Defaults to `boost::math::policies::indeterminate_result_error<ignore_error>`
+
+ When the action is ['throw_on_error] then throws `boost::math::evaluation_error`]]
]
[h4 Examples]
@@ -684,7 +698,9 @@
class A8 = default_policy,
class A9 = default_policy,
class A10 = default_policy,
- class A11 = default_policy>
+ class A11 = default_policy,
+ class A12 = default_policy,
+ class A13 = default_policy>
struct policy
{
public:
@@ -695,6 +711,7 @@
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]`` indeterminate_result_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;
@@ -716,7 +733,9 @@
class A8 = default_policy,
class A9 = default_policy,
class A10 = default_policy,
- class A11 = default_policy>
+ class A11 = default_policy,
+ class A12 = default_policy,
+ class A13 = default_policy>
struct normalise
{
typedef ``computed-from-template-arguments`` type;
@@ -767,6 +786,13 @@
`boost::math::policies::evaluation_error<>` with the template argument to
`evaluation_error` one of the `error_policy_type` enumerated values.
+ policy<...>::indeterminate_error_type
+
+Specifies how indeterminate result errors are handled, will be an instance of
+`boost::math::policies::indeterminate_result_error<>` with the template argument
+to `indeterminate_result_error` one of the `error_policy_type` enumerated
+values.
+
policy<...>::precision_type
Specifies the internal precision to use in binary digits (uses zero
@@ -817,7 +843,9 @@
class A8 = default_policy,
class A9 = default_policy,
class A10 = default_policy,
- class A11 = default_policy>
+ class A11 = default_policy,
+ class A12 = default_policy,
+ class A13 = default_policy>
struct normalise
{
typedef ``computed-from-template-arguments`` type;
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-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
@@ -46,6 +46,7 @@
[[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.]]
+[[Indeterminate Result Error][Returns a result that depends on the function where the error occurred.]
[[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
more precision than double.]]
Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/pow.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/pow.qbk (original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/pow.qbk 2008-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
@@ -53,8 +53,8 @@
[h4 Return Type]
-The return type of these functions is computed using the __arg_pomotion_rules
-when T1 and T2 are different types. For example:
+The return type of these functions is computed using the __arg_pomotion_rules.
+For example:
* If T is a `float`, the return type is a `float`.
* If T is a `long double`, the return type is a `long double`.
@@ -66,9 +66,13 @@
[h4 Error Handling]
-In the case where `pow` is called with a null base and a negative exponent,
-an error occurs since this operation is a division by 0 (it equals to 1/0).
-The error raised is an __overflow_error following the
+Two cases of errors can occur when using `pow`:
+
+* In case of null base and negative exponent, an __overflown_error occurs since
+this operation is a division by 0 (it equals to 1/0).
+* In case of null exponent, an indeterminate_result_error occurs since the
+result of a null power is indeterminate.
+Those errors follow the
[@sf_and_dist/html/math_toolkit/main_overview/error_handling.html
general policies of error handling in Boost.Math].
@@ -81,6 +85,15 @@
* `user_error`: Returns the result of `boost::math::policies::user_overflow_error`:
this function must be defined by the user.
+The default indeterminate result error policy is `ignore_error`, which for this
+function returns 1 since it's the most commonly chosen result for a power of 0.
+Here again, other error handling policies can be used:
+
+* `throw_on_error`: Throws `std::domain_error`
+* `errno_on_error`: Sets `::errno` to `EDOM` and returns 1.
+* `user_error`: Returns the result of `boost::math::policies::user_indeterminate_result_error`:
+ this function must be defined by the user.
+
Here is an example of error handling customization where we want to
specify the result that has to be returned in case of error. We will
thus use the `user_error` policy, by passing as second argument an
Modified: sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp
==============================================================================
--- sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp (original)
+++ sandbox/math_toolkit/libs/math/example/policy_eg_8.cpp 2008-06-22 14:03:54 EDT (Sun, 22 Jun 2008)
@@ -39,6 +39,8 @@
T user_denorm_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);
+ template <class T>
+ T user_indeterminate_result_error(const char* function, const char* message, const T& val);
}}} // namespaces
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