3 <meta http-equiv=
"Content-Type" content=
"text/html; charset=US-ASCII">
4 <title>Error Handling
</title>
5 <link rel=
"stylesheet" href=
"../math.css" type=
"text/css">
6 <meta name=
"generator" content=
"DocBook XSL Stylesheets V1.77.1">
7 <link rel=
"home" href=
"../index.html" title=
"Math Toolkit 2.5.1">
8 <link rel=
"up" href=
"../overview.html" title=
"Chapter 1. Overview">
9 <link rel=
"prev" href=
"result_type.html" title=
"Calculation of the Type of the Result">
10 <link rel=
"next" href=
"compilers_overview.html" title=
"Compilers">
12 <body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF">
13 <table cellpadding=
"2" width=
"100%"><tr>
14 <td valign=
"top"><img alt=
"Boost C++ Libraries" width=
"277" height=
"86" src=
"../../../../../boost.png"></td>
15 <td align=
"center"><a href=
"../../../../../index.html">Home
</a></td>
16 <td align=
"center"><a href=
"../../../../../libs/libraries.htm">Libraries
</a></td>
17 <td align=
"center"><a href=
"http://www.boost.org/users/people.html">People
</a></td>
18 <td align=
"center"><a href=
"http://www.boost.org/users/faq.html">FAQ
</a></td>
19 <td align=
"center"><a href=
"../../../../../more/index.htm">More
</a></td>
22 <div class=
"spirit-nav">
23 <a accesskey=
"p" href=
"result_type.html"><img src=
"../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../overview.html"><img src=
"../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../index.html"><img src=
"../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"compilers_overview.html"><img src=
"../../../../../doc/src/images/next.png" alt=
"Next"></a>
26 <div class=
"titlepage"><div><div><h2 class=
"title" style=
"clear: both">
27 <a name=
"math_toolkit.error_handling"></a><a class=
"link" href=
"error_handling.html" title=
"Error Handling">Error Handling
</a>
28 </h2></div></div></div>
30 <a name=
"math_toolkit.error_handling.h0"></a>
31 <span class=
"phrase"><a name=
"math_toolkit.error_handling.quick_reference"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.quick_reference">Quick
35 Handling of errors by this library is split into two orthogonal parts:
37 <div class=
"itemizedlist"><ul class=
"itemizedlist" style=
"list-style-type: disc; ">
39 What kind of error has been raised?
42 What should be done when the error is raised?
45 <div class=
"warning"><table border=
"0" summary=
"Warning">
47 <td rowspan=
"2" align=
"center" valign=
"top" width=
"25"><img alt=
"[Warning]" src=
"../../../../../doc/src/images/warning.png"></td>
48 <th align=
"left">Warning
</th>
50 <tr><td align=
"left" valign=
"top"><p>
51 The default error actions are to throw an exception with an informative error
52 message. If you do not try to catch the exception, you will not see the message!
56 The kinds of errors that can be raised are:
58 <div class=
"variablelist">
59 <p class=
"title"><b></b></p>
60 <dl class=
"variablelist">
61 <dt><span class=
"term">Domain Error
</span></dt>
63 Occurs when one or more arguments to a function are out of range.
65 <dt><span class=
"term">Pole Error
</span></dt>
67 Occurs when the particular arguments cause the function to be evaluated
68 at a pole with no well defined residual value. For example if
<a class=
"link" href=
"sf_gamma/tgamma.html" title=
"Gamma">tgamma
</a>
69 is evaluated at exactly -
2, the function approaches different limiting
70 values depending upon whether you approach from just above or just below
71 -
2. Hence the function has no well defined value at this point and a
72 Pole Error will be raised.
74 <dt><span class=
"term">Overflow Error
</span></dt>
76 Occurs when the result is either infinite, or too large to represent
77 in the numeric type being returned by the function.
79 <dt><span class=
"term">Underflow Error
</span></dt>
81 Occurs when the result is not zero, but is too small to be represented
82 by any other value in the type being returned by the function.
84 <dt><span class=
"term">Denormalisation Error
</span></dt>
86 Occurs when the returned result would be a denormalised value.
88 <dt><span class=
"term">Rounding Error
</span></dt>
90 Occurs when the argument to one of the rounding functions
<a class=
"link" href=
"rounding/trunc.html" title=
"Truncation Functions">trunc
</a>,
91 <a class=
"link" href=
"rounding/round.html" title=
"Rounding Functions">round
</a> and
<a class=
"link" href=
"rounding/modf.html" title=
"Integer and Fractional Part Splitting (modf)">modf
</a>
92 can not be represented as an integer type, is outside the range of the
95 <dt><span class=
"term">Evaluation Error
</span></dt>
97 Occurs if no method of evaluation is known, or when an internal error
98 occurred that prevented the result from being evaluated: this should
99 never occur, but if it does, then it's likely to be due to an iterative
100 method not converging fast enough.
102 <dt><span class=
"term">Indeterminate Result Error
</span></dt>
104 Occurs when the result of a function is not defined for the values that
110 The action undertaken by each error condition is determined by the current
111 <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> in effect. This can be changed program-wide
112 by setting some configuration macros, or at namespace scope, or at the call
113 site (by specifying a specific policy in the function call).
116 The available actions are:
118 <div class=
"variablelist">
119 <p class=
"title"><b></b></p>
120 <dl class=
"variablelist">
121 <dt><span class=
"term">throw_on_error
</span></dt>
123 Throws the exception most appropriate to the error condition.
125 <dt><span class=
"term">errno_on_error
</span></dt>
127 Sets ::errno to an appropriate value, and then returns the most appropriate
130 <dt><span class=
"term">ignore_error
</span></dt>
132 Ignores the error and simply the returns the most appropriate result.
134 <dt><span class=
"term">user_error
</span></dt>
136 Calls a
<a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">user-supplied
142 The following tables show all the permutations of errors and actions, with
143 the
<span class=
"bold"><strong>default action for each error shown in bold
</strong></span>:
146 <a name=
"math_toolkit.error_handling.possible_actions_for_domain_erro"></a><p class=
"title"><b>Table
 1.1.
 Possible Actions for Domain Errors
