...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
See error handling documentation for a detailed explanation of the mechanism of handling errors, including the common "bad" arguments to distributions and functions, and how to use Policies to control it.
But, by default, exceptions will be raised, for domain errors, pole errors, numeric overflow, and internal evaluation errors. To avoid the exceptions from getting thrown and instead get an appropriate value returned, usually a NaN (domain errors pole errors or internal errors), or infinity (from overflow), you need to change the policy.
The following example demonstrates the effect of setting the macro BOOST_MATH_DOMAIN_ERROR_POLICY when an invalid argument is encountered. For the purposes of this example, we'll pass a negative degrees of freedom parameter to the student's t distribution.
Since we know that this is a single file program we could just add:
#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
to the top of the source file to change the default policy to one that simply returns a NaN when a domain error occurs. Alternatively we could use:
#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
To ensure the ::errno
is set when a domain error occurs as well as returning a NaN.
This is safe provided the program consists of a single translation unit and we place the define before any #includes. Note that should we add the define after the includes then it will have no effect! A warning such as:
warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition
is a certain sign that it will not have the desired effect.
We'll begin our sample program with the needed includes:
#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error // Boost #include <boost/math/distributions/students_t.hpp> using boost::math::students_t; // Probability of students_t(df, t). // std #include <iostream> using std::cout; using std::endl; #include <stdexcept> using std::exception; #include <cstddef> // using ::errno
Next we'll define the program's main() to call the student's t distribution with an invalid degrees of freedom parameter, the program is set up to handle either an exception or a NaN:
int main() { cout << "Example error handling using Student's t function. " << endl; cout << "BOOST_MATH_DOMAIN_ERROR_POLICY is set to: " << BOOST_STRINGIZE(BOOST_MATH_DOMAIN_ERROR_POLICY) << endl; double degrees_of_freedom = -1; // A bad argument! double t = 10; try { errno = 0; // Clear/reset. students_t dist(degrees_of_freedom); // exception is thrown here if enabled. double p = cdf(dist, t); // Test for error reported by other means: if((boost::math::isnan)(p)) { cout << "cdf returned a NaN!" << endl; if (errno != 0) { // So errno has been set. cout << "errno is set to: " << errno << endl; } } else cout << "Probability of Student's t is " << p << endl; } catch(const std::exception& e) { std::cout << "\n""Message from thrown exception was:\n " << e.what() << std::endl; } return 0; } // int main()
Here's what the program output looks like with a default build (one that does throw exceptions):
Example error handling using Student's t function. BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error Message from thrown exception was: Error in function boost::math::students_t_distribution<double>::students_t_distribution: Degrees of freedom argument is -1, but must be > 0 !
Alternatively let's build with:
#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error
Now the program output is:
Example error handling using Student's t function. BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error cdf returned a NaN!
And finally let's build with:
#define BOOST_MATH_DOMAIN_ERROR_POLICY errno_on_error
Which gives the output show errno:
Example error handling using Student's t function. BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error cdf returned a NaN! errno is set to: 33
Caution | |
---|---|
If throwing of exceptions is enabled (the default) but you do not have try & catch block, then the program will terminate with an uncaught exception and probably abort. Therefore to get the benefit of helpful error messages, enabling all exceptions and using try & catch is recommended for most applications. However, for simplicity, the is not done for most examples. |