error_handling.qbk

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

['"the corresponding mathematical function is not mathematically defined.]]

[:['"Note 2: A mathematical function is mathematically defined
for a given set of argument values if it is explicitly defined
for that set of argument values or
if its limiting value exists and does not depend on the direction of approach."]]

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 [#pole_error]Evaluation at a pole]

When a special function is passed an argument that is at a pole
without a well defined residual value, then the function returns
the result of:

   boost::math::policies::raise_pole_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 of the argument that is at a pole, and __Policy is the 
current policy in use for the function that was called.

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
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 [#overflow_error]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:

   boost::math::policies::raise_overflow_error<T>(FunctionName, Message, __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,
and __Policy is the current policy
in use for the function that was called.

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()`.
In this situation if the type `T` doesn't support infinities,
the maximum value for the type is returned.

[heading [#underflow_error]Numeric Underflow]

If the result of a special function is known to be non-zero, but the
calculated result underflows to zero, then the function returns the result of:

   boost::math::policies::raise_underflow_error<T>(FunctionName, Message, __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,
and __Policy is the current policy
in use for the called function.

The default version of this function returns zero.
But with another policy, like `throw_on_error`, 
throws an `std::underflow_error` C++ exception.  

[heading [#denorm_error]Denormalisation Errors]

If the result of a special function is a denormalised value /z/ then the function
returns the result of:

   boost::math::policies::raise_denorm_error<T>(z, FunctionName, Message, __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,
and __Policy is the current policy
in use for the called function.

The default version of this function returns /z/.
But with another policy, like `throw_on_error` 
throws an `std::underflow_error` C++ exception.

[heading [#evaluation_error]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::policies::raise_evaluation_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 value,
and __Policy is the current policy
in use for the called function.

The default behaviour of this function is to throw a `boost::math::evaluation_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 [#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`: note that this error
type is reserved for situations where the result is mathematically
undefined or indeterminate, but there is none the less a convention for what
the result should be: for example the C99 standard specifies that the result
of 0[super 0] is 1, even though the result is actually mathematically indeterminate.

[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
than their arguments in order to ensure full machine precision in 
the result: for example, a function passed a float argument may evaluate
its result using double precision internally.  Many of the errors listed
above may therefore occur not during evaluation, but when converting 
the result to the narrower result type.  The function:

   template <class T, class __Policy, class U>
   T checked_narrowing_cast(U const& val, const char* function);
   
Is used to perform these conversions, and will call the error handlers
listed above on [link overflow_error overflow], 
[link underflow_error underflow] or [link denorm_error denormalisation].

[endsect][/section:error_handling Error Handling]

[/ 
  Copyright 2006 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).
]