</b></p>
147 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Domain Errors">
173 <span class=
"bold"><strong>Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">domain_error
</span></code></strong></span>
185 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
186 to
<code class=
"computeroutput"><span class=
"identifier">EDOM
</span></code> and returns
187 <code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">quiet_NaN
</span><span class=
"special">()
</span></code>
199 Returns
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">quiet_NaN
</span><span class=
"special">()
</span></code>
211 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_domain_error
</span></code>:
212 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
213 must be defined by the user
</a>.
220 <br class=
"table-break"><div class=
"table">
221 <a name=
"math_toolkit.error_handling.possible_actions_for_pole_errors"></a><p class=
"title"><b>Table
 1.2.
 Possible Actions for Pole Errors
</b></p>
222 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Pole Errors">
248 <span class=
"bold"><strong>Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">domain_error
</span></code></strong></span>
260 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
261 to
<code class=
"computeroutput"><span class=
"identifier">EDOM
</span></code> and returns
262 <code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">quiet_NaN
</span><span class=
"special">()
</span></code>
274 Returns
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">quiet_NaN
</span><span class=
"special">()
</span></code>
286 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_pole_error
</span></code>:
287 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
288 must be defined by the user
</a>.
295 <br class=
"table-break"><div class=
"table">
296 <a name=
"math_toolkit.error_handling.possible_actions_for_overflow_er"></a><p class=
"title"><b>Table
 1.3.
 Possible Actions for Overflow Errors
