<title>Error Handling</title>
<link rel="stylesheet" href="../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
-<link rel="home" href="../index.html" title="Math Toolkit 2.10.0">
+<link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
<link rel="up" href="../overview.html" title="Chapter 1. Overview">
<link rel="prev" href="result_type.html" title="Calculation of the Type of the Result">
<link rel="next" href="compilers_overview.html" title="Compilers">
</tr>
<tr><td align="left" valign="top"><p>
The default error actions are to throw an exception with an informative error
- message. If you do not try to catch the exception, you will not see the message!
+ message. <span class="red">If you do not try to catch the exception, you
+ will not see the message!</span>
</p></td></tr>
</table></div>
<p>
</div>
<p>
The action undertaken by each error condition is determined by the current
- <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> in effect. This can be changed program-wide
+ <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> 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).
</p>
</h4>
<p>
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
- the policy defaults</a>. See also the <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">policy section</a>.
+ the policy defaults</a>. See also the <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">policy section</a>.
</p>
<p>
An example is at the Policy tutorial in <a class="link" href="pol_tutorial/changing_policy_defaults.html" title="Changing the Policy Defaults">Changing
values for which that function is defined, then the function returns the result
of:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
is an error message describing the problem, Val is the value that was out of
- range, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use
+ range, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use
for the function that was called.
</p>
<p>
The default policy behaviour of this function is to throw a std::domain_error
- C++ exception. But if the <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> is to ignore
+ C++ exception. But if the <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> is to ignore
the error, or set global <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>,
then a NaN will be returned.
</p>
<span class="emphasis"><em>"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:</em></span>
- </p></blockquote></div>
-<div class="blockquote"><blockquote class="blockquote">
-<p>
- <span class="emphasis"><em>"the function description's Returns clause explicitly specifies
- a domain, and those arguments fall outside the specified domain; or</em></span>
- </p>
-<p>
- <span class="emphasis"><em>"the corresponding mathematical function value has a non-zero
- imaginary component; or</em></span>
- </p>
-<p>
- <span class="emphasis"><em>"the corresponding mathematical function is not mathematically
- defined.</em></span>
- </p>
-</blockquote></div>
-<div class="blockquote"><blockquote class="blockquote"><p>
- <span class="emphasis"><em>"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."</em></span>
+ error for just those argument values for which:<br> the function description's
+ Returns clause explicitly specifies a domain, and those arguments fall outside
+ the specified domain; or <br> the corresponding mathematical function value
+ has a non-zero imaginary component; or <br> the corresponding mathematical
+ function is not mathematically defined. <br> 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."</em></span>
</p></blockquote></div>
<p>
Note that in order to support information-rich error messages when throwing
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:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
- is the value of the argument that is at a pole, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a>
+ is the value of the argument that is at a pole, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a>
is the current policy in use for the function that was called.
</p>
<p>
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:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
- is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a>
+ is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a>
is the current policy in use for the function that was called.
</p>
<p>
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:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
- is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a>
+ is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a>
is the current policy in use for the called function.
</p>
<p>
If the result of a special function is a denormalised value <span class="emphasis"><em>z</em></span>
then the function returns the result of:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
- is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a>
+ is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a>
is the current policy in use for the called function.
</p>
<p>
When a special function calculates a result that is known to be erroneous,
or where the result is incalculable then it calls:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
- is the erroneous value, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current
+ is the erroneous value, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current
policy in use for the called function.
</p>
<p>
When the result of a special function is indeterminate for the value that was
passed to it, then the function returns the result of:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
result is indeterminate, Default is an alternative default result that must
be returned for <code class="computeroutput"><span class="identifier">ignore_error</span></code>
and <code class="computeroutput"><span class="identifier">errno_on_erro</span></code> policies,
- and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use for the
+ and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use for the
function that was called.
</p>
<p>
to be represented in the result type then the value returned is the result
of a call to:
</p>
-<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 19. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
+<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 20. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
</pre>
<p>
Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
- is the erroneous argument, and <a class="link" href="../policy.html" title="Chapter 19. Policies: Controlling Precision, Error Handling etc">Policy</a> is the
+ is the erroneous argument, and <a class="link" href="../policy.html" title="Chapter 20. Policies: Controlling Precision, Error Handling etc">Policy</a> is the
current policy in use for the called function.
</p>
<p>
evaluation, but when converting the result to the narrower result type. The
function:
</p>
-<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 19. 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>
+<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 20. 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>
<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>
</pre>
<p>
projects / platform / upstream / boost.git / blobdiff