mirror of
https://github.com/boostorg/math.git
synced 2026-02-23 03:42:20 +00:00
193 lines
7.3 KiB
Plaintext
193 lines
7.3 KiB
Plaintext
[section:error_handling Error Handling]
|
|
|
|
[caution __caution ]
|
|
|
|
[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);
|
|
|
|
The functions in this header are designed to be user-replacable error
|
|
handlers that define how errors are handled by the special functions
|
|
in this library. There are also some preprocessor 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.
|
|
|
|
[#domain_error][h4 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::tools::domain_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 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.
|
|
|
|
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.
|
|
|
|
[#pole_error][h4 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::tools::pole_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 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)`.
|
|
|
|
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.
|
|
|
|
[#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:
|
|
|
|
boost::math::tools::overflow_error<T>(FunctionName, Message);
|
|
|
|
Where
|
|
`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.
|
|
|
|
[#underflow_error][h4 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::tools::underflow_error<T>(FunctionName, Message);
|
|
|
|
Where
|
|
`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.
|
|
|
|
[#denorm_error][h4 Denormalisation Errors]
|
|
|
|
If the result of a special function is a denormalised value /z/ then the function
|
|
returns the result of:
|
|
|
|
boost::math::tools::denorm_error<T>(z, FunctionName, Message);
|
|
|
|
Where
|
|
`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.
|
|
|
|
[#logic_error][h4 Internal Logic 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);
|
|
|
|
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 erronious value.
|
|
|
|
The default behaviour of this function is to throw a `std::logic_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.
|
|
|
|
[#checked_narrowing_cast][h4 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 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].
|
|
|
|
Obviously if T and U are the same type or if T is at least as wide as U,
|
|
then no checks are performed.
|
|
|
|
[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).
|
|
]
|
|
|