</b></p>
297 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Overflow Errors">
323 <span class=
"bold"><strong>Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">overflow_error
</span></code></strong></span>
335 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
336 to
<code class=
"computeroutput"><span class=
"identifier">ERANGE
</span></code> and returns
337 <code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">infinity
</span><span class=
"special">()
</span></code>
349 Returns
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">infinity
</span><span class=
"special">()
</span></code>
361 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_overflow_error
</span></code>:
362 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
363 must be defined by the user
</a>.
370 <br class=
"table-break"><div class=
"table">
371 <a name=
"math_toolkit.error_handling.possible_actions_for_underflow_e"></a><p class=
"title"><b>Table
 1.4.
 Possible Actions for Underflow Errors
</b></p>
372 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Underflow Errors">
398 Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">underflow_error
</span></code>
410 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
411 to
<code class=
"computeroutput"><span class=
"identifier">ERANGE
</span></code> and returns
424 <span class=
"bold"><strong>Returns
0</strong></span>
436 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_underflow_error
</span></code>:
437 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
438 must be defined by the user
</a>.
445 <br class=
"table-break"><div class=
"table">
446 <a name=
"math_toolkit.error_handling.possible_actions_for_denorm_erro"></a><p class=
"title"><b>Table
 1.5.
 Possible Actions for Denorm Errors
</b></p>
447 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Denorm Errors">
473 Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">underflow_error
</span></code>
485 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
486 to
<code class=
"computeroutput"><span class=
"identifier">ERANGE
</span></code> and returns
487 the denormalised value.
499 <span class=
"bold"><strong>Returns the denormalised value.
</strong></span>
511 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_denorm_error
</span></code>:
512 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
513 must be defined by the user
</a>.
520 <br class=
"table-break"><div class=
"table">
521 <a name=
"math_toolkit.error_handling.possible_actions_for_rounding_er"></a><p class=
"title"><b>Table
 1.6.
 Possible Actions for Rounding Errors
