error_handling.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[section:error_handling Error Handling]

[def __format [@../../../../format/index.html Boost.Format]]

[heading Quick Reference]

Handling of errors by this library is split into two orthogonal parts:

* What kind of error has been raised?
* What should be done when the error is raised?

The kinds of errors that can be raised are:

[variablelist
[[Domain Error][Occurs when one or more arguments to a function 
  are out of range.]]
[[Pole Error][Occurs when the particular arguments cause the function to be
   evaluated at a pole with no well defined residual value.  For example if
   __tgamma is evaluated at exactly -2, the function approaches different limiting
   values depending upon whether you approach from just above or just below
   -2.  Hence the function has no well defined value at this point and a 
   Pole Error will be raised.]]
[[Overflow Error][Occurs when the result is either infinite, or too large
   to represent in the numeric type being returned by the function.]]
[[Underflow Error][Occurs when the result is not zero, but is too small
   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.]]
[[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
__Policy in effect.  This can be changed program-wide by setting some 
configuration macros, or at namespace scope, or at the call site (by
specifying a specific policy in the function call).

The available actions are:

[variablelist
[[throw_on_error][Throws the exception most appropriate to the error condition.]]
[[errno_on_error][Sets ::errno to an appropriate value, and then returns the most
appropriate result]]
[[ignore_error][Ignores the error and simply the returns the most appropriate result.]]
[[user_error][Calls a 
   [link math_toolkit.policy.pol_tutorial.user_def_err_pol user-supplied error handler].]]
]

The following tables show all the permutations of errors and actions, 
with the default action for each error shown in bold:

[table Possible Actions for Domain Errors
[[Action]         [Behaviour]]
[[throw_on_error][[*Throws `std::domain_error`]]]
[[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]]
[[ignore_error][Returns `std::numeric_limits<T>::quiet_NaN()`]]
[[user_error][Returns the result of `boost::math::policies::user_domain_error`: 
            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
            this function must be defined by the user].]]
]
    
[table Possible Actions for Pole Errors
[[Action]   [Behaviour]]
[[throw_on_error]   [[*Throws `std::domain_error`]]]
[[errno_on_error][Sets `::errno` to `EDOM` and returns `std::numeric_limits<T>::quiet_NaN()`]]
[[ignore_error][Returns `std::numeric_limits<T>::quiet_NaN()`]]
[[user_error][Returns the result of `boost::math::policies::user_pole_error`: 
            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
            this function must be defined by the user].]]
]

[table Possible Actions for Overflow Errors
[[Action]   [Behaviour]]
[[throw_on_error][[*Throws `std::overflow_error`]]]
[[errno_on_error][Sets `::errno` to `ERANGE` and returns `std::numeric_limits<T>::infinity()`]]
[[ignore_error][Returns `std::numeric_limits<T>::infinity()`]]
[[user_error][Returns the result of `boost::math::policies::user_overflow_error`: 
            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
            this function must be defined by the user].]]
]

[table Possible Actions for Underflow Errors
[[Action]   [Behaviour]]
[[throw_on_error][Throws `std::underflow_error`]]
[[errno_on_error][Sets `::errno` to `ERANGE` and returns 0.]]
[[ignore_error][[*Returns 0]]]
[[user_error][Returns the result of `boost::math::policies::user_underflow_error`: 
            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
            this function must be defined by the user].]]
]

[table Possible Actions for Denorm Errors
[[Action]   [Behaviour]]
[[throw_on_error][Throws `std::underflow_error`]]
[[errno_on_error][Sets `::errno` to `ERANGE` and returns the denormalised value.]]
[[ignore_error][[*Returns the denormalised value.]]]
[[user_error][Returns the result of `boost::math::policies::user_denorm_error`: 
            [link math_toolkit.policy.pol_tutorial.user_def_err_pol 
            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`]]]
[[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
default behaviours were chosen based on feedback during the formal review of 
this library.  It was felt that: 

* Genuine errors should be flagged with exceptions
rather than following C-compatible behaviour and setting ::errno.
* Numeric underflow and denormalised results were not considered to be
fatal errors in most cases, so it was felt that these should be ignored.

[heading Finding More Information]

There are some pre-processor macro defines that can be used to
[link math_toolkit.policy.pol_ref.policy_defaults
change the policy defaults].  See also the [link math_toolkit.policy 
policy section].

An example is at the Policy tutorial in
[link math_toolkit.policy.pol_tutorial.changing_policy_defaults 
Changing the Policy Defaults].

Full source code of this typical example of passing a 'bad' argument
(negative degrees of freedom) to Student's t distribution 
is [link math_toolkit.dist.stat_tut.weg.error_eg in the error handling example].

The various kind of errors are described in more detail below.

[heading [#domain_error]Domain Errors]

When a special function is passed an argument that is outside the range
of values for which that function is defined, then the function returns
the result of:

   boost::math::policies::raise_domain_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 value that was out of range, and __Policy is the current policy
in use for the function that was called.

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]
and with the
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Draft Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph 6]:

[:['"Each of the functions declared above shall return a NaN (Not a Number)
if any argument value is a NaN, but it shall not report a domain error.
Otherwise, each of the functions declared above shall report a domain error
for just those argument values for which:]]

[:['"the function description's Returns clause explicitly specifies a domain, and those arguments fall outside the specified domain; or]

['"the corresponding mathematical function value has a non-zero imaginary component; or]