</b></p>
522 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Rounding Errors">
548 Throws
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">rounding_error
</span></code>
560 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
561 to
<code class=
"computeroutput"><span class=
"identifier">ERANGE
</span></code> and returns
562 the largest representable value of the target integer type (or the
563 most negative value if the argument to the function was less than
576 <span class=
"bold"><strong>Returns the largest representable value of
577 the target integer type (or the most negative value if the argument
578 to the function was less than zero).
</strong></span>
590 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_rounding_error
</span></code>:
591 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
592 must be defined by the user
</a>.
599 <br class=
"table-break"><div class=
"table">
600 <a name=
"math_toolkit.error_handling.possible_actions_for_internal_ev"></a><p class=
"title"><b>Table
 1.7.
 Possible Actions for Internal Evaluation Errors
</b></p>
601 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Internal Evaluation Errors">
627 <span class=
"bold"><strong>Throws
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">evaluation_error
</span></code></strong></span>
639 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
640 to
<code class=
"computeroutput"><span class=
"identifier">EDOM
</span></code> and returns
641 the closest approximation found.
653 Returns the closest approximation found.
665 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_evaluation_error
</span></code>:
666 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
667 must be defined by the user
</a>.
674 <br class=
"table-break"><div class=
"table">
675 <a name=
"math_toolkit.error_handling.possible_actions_for_indetermina"></a><p class=
"title"><b>Table
 1.8.
 Possible Actions for Indeterminate Result Errors
</b></p>
676 <div class=
"table-contents"><table class=
"table" summary=
"Possible Actions for Indeterminate Result Errors">
702 Throws
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">domain_error
</span></code>
714 Sets
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>
715 to
<code class=
"computeroutput"><span class=
"identifier">EDOM
</span></code> and returns
716 the same value as
<code class=
"computeroutput"><span class=
"identifier">ignore_error
</span></code>.
728 <span class=
"bold"><strong>Returns a default result that depends on the
729 function where the error occurred.
</strong></span>
741 Returns the result of
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">user_indeterminate_result_error
</span></code>:
742 <a class=
"link" href=
"pol_tutorial/user_def_err_pol.html" title=
"Calling User Defined Error Handlers">this function
743 must be defined by the user
</a>.
750 <br class=
"table-break"><p>
751 All these error conditions are in namespace boost::math::policies, made available,
752 for example, a by namespace declaration using
<code class=
"computeroutput"><span class=
"keyword">namespace
</span>
753 <span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">;
</span></code> or individual using declarations
<code class=
"computeroutput"><span class=
"keyword">using
</span> <span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">overflow_error
</span><span class=
"special">;
</span></code>.
756 <a name=
"math_toolkit.error_handling.h1"></a>
757 <span class=
"phrase"><a name=
"math_toolkit.error_handling.rationale"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.rationale">Rationale
</a>
760 The flexibility of the current implementation should be reasonably obvious:
761 the default behaviours were chosen based on feedback during the formal review
762 of this library. It was felt that:
764 <div class=
"itemizedlist"><ul class=
"itemizedlist" style=
"list-style-type: disc; ">
765 <li class=
"listitem">
766 Genuine errors should be flagged with exceptions rather than following
767 C-compatible behaviour and setting
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>.
769 <li class=
"listitem">
770 Numeric underflow and denormalised results were not considered to be fatal
771 errors in most cases, so it was felt that these should be ignored.
773 <li class=
"listitem">
774 If there is more than one error, only the first detected will be reported
775 in the throw message.
779 <a name=
"math_toolkit.error_handling.h2"></a>
780 <span class=
"phrase"><a name=
"math_toolkit.error_handling.finding_more_information"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.finding_more_information">Finding
784 There are some pre-processor macro defines that can be used to
<a class=
"link" href=
"pol_ref/policy_defaults.html" title=
"Using Macros to Change the Policy Defaults">change
785 the policy defaults
</a>. See also the
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">policy section
</a>.
788 An example is at the Policy tutorial in
<a class=
"link" href=
"pol_tutorial/changing_policy_defaults.html" title=
"Changing the Policy Defaults">Changing
789 the Policy Defaults
</a>.
792 Full source code of this typical example of passing a 'bad' argument (negative
793 degrees of freedom) to Student's t distribution is
<a class=
"link" href=
"stat_tut/weg/error_eg.html" title=
"Error Handling Example">in
794 the error handling example
</a>.
797 The various kind of errors are described in more detail below.
800 <a name=
"math_toolkit.error_handling.h3"></a>
801 <span class=
"phrase"><a name=
"math_toolkit.error_handling.domain_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.domain_error">Domain
805 When a special function is passed an argument that is outside the range of
806 values for which that function is defined, then the function returns the result
809 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_domain_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <span class=
"identifier">Val
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
812 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating-point
813 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
814 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
815 is an error message describing the problem, Val is the value that was out of
816 range, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> is the current policy in use
817 for the function that was called.
820 The default policy behaviour of this function is to throw a std::domain_error
821 C++ exception. But if the
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> is to ignore
822 the error, or set global
<code class=
"computeroutput"><span class=
"special">::
</span><span class=
"identifier">errno
</span></code>,
823 then a NaN will be returned.
826 This behaviour is chosen to assist compatibility with the behaviour of
<span class=
"emphasis"><em>ISO/IEC
827 9899:
1999 Programming languages - C
</em></span> and with the
<a href=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf" target=
"_top">Draft
828 Technical Report on C++ Library Extensions,
2005-
06-
24, section
5.2.1, paragraph
831 <div class=
"blockquote"><blockquote class=
"blockquote"><p>
832 <span class=
"emphasis"><em>"Each of the functions declared above shall return a NaN (Not
833 a Number) if any argument value is a NaN, but it shall not report a domain
834 error. Otherwise, each of the functions declared above shall report a domain
835 error for just those argument values for which:</em></span>
836 </p></blockquote></div>
837 <div class="blockquote
"><blockquote class="blockquote
">
839 <span class="emphasis
"><em>"the function description's Returns clause explicitly specifies
840 a domain, and those arguments fall outside the specified domain; or
</em></span>
843 <span class=
"emphasis"><em>"the corresponding mathematical function value has a non-zero
844 imaginary component; or</em></span>
847 <span class="emphasis
"><em>"the corresponding mathematical function is not mathematically
851 <div class=
"blockquote"><blockquote class=
"blockquote"><p>
852 <span class=
"emphasis"><em>"Note 2: A mathematical function is mathematically defined
853 for a given set of argument values if it is explicitly defined for that set
854 of argument values or if its limiting value exists and does not depend on
855 the direction of approach."</em></span>
856 </p></blockquote></div>
858 Note that in order to support information-rich error messages when throwing
859 exceptions,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> must contain
860 a
<a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> recognised format
861 specifier: the argument
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code>
862 is inserted into the error message according to the specifier used.
865 For example if
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> contains
866 a
"%1%" then it is replaced by the value of
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code>
867 to the full precision of T, where as
"%.3g" would contain the value
868 of
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code> to
3 digits. See the
869 <a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> documentation
873 <a name=
"math_toolkit.error_handling.h4"></a>
874 <span class=
"phrase"><a name=
"math_toolkit.error_handling.pole_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.pole_error">Evaluation
878 When a special function is passed an argument that is at a pole without a well
879 defined residual value, then the function returns the result of:
881 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_pole_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <span class=
"identifier">Val
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
884 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating point
885 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
886 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
887 is an error message describing the problem,
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code>
888 is the value of the argument that is at a pole, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a>
889 is the current policy in use for the function that was called.
892 The default behaviour of this function is to throw a std::domain_error exception.
893 But
<a class=
"link" href=
"pol_ref/error_handling_policies.html" title=
"Error Handling Policies">error handling
894 policies
</a> can be used to change this, for example to
<code class=
"computeroutput"><span class=
"identifier">ignore_error
</span></code>
898 Note that in order to support information-rich error messages when throwing
899 exceptions,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> must contain
900 a
<a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> recognised format
901 specifier: the argument
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
902 is inserted into the error message according to the specifier used.
905 For example if
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> contains
906 a
"%1%" then it is replaced by the value of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
907 to the full precision of T, where as
"%.3g" would contain the value
908 of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code> to
3 digits. See the
909 <a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> documentation
913 <a name=
"math_toolkit.error_handling.h5"></a>
914 <span class=
"phrase"><a name=
"math_toolkit.error_handling.overflow_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.overflow_error">Numeric
918 When the result of a special function is too large to fit in the argument floating-point
919 type, then the function returns the result of:
921 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_overflow_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
924 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating-point
925 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
926 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
927 is an error message describing the problem, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a>
928 is the current policy in use for the function that was called.
931 The default policy for this function is that
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">overflow_error
</span></code>
932 C++ exception is thrown. But if, for example, an
<code class=
"computeroutput"><span class=
"identifier">ignore_error
</span></code>
933 policy is used, then returns
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">numeric_limits
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">infinity
</span><span class=
"special">()
</span></code>.
934 In this situation if the type
<code class=
"computeroutput"><span class=
"identifier">T
</span></code>
935 doesn't support infinities, the maximum value for the type is returned.
938 <a name=
"math_toolkit.error_handling.h6"></a>
939 <span class=
"phrase"><a name=
"math_toolkit.error_handling.underflow_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.underflow_error">Numeric
943 If the result of a special function is known to be non-zero, but the calculated
944 result underflows to zero, then the function returns the result of:
946 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_underflow_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
949 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating point
950 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
951 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
952 is an error message describing the problem, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a>
953 is the current policy in use for the called function.
956 The default version of this function returns zero. But with another policy,
957 like
<code class=
"computeroutput"><span class=
"identifier">throw_on_error
</span></code>, throws
958 an
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">underflow_error
</span></code> C++ exception.
961 <a name=
"math_toolkit.error_handling.h7"></a>
962 <span class=
"phrase"><a name=
"math_toolkit.error_handling.denorm_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.denorm_error">Denormalisation
966 If the result of a special function is a denormalised value
<span class=
"emphasis"><em>z
</em></span>
967 then the function returns the result of:
969 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_denorm_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">z
</span><span class=
"special">,
</span> <span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
972 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating point
973 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
974 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
975 is an error message describing the problem, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a>
976 is the current policy in use for the called function.
979 The default version of this function returns
<span class=
"emphasis"><em>z
</em></span>. But with
980 another policy, like
<code class=
"computeroutput"><span class=
"identifier">throw_on_error
</span></code>
981 throws an
<code class=
"computeroutput"><span class=
"identifier">std
</span><span class=
"special">::
</span><span class=
"identifier">underflow_error
</span></code> C++ exception.
984 <a name=
"math_toolkit.error_handling.h8"></a>
985 <span class=
"phrase"><a name=
"math_toolkit.error_handling.evaluation_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.evaluation_error">Evaluation
989 When a special function calculates a result that is known to be erroneous,
990 or where the result is incalculable then it calls:
992 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_evaluation_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <span class=
"identifier">Val
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
995 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating point
996 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
997 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
998 is an error message describing the problem,
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code>
999 is the erroneous value, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> is the current
1000 policy in use for the called function.
1003 The default behaviour of this function is to throw a
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">evaluation_error
</span></code>.
1006 Note that in order to support information rich error messages when throwing
1007 exceptions,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> must contain
1008 a
<a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> recognised format
1009 specifier: the argument
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
1010 is inserted into the error message according to the specifier used.
1013 For example if
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> contains
1014 a
"%1%" then it is replaced by the value of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
1015 to the full precision of T, where as
"%.3g" would contain the value
1016 of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code> to
3 digits. See the
1017 <a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> documentation
1021 <a name=
"math_toolkit.error_handling.h9"></a>
1022 <span class=
"phrase"><a name=
"math_toolkit.error_handling.indeterminate_result_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.indeterminate_result_error">Indeterminate
1026 When the result of a special function is indeterminate for the value that was
1027 passed to it, then the function returns the result of:
1029 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_overflow_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <span class=
"identifier">Val
</span><span class=
"special">,
</span> <span class=
"identifier">Default
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
1032 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating-point
1033 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
1034 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
1035 is an error message describing the problem, Val is the value for which the
1036 result is indeterminate, Default is an alternative default result that must
1037 be returned for
<code class=
"computeroutput"><span class=
"identifier">ignore_error
</span></code>
1038 and
<code class=
"computeroutput"><span class=
"identifier">errno_on_erro
</span></code> policies,
1039 and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> is the current policy in use for the
1040 function that was called.
1043 The default policy for this function is
<code class=
"computeroutput"><span class=
"identifier">ignore_error
</span></code>:
1044 note that this error type is reserved for situations where the result is mathematically
1045 undefined or indeterminate, but there is none the less a convention for what
1046 the result should be: for example the C99 standard specifies that the result
1047 of
0<sup>0</sup> is
1, even though the result is actually mathematically indeterminate.
1050 <a name=
"math_toolkit.error_handling.h10"></a>
1051 <span class=
"phrase"><a name=
"math_toolkit.error_handling.rounding_error"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.rounding_error">Rounding
1055 When one of the rounding functions
<a class=
"link" href=
"rounding/round.html" title=
"Rounding Functions">round
</a>,
1056 <a class=
"link" href=
"rounding/trunc.html" title=
"Truncation Functions">trunc
</a> or
<a class=
"link" href=
"rounding/modf.html" title=
"Integer and Fractional Part Splitting (modf)">modf
</a>
1057 is called with an argument that has no integer representation, or is too large
1058 to be represented in the result type then the value returned is the result
1061 <pre class=
"programlisting"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">policies
</span><span class=
"special">::
</span><span class=
"identifier">raise_rounding_error
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>(
</span><span class=
"identifier">FunctionName
</span><span class=
"special">,
</span> <span class=
"identifier">Message
</span><span class=
"special">,
</span> <span class=
"identifier">Val
</span><span class=
"special">,
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">);
</span>
1064 Where
<code class=
"computeroutput"><span class=
"identifier">T
</span></code> is the floating point
1065 type passed to the function,
<code class=
"computeroutput"><span class=
"identifier">FunctionName
</span></code>
1066 is the name of the function,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code>
1067 is an error message describing the problem,
<code class=
"computeroutput"><span class=
"identifier">Val
</span></code>
1068 is the erroneous argument, and
<a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a> is the
1069 current policy in use for the called function.
1072 The default behaviour of this function is to throw a
<code class=
"computeroutput"><span class=
"identifier">boost
</span><span class=
"special">::
</span><span class=
"identifier">math
</span><span class=
"special">::
</span><span class=
"identifier">rounding_error
</span></code>.
1075 Note that in order to support information rich error messages when throwing
1076 exceptions,
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> must contain
1077 a
<a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> recognised format
1078 specifier: the argument
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
1079 is inserted into the error message according to the specifier used.
1082 For example if
<code class=
"computeroutput"><span class=
"identifier">Message
</span></code> contains
1083 a
"%1%" then it is replaced by the value of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code>
1084 to the full precision of T, where as
"%.3g" would contain the value
1085 of
<code class=
"computeroutput"><span class=
"identifier">val
</span></code> to
3 digits. See the
1086 <a href=
"../../../../format/index.html" target=
"_top">Boost.Format
</a> documentation
1090 <a name=
"math_toolkit.error_handling.h11"></a>
1091 <span class=
"phrase"><a name=
"math_toolkit.error_handling.checked_narrowing_cast"></a></span><a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.checked_narrowing_cast">Errors
1095 Many special functions evaluate their results at a higher precision than their
1096 arguments in order to ensure full machine precision in the result: for example,
1097 a function passed a float argument may evaluate its result using double precision
1098 internally. Many of the errors listed above may therefore occur not during
1099 evaluation, but when converting the result to the narrower result type. The
1102 <pre class=
"programlisting"><span class=
"keyword">template
</span> <span class=
"special"><</span><span class=
"keyword">class
</span> <span class=
"identifier">T
</span><span class=
"special">,
</span> <span class=
"keyword">class
</span> <a class=
"link" href=
"../policy.html" title=
"Chapter 15. Policies: Controlling Precision, Error Handling etc">Policy
</a><span class=
"special">,
</span> <span class=
"keyword">class
</span> <span class=
"identifier">U
</span><span class=
"special">></span>
1103 <span class=
"identifier">T
</span> <span class=
"identifier">checked_narrowing_cast
</span><span class=
"special">(
</span><span class=
"identifier">U
</span> <span class=
"keyword">const
</span><span class=
"special">&</span> <span class=
"identifier">val
</span><span class=
"special">,
</span> <span class=
"keyword">const
</span> <span class=
"keyword">char
</span><span class=
"special">*
</span> <span class=
"identifier">function
</span><span class=
"special">);
</span>
1106 Is used to perform these conversions, and will call the error handlers listed
1107 above on
<a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.overflow_error">overflow
</a>,
1108 <a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.underflow_error">underflow
</a>
1109 or
<a class=
"link" href=
"error_handling.html#math_toolkit.error_handling.denorm_error">denormalisation
</a>.
1112 <table xmlns:
rev=
"http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width=
"100%"><tr>
1113 <td align=
"left"></td>
1114 <td align=
"right"><div class=
"copyright-footer">Copyright
© 2006-
2010,
2012-
2014 Nikhar Agrawal,
1115 Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
1116 Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R
åde, Gautam Sewani,
1117 Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang
<p>
1118 Distributed under the Boost Software License, Version
1.0. (See accompanying
1119 file LICENSE_1_0.txt or copy at
<a href=
"http://www.boost.org/LICENSE_1_0.txt" target=
"_top">http://www.boost.org/LICENSE_1_0.txt
</a>)
1124 <div class=
"spirit-nav">
1125 <a accesskey=
"p" href=
"result_type.html"><img src=
"../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../overview.html"><img src=
"../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../index.html"><img src=
"../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"compilers_overview.html"><img src=
"../../../../../doc/src/images/next.png" alt=
"Next"></a>