libs/math/doc/html/math_toolkit/error_handling.html

   1 <html>
   2 <head>
   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.79.1">
   7 <link rel="home" href="../index.html" title="Math Toolkit 2.11.0">
   8 <link rel="up" href="../overview.html" title="Chapter&#160;1.&#160;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">
  11 </head>
  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>
  20 </tr></table>
  21 <hr>
  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>
  24 </div>
  25 <div class="section">
  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>
  29 <h4>
  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
  32       Reference</a>
  33     </h4>
  34 <p>
  35       Handling of errors by this library is split into two orthogonal parts:
  36     </p>
  37 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  38 <li class="listitem">
  39           What kind of error has been raised?
  40         </li>
  41 <li class="listitem">
  42           What should be done when the error is raised?
  43         </li>
  44 </ul></div>
  45 <div class="warning"><table border="0" summary="Warning">
  46 <tr>
  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>
  49 </tr>
  50 <tr><td align="left" valign="top"><p>
  51         The default error actions are to throw an exception with an informative error
  52         message. <span class="red">If you do not try to catch the exception, you
  53         will not see the message!</span>
  54       </p></td></tr>
  55 </table></div>
  56 <p>
  57       The kinds of errors that can be raised are:
  58     </p>
  59 <div class="variablelist">
  60 <p class="title"><b></b></p>
  61 <dl class="variablelist">
  62 <dt><span class="term">Domain Error</span></dt>
  63 <dd><p>
  64             Occurs when one or more arguments to a function are out of range.
  65           </p></dd>
  66 <dt><span class="term">Pole Error</span></dt>
  67 <dd><p>
  68             Occurs when the particular arguments cause the function to be evaluated
  69             at a pole with no well defined residual value. For example if <a class="link" href="sf_gamma/tgamma.html" title="Gamma">tgamma</a>
  70             is evaluated at exactly -2, the function approaches different limiting
  71             values depending upon whether you approach from just above or just below
  72             -2. Hence the function has no well defined value at this point and a
  73             Pole Error will be raised.
  74           </p></dd>
  75 <dt><span class="term">Overflow Error</span></dt>
  76 <dd><p>
  77             Occurs when the result is either infinite, or too large to represent
  78             in the numeric type being returned by the function.
  79           </p></dd>
  80 <dt><span class="term">Underflow Error</span></dt>
  81 <dd><p>
  82             Occurs when the result is not zero, but is too small to be represented
  83             by any other value in the type being returned by the function.
  84           </p></dd>
  85 <dt><span class="term">Denormalisation Error</span></dt>
  86 <dd><p>
  87             Occurs when the returned result would be a denormalised value.
  88           </p></dd>
  89 <dt><span class="term">Rounding Error</span></dt>
  90 <dd><p>
  91             Occurs when the argument to one of the rounding functions <a class="link" href="rounding/trunc.html" title="Truncation Functions">trunc</a>,
  92             <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>
  93             can not be represented as an integer type, is outside the range of the
  94             result type.
  95           </p></dd>
  96 <dt><span class="term">Evaluation Error</span></dt>
  97 <dd><p>
  98             Occurs if no method of evaluation is known, or when an internal error
  99             occurred that prevented the result from being evaluated: this should
 100             never occur, but if it does, then it's likely to be due to an iterative
 101             method not converging fast enough.
 102           </p></dd>
 103 <dt><span class="term">Indeterminate Result Error</span></dt>
 104 <dd><p>
 105             Occurs when the result of a function is not defined for the values that
 106             were passed to it.
 107           </p></dd>
 108 </dl>
 109 </div>
 110 <p>
 111       The action undertaken by each error condition is determined by the current
 112       <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> in effect. This can be changed program-wide
 113       by setting some configuration macros, or at namespace scope, or at the call
 114       site (by specifying a specific policy in the function call).
 115     </p>
 116 <p>
 117       The available actions are:
 118     </p>
 119 <div class="variablelist">
 120 <p class="title"><b></b></p>
 121 <dl class="variablelist">
 122 <dt><span class="term">throw_on_error</span></dt>
 123 <dd><p>
 124             Throws the exception most appropriate to the error condition.
 125           </p></dd>
 126 <dt><span class="term">errno_on_error</span></dt>
 127 <dd><p>
 128             Sets ::errno to an appropriate value, and then returns the most appropriate
 129             result
 130           </p></dd>
 131 <dt><span class="term">ignore_error</span></dt>
 132 <dd><p>
 133             Ignores the error and simply the returns the most appropriate result.
 134           </p></dd>
 135 <dt><span class="term">user_error</span></dt>
 136 <dd><p>
 137             Calls a <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user-supplied
 138             error handler</a>.
 139           </p></dd>
 140 </dl>
 141 </div>
 142 <p>
 143       The following tables show all the permutations of errors and actions, with
 144       the <span class="bold"><strong>default action for each error shown in bold</strong></span>:
 145     </p>
 146 <div class="table">
 147 <a name="math_toolkit.error_handling.possible_actions_for_domain_erro"></a><p class="title"><b>Table&#160;1.1.&#160;Possible Actions for Domain Errors</b></p>
 148 <div class="table-contents"><table class="table" summary="Possible Actions for Domain Errors">
 149 <colgroup>
 150 <col>
 151 <col>
 152 </colgroup>
 153 <thead><tr>
 154 <th>
 155               <p>
 156                 Action
 157               </p>
 158             </th>
 159 <th>
 160               <p>
 161                 Behaviour
 162               </p>
 163             </th>
 164 </tr></thead>
 165 <tbody>
 166 <tr>
 167 <td>
 168               <p>
 169                 throw_on_error
 170               </p>
 171             </td>
 172 <td>
 173               <p>
 174                 <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>
 175               </p>
 176             </td>
 177 </tr>
 178 <tr>
 179 <td>
 180               <p>
 181                 errno_on_error
 182               </p>
 183             </td>
 184 <td>
 185               <p>
 186                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 187                 to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
 188                 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 189               </p>
 190             </td>
 191 </tr>
 192 <tr>
 193 <td>
 194               <p>
 195                 ignore_error
 196               </p>
 197             </td>
 198 <td>
 199               <p>
 200                 Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 201               </p>
 202             </td>
 203 </tr>
 204 <tr>
 205 <td>
 206               <p>
 207                 user_error
 208               </p>
 209             </td>
 210 <td>
 211               <p>
 212                 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>:
 213                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 214                 must be defined by the user</a>.
 215               </p>
 216             </td>
 217 </tr>
 218 </tbody>
 219 </table></div>
 220 </div>
 221 <br class="table-break"><div class="table">
 222 <a name="math_toolkit.error_handling.possible_actions_for_pole_errors"></a><p class="title"><b>Table&#160;1.2.&#160;Possible Actions for Pole Errors</b></p>
 223 <div class="table-contents"><table class="table" summary="Possible Actions for Pole Errors">
 224 <colgroup>
 225 <col>
 226 <col>
 227 </colgroup>
 228 <thead><tr>
 229 <th>
 230               <p>
 231                 Action
 232               </p>
 233             </th>
 234 <th>
 235               <p>
 236                 Behaviour
 237               </p>
 238             </th>
 239 </tr></thead>
 240 <tbody>
 241 <tr>
 242 <td>
 243               <p>
 244                 throw_on_error
 245               </p>
 246             </td>
 247 <td>
 248               <p>
 249                 <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>
 250               </p>
 251             </td>
 252 </tr>
 253 <tr>
 254 <td>
 255               <p>
 256                 errno_on_error
 257               </p>
 258             </td>
 259 <td>
 260               <p>
 261                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 262                 to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
 263                 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 264               </p>
 265             </td>
 266 </tr>
 267 <tr>
 268 <td>
 269               <p>
 270                 ignore_error
 271               </p>
 272             </td>
 273 <td>
 274               <p>
 275                 Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 276               </p>
 277             </td>
 278 </tr>
 279 <tr>
 280 <td>
 281               <p>
 282                 user_error
 283               </p>
 284             </td>
 285 <td>
 286               <p>
 287                 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>:
 288                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 289                 must be defined by the user</a>.
 290               </p>
 291             </td>
 292 </tr>
 293 </tbody>
 294 </table></div>
 295 </div>
 296 <br class="table-break"><div class="table">
 297 <a name="math_toolkit.error_handling.possible_actions_for_overflow_er"></a><p class="title"><b>Table&#160;1.3.&#160;Possible Actions for Overflow Errors</b></p>
 298 <div class="table-contents"><table class="table" summary="Possible Actions for Overflow Errors">
 299 <colgroup>
 300 <col>
 301 <col>
 302 </colgroup>
 303 <thead><tr>
 304 <th>
 305               <p>
 306                 Action
 307               </p>
 308             </th>
 309 <th>
 310               <p>
 311                 Behaviour
 312               </p>
 313             </th>
 314 </tr></thead>
 315 <tbody>
 316 <tr>
 317 <td>
 318               <p>
 319                 throw_on_error
 320               </p>
 321             </td>
 322 <td>
 323               <p>
 324                 <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>
 325               </p>
 326             </td>
 327 </tr>
 328 <tr>
 329 <td>
 330               <p>
 331                 errno_on_error
 332               </p>
 333             </td>
 334 <td>
 335               <p>
 336                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 337                 to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
 338                 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>
 339               </p>
 340             </td>
 341 </tr>
 342 <tr>
 343 <td>
 344               <p>
 345                 ignore_error
 346               </p>
 347             </td>
 348 <td>
 349               <p>
 350                 Returns <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>
 351               </p>
 352             </td>
 353 </tr>
 354 <tr>
 355 <td>
 356               <p>
 357                 user_error
 358               </p>
 359             </td>
 360 <td>
 361               <p>
 362                 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>:
 363                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 364                 must be defined by the user</a>.
 365               </p>
 366             </td>
 367 </tr>
 368 </tbody>
 369 </table></div>
 370 </div>
 371 <br class="table-break"><div class="table">
 372 <a name="math_toolkit.error_handling.possible_actions_for_underflow_e"></a><p class="title"><b>Table&#160;1.4.&#160;Possible Actions for Underflow Errors</b></p>
 373 <div class="table-contents"><table class="table" summary="Possible Actions for Underflow Errors">
 374 <colgroup>
 375 <col>
 376 <col>
 377 </colgroup>
 378 <thead><tr>
 379 <th>
 380               <p>
 381                 Action
 382               </p>
 383             </th>
 384 <th>
 385               <p>
 386                 Behaviour
 387               </p>
 388             </th>
 389 </tr></thead>
 390 <tbody>
 391 <tr>
 392 <td>
 393               <p>
 394                 throw_on_error
 395               </p>
 396             </td>
 397 <td>
 398               <p>
 399                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
 400               </p>
 401             </td>
 402 </tr>
 403 <tr>
 404 <td>
 405               <p>
 406                 errno_on_error
 407               </p>
 408             </td>
 409 <td>
 410               <p>
 411                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 412                 to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
 413                 0.
 414               </p>
 415             </td>
 416 </tr>
 417 <tr>
 418 <td>
 419               <p>
 420                 ignore_error
 421               </p>
 422             </td>
 423 <td>
 424               <p>
 425                 <span class="bold"><strong>Returns 0</strong></span>
 426               </p>
 427             </td>
 428 </tr>
 429 <tr>
 430 <td>
 431               <p>
 432                 user_error
 433               </p>
 434             </td>
 435 <td>
 436               <p>
 437                 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>:
 438                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 439                 must be defined by the user</a>.
 440               </p>
 441             </td>
 442 </tr>
 443 </tbody>
 444 </table></div>
 445 </div>
 446 <br class="table-break"><div class="table">
 447 <a name="math_toolkit.error_handling.possible_actions_for_denorm_erro"></a><p class="title"><b>Table&#160;1.5.&#160;Possible Actions for Denorm Errors</b></p>
 448 <div class="table-contents"><table class="table" summary="Possible Actions for Denorm Errors">
 449 <colgroup>
 450 <col>
 451 <col>
 452 </colgroup>
 453 <thead><tr>
 454 <th>
 455               <p>
 456                 Action
 457               </p>
 458             </th>
 459 <th>
 460               <p>
 461                 Behaviour
 462               </p>
 463             </th>
 464 </tr></thead>
 465 <tbody>
 466 <tr>
 467 <td>
 468               <p>
 469                 throw_on_error
 470               </p>
 471             </td>
 472 <td>
 473               <p>
 474                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
 475               </p>
 476             </td>
 477 </tr>
 478 <tr>
 479 <td>
 480               <p>
 481                 errno_on_error
 482               </p>
 483             </td>
 484 <td>
 485               <p>
 486                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 487                 to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
 488                 the denormalised value.
 489               </p>
 490             </td>
 491 </tr>
 492 <tr>
 493 <td>
 494               <p>
 495                 ignore_error
 496               </p>
 497             </td>
 498 <td>
 499               <p>
 500                 <span class="bold"><strong>Returns the denormalised value.</strong></span>
 501               </p>
 502             </td>
 503 </tr>
 504 <tr>
 505 <td>
 506               <p>
 507                 user_error
 508               </p>
 509             </td>
 510 <td>
 511               <p>
 512                 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>:
 513                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 514                 must be defined by the user</a>.
 515               </p>
 516             </td>
 517 </tr>
 518 </tbody>
 519 </table></div>
 520 </div>
 521 <br class="table-break"><div class="table">
 522 <a name="math_toolkit.error_handling.possible_actions_for_rounding_er"></a><p class="title"><b>Table&#160;1.6.&#160;Possible Actions for Rounding Errors</b></p>
 523 <div class="table-contents"><table class="table" summary="Possible Actions for Rounding Errors">
 524 <colgroup>
 525 <col>
 526 <col>
 527 </colgroup>
 528 <thead><tr>
 529 <th>
 530               <p>
 531                 Action
 532               </p>
 533             </th>
 534 <th>
 535               <p>
 536                 Behaviour
 537               </p>
 538             </th>
 539 </tr></thead>
 540 <tbody>
 541 <tr>
 542 <td>
 543               <p>
 544                 throw_on_error
 545               </p>
 546             </td>
 547 <td>
 548               <p>
 549                 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>
 550               </p>
 551             </td>
 552 </tr>
 553 <tr>
 554 <td>
 555               <p>
 556                 errno_on_error
 557               </p>
 558             </td>
 559 <td>
 560               <p>
 561                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 562                 to <code class="computeroutput"><span class="identifier">ERANGE</span></code> and returns
 563                 the largest representable value of the target integer type (or the
 564                 most negative value if the argument to the function was less than
 565                 zero).
 566               </p>
 567             </td>
 568 </tr>
 569 <tr>
 570 <td>
 571               <p>
 572                 ignore_error
 573               </p>
 574             </td>
 575 <td>
 576               <p>
 577                 <span class="bold"><strong>Returns the largest representable value of
 578                 the target integer type (or the most negative value if the argument
 579                 to the function was less than zero).</strong></span>
 580               </p>
 581             </td>
 582 </tr>
 583 <tr>
 584 <td>
 585               <p>
 586                 user_error
 587               </p>
 588             </td>
 589 <td>
 590               <p>
 591                 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>:
 592                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 593                 must be defined by the user</a>.
 594               </p>
 595             </td>
 596 </tr>
 597 </tbody>
 598 </table></div>
 599 </div>
 600 <br class="table-break"><div class="table">
 601 <a name="math_toolkit.error_handling.possible_actions_for_internal_ev"></a><p class="title"><b>Table&#160;1.7.&#160;Possible Actions for Internal Evaluation Errors</b></p>
 602 <div class="table-contents"><table class="table" summary="Possible Actions for Internal Evaluation Errors">
 603 <colgroup>
 604 <col>
 605 <col>
 606 </colgroup>
 607 <thead><tr>
 608 <th>
 609               <p>
 610                 Action
 611               </p>
 612             </th>
 613 <th>
 614               <p>
 615                 Behaviour
 616               </p>
 617             </th>
 618 </tr></thead>
 619 <tbody>
 620 <tr>
 621 <td>
 622               <p>
 623                 throw_on_error
 624               </p>
 625             </td>
 626 <td>
 627               <p>
 628                 <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>
 629               </p>
 630             </td>
 631 </tr>
 632 <tr>
 633 <td>
 634               <p>
 635                 errno_on_error
 636               </p>
 637             </td>
 638 <td>
 639               <p>
 640                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 641                 to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
 642                 the closest approximation found.
 643               </p>
 644             </td>
 645 </tr>
 646 <tr>
 647 <td>
 648               <p>
 649                 ignore_error
 650               </p>
 651             </td>
 652 <td>
 653               <p>
 654                 Returns the closest approximation found.
 655               </p>
 656             </td>
 657 </tr>
 658 <tr>
 659 <td>
 660               <p>
 661                 user_error
 662               </p>
 663             </td>
 664 <td>
 665               <p>
 666                 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>:
 667                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 668                 must be defined by the user</a>.
 669               </p>
 670             </td>
 671 </tr>
 672 </tbody>
 673 </table></div>
 674 </div>
 675 <br class="table-break"><div class="table">
 676 <a name="math_toolkit.error_handling.possible_actions_for_indetermina"></a><p class="title"><b>Table&#160;1.8.&#160;Possible Actions for Indeterminate Result Errors</b></p>
 677 <div class="table-contents"><table class="table" summary="Possible Actions for Indeterminate Result Errors">
 678 <colgroup>
 679 <col>
 680 <col>
 681 </colgroup>
 682 <thead><tr>
 683 <th>
 684               <p>
 685                 Action
 686               </p>
 687             </th>
 688 <th>
 689               <p>
 690                 Behaviour
 691               </p>
 692             </th>
 693 </tr></thead>
 694 <tbody>
 695 <tr>
 696 <td>
 697               <p>
 698                 throw_on_error
 699               </p>
 700             </td>
 701 <td>
 702               <p>
 703                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
 704               </p>
 705             </td>
 706 </tr>
 707 <tr>
 708 <td>
 709               <p>
 710                 errno_on_error
 711               </p>
 712             </td>
 713 <td>
 714               <p>
 715                 Sets <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
 716                 to <code class="computeroutput"><span class="identifier">EDOM</span></code> and returns
 717                 the same value as <code class="computeroutput"><span class="identifier">ignore_error</span></code>.
 718               </p>
 719             </td>
 720 </tr>
 721 <tr>
 722 <td>
 723               <p>
 724                 ignore_error
 725               </p>
 726             </td>
 727 <td>
 728               <p>
 729                 <span class="bold"><strong>Returns a default result that depends on the
 730                 function where the error occurred.</strong></span>
 731               </p>
 732             </td>
 733 </tr>
 734 <tr>
 735 <td>
 736               <p>
 737                 user_error
 738               </p>
 739             </td>
 740 <td>
 741               <p>
 742                 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>:
 743                 <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">this function
 744                 must be defined by the user</a>.
 745               </p>
 746             </td>
 747 </tr>
 748 </tbody>
 749 </table></div>
 750 </div>
 751 <br class="table-break"><p>
 752       All these error conditions are in namespace boost::math::policies, made available,
 753       for example, a by namespace declaration using <code class="computeroutput"><span class="keyword">namespace</span>
 754       <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>.
 755     </p>
 756 <h4>
 757 <a name="math_toolkit.error_handling.h1"></a>
 758       <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>
 759     </h4>
 760 <p>
 761       The flexibility of the current implementation should be reasonably obvious:
 762       the default behaviours were chosen based on feedback during the formal review
 763       of this library. It was felt that:
 764     </p>
 765 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 766 <li class="listitem">
 767           Genuine errors should be flagged with exceptions rather than following
 768           C-compatible behaviour and setting <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>.
 769         </li>
 770 <li class="listitem">
 771           Numeric underflow and denormalised results were not considered to be fatal
 772           errors in most cases, so it was felt that these should be ignored.
 773         </li>
 774 <li class="listitem">
 775           If there is more than one error, only the first detected will be reported
 776           in the throw message.
 777         </li>
 778 </ul></div>
 779 <h4>
 780 <a name="math_toolkit.error_handling.h2"></a>
 781       <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
 782       More Information</a>
 783     </h4>
 784 <p>
 785       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
 786       the policy defaults</a>. See also the <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">policy section</a>.
 787     </p>
 788 <p>
 789       An example is at the Policy tutorial in <a class="link" href="pol_tutorial/changing_policy_defaults.html" title="Changing the Policy Defaults">Changing
 790       the Policy Defaults</a>.
 791     </p>
 792 <p>
 793       Full source code of this typical example of passing a 'bad' argument (negative
 794       degrees of freedom) to Student's t distribution is <a class="link" href="stat_tut/weg/error_eg.html" title="Error Handling Example">in
 795       the error handling example</a>.
 796     </p>
 797 <p>
 798       The various kind of errors are described in more detail below.
 799     </p>
 800 <h4>
 801 <a name="math_toolkit.error_handling.h3"></a>
 802       <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
 803       Errors</a>
 804     </h4>
 805 <p>
 806       When a special function is passed an argument that is outside the range of
 807       values for which that function is defined, then the function returns the result
 808       of:
 809     </p>
 810 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 811 </pre>
 812 <p>
 813       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
 814       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 815       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 816       is an error message describing the problem, Val is the value that was out of
 817       range, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use
 818       for the function that was called.
 819     </p>
 820 <p>
 821       The default policy behaviour of this function is to throw a std::domain_error
 822       C++ exception. But if the <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is to ignore
 823       the error, or set global <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>,
 824       then a NaN will be returned.
 825     </p>
 826 <p>
 827       This behaviour is chosen to assist compatibility with the behaviour of <span class="emphasis"><em>ISO/IEC
 828       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
 829       Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph
 830       6</a>:
 831     </p>
 832 <div class="blockquote"><blockquote class="blockquote"><p>
 833         <span class="emphasis"><em>"Each of the functions declared above shall return a NaN (Not
 834         a Number) if any argument value is a NaN, but it shall not report a domain
 835         error. Otherwise, each of the functions declared above shall report a domain
 836         error for just those argument values for which:<br> the function description's
 837         Returns clause explicitly specifies a domain, and those arguments fall outside
 838         the specified domain; or <br> the corresponding mathematical function value
 839         has a non-zero imaginary component; or <br> the corresponding mathematical
 840         function is not mathematically defined. <br> Note 2: A mathematical function
 841         is mathematically defined for a given set of argument values if it is explicitly
 842         defined for that set of argument values or if its limiting value exists and
 843         does not depend on the direction of approach."</em></span>
 844       </p></blockquote></div>
 845 <p>
 846       Note that in order to support information-rich error messages when throwing
 847       exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must contain
 848       a <a href="../../../../format/index.html" target="_top">Boost.Format</a> recognised format
 849       specifier: the argument <code class="computeroutput"><span class="identifier">Val</span></code>
 850       is inserted into the error message according to the specifier used.
 851     </p>
 852 <p>
 853       For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
 854       a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">Val</span></code>
 855       to the full precision of T, where as "%.3g" would contain the value
 856       of <code class="computeroutput"><span class="identifier">Val</span></code> to 3 digits. See the
 857       <a href="../../../../format/index.html" target="_top">Boost.Format</a> documentation
 858       for more details.
 859     </p>
 860 <h4>
 861 <a name="math_toolkit.error_handling.h4"></a>
 862       <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
 863       at a pole</a>
 864     </h4>
 865 <p>
 866       When a special function is passed an argument that is at a pole without a well
 867       defined residual value, then the function returns the result of:
 868     </p>
 869 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 870 </pre>
 871 <p>
 872       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
 873       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 874       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 875       is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
 876       is the value of the argument that is at a pole, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 877       is the current policy in use for the function that was called.
 878     </p>
 879 <p>
 880       The default behaviour of this function is to throw a std::domain_error exception.
 881       But <a class="link" href="pol_ref/error_handling_policies.html" title="Error Handling Policies">error handling
 882       policies</a> can be used to change this, for example to <code class="computeroutput"><span class="identifier">ignore_error</span></code>
 883       and return NaN.
 884     </p>
 885 <p>
 886       Note that in order to support information-rich error messages when throwing
 887       exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must contain
 888       a <a href="../../../../format/index.html" target="_top">Boost.Format</a> recognised format
 889       specifier: the argument <code class="computeroutput"><span class="identifier">val</span></code>
 890       is inserted into the error message according to the specifier used.
 891     </p>
 892 <p>
 893       For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
 894       a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">val</span></code>
 895       to the full precision of T, where as "%.3g" would contain the value
 896       of <code class="computeroutput"><span class="identifier">val</span></code> to 3 digits. See the
 897       <a href="../../../../format/index.html" target="_top">Boost.Format</a> documentation
 898       for more details.
 899     </p>
 900 <h4>
 901 <a name="math_toolkit.error_handling.h5"></a>
 902       <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
 903       Overflow</a>
 904     </h4>
 905 <p>
 906       When the result of a special function is too large to fit in the argument floating-point
 907       type, then the function returns the result of:
 908     </p>
 909 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 910 </pre>
 911 <p>
 912       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
 913       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 914       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 915       is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 916       is the current policy in use for the function that was called.
 917     </p>
 918 <p>
 919       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>
 920       C++ exception is thrown. But if, for example, an <code class="computeroutput"><span class="identifier">ignore_error</span></code>
 921       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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>.
 922       In this situation if the type <code class="computeroutput"><span class="identifier">T</span></code>
 923       doesn't support infinities, the maximum value for the type is returned.
 924     </p>
 925 <h4>
 926 <a name="math_toolkit.error_handling.h6"></a>
 927       <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
 928       Underflow</a>
 929     </h4>
 930 <p>
 931       If the result of a special function is known to be non-zero, but the calculated
 932       result underflows to zero, then the function returns the result of:
 933     </p>
 934 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 935 </pre>
 936 <p>
 937       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
 938       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 939       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 940       is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 941       is the current policy in use for the called function.
 942     </p>
 943 <p>
 944       The default version of this function returns zero. But with another policy,
 945       like <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, throws
 946       an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code> C++ exception.
 947     </p>
 948 <h4>
 949 <a name="math_toolkit.error_handling.h7"></a>
 950       <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
 951       Errors</a>
 952     </h4>
 953 <p>
 954       If the result of a special function is a denormalised value <span class="emphasis"><em>z</em></span>
 955       then the function returns the result of:
 956     </p>
 957 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 958 </pre>
 959 <p>
 960       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
 961       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 962       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 963       is an error message describing the problem, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 964       is the current policy in use for the called function.
 965     </p>
 966 <p>
 967       The default version of this function returns <span class="emphasis"><em>z</em></span>. But with
 968       another policy, like <code class="computeroutput"><span class="identifier">throw_on_error</span></code>
 969       throws an <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code> C++ exception.
 970     </p>
 971 <h4>
 972 <a name="math_toolkit.error_handling.h8"></a>
 973       <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
 974       Errors</a>
 975     </h4>
 976 <p>
 977       When a special function calculates a result that is known to be erroneous,
 978       or where the result is incalculable then it calls:
 979     </p>
 980 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 981 </pre>
 982 <p>
 983       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
 984       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
 985       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
 986       is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
 987       is the erroneous value, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current
 988       policy in use for the called function.
 989     </p>
 990 <p>
 991       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>.
 992     </p>
 993 <p>
 994       Note that in order to support information rich error messages when throwing
 995       exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must contain
 996       a <a href="../../../../format/index.html" target="_top">Boost.Format</a> recognised format
 997       specifier: the argument <code class="computeroutput"><span class="identifier">val</span></code>
 998       is inserted into the error message according to the specifier used.
 999     </p>
1000 <p>
1001       For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
1002       a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">val</span></code>
1003       to the full precision of T, where as "%.3g" would contain the value
1004       of <code class="computeroutput"><span class="identifier">val</span></code> to 3 digits. See the
1005       <a href="../../../../format/index.html" target="_top">Boost.Format</a> documentation
1006       for more details.
1007     </p>
1008 <h4>
1009 <a name="math_toolkit.error_handling.h9"></a>
1010       <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
1011       Result Errors</a>
1012     </h4>
1013 <p>
1014       When the result of a special function is indeterminate for the value that was
1015       passed to it, then the function returns the result of:
1016     </p>
1017 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
1018 </pre>
1019 <p>
1020       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating-point
1021       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
1022       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
1023       is an error message describing the problem, Val is the value for which the
1024       result is indeterminate, Default is an alternative default result that must
1025       be returned for <code class="computeroutput"><span class="identifier">ignore_error</span></code>
1026       and <code class="computeroutput"><span class="identifier">errno_on_erro</span></code> policies,
1027       and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use for the
1028       function that was called.
1029     </p>
1030 <p>
1031       The default policy for this function is <code class="computeroutput"><span class="identifier">ignore_error</span></code>:
1032       note that this error type is reserved for situations where the result is mathematically
1033       undefined or indeterminate, but there is none the less a convention for what
1034       the result should be: for example the C99 standard specifies that the result
1035       of 0<sup>0</sup> is 1, even though the result is actually mathematically indeterminate.
1036     </p>
1037 <h4>
1038 <a name="math_toolkit.error_handling.h10"></a>
1039       <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
1040       Errors</a>
1041     </h4>
1042 <p>
1043       When one of the rounding functions <a class="link" href="rounding/round.html" title="Rounding Functions">round</a>,
1044       <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>
1045       is called with an argument that has no integer representation, or is too large
1046       to be represented in the result type then the value returned is the result
1047       of a call to:
1048     </p>
1049 <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">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
1050 </pre>
1051 <p>
1052       Where <code class="computeroutput"><span class="identifier">T</span></code> is the floating point
1053       type passed to the function, <code class="computeroutput"><span class="identifier">FunctionName</span></code>
1054       is the name of the function, <code class="computeroutput"><span class="identifier">Message</span></code>
1055       is an error message describing the problem, <code class="computeroutput"><span class="identifier">Val</span></code>
1056       is the erroneous argument, and <a class="link" href="../policy.html" title="Chapter&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the
1057       current policy in use for the called function.
1058     </p>
1059 <p>
1060       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>.
1061     </p>
1062 <p>
1063       Note that in order to support information rich error messages when throwing
1064       exceptions, <code class="computeroutput"><span class="identifier">Message</span></code> must contain
1065       a <a href="../../../../format/index.html" target="_top">Boost.Format</a> recognised format
1066       specifier: the argument <code class="computeroutput"><span class="identifier">val</span></code>
1067       is inserted into the error message according to the specifier used.
1068     </p>
1069 <p>
1070       For example if <code class="computeroutput"><span class="identifier">Message</span></code> contains
1071       a "%1%" then it is replaced by the value of <code class="computeroutput"><span class="identifier">val</span></code>
1072       to the full precision of T, where as "%.3g" would contain the value
1073       of <code class="computeroutput"><span class="identifier">val</span></code> to 3 digits. See the
1074       <a href="../../../../format/index.html" target="_top">Boost.Format</a> documentation
1075       for more details.
1076     </p>
1077 <h4>
1078 <a name="math_toolkit.error_handling.h11"></a>
1079       <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
1080       from typecasts</a>
1081     </h4>
1082 <p>
1083       Many special functions evaluate their results at a higher precision than their
1084       arguments in order to ensure full machine precision in the result: for example,
1085       a function passed a float argument may evaluate its result using double precision
1086       internally. Many of the errors listed above may therefore occur not during
1087       evaluation, but when converting the result to the narrower result type. The
1088       function:
1089     </p>
1090 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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&#160;20.&#160;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">&gt;</span>
1091 <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">&amp;</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>
1092 </pre>
1093 <p>
1094       Is used to perform these conversions, and will call the error handlers listed
1095       above on <a class="link" href="error_handling.html#math_toolkit.error_handling.overflow_error">overflow</a>,
1096       <a class="link" href="error_handling.html#math_toolkit.error_handling.underflow_error">underflow</a>
1097       or <a class="link" href="error_handling.html#math_toolkit.error_handling.denorm_error">denormalisation</a>.
1098     </p>
1099 </div>
1100 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
1101 <td align="left"></td>
1102 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
1103       Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
1104       Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
1105       R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
1106       Daryle Walker and Xiaogang Zhang<p>
1107         Distributed under the Boost Software License, Version 1.0. (See accompanying
1108         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>)
1109       </p>
1110 </div></td>
1111 </tr></table>
1112 <hr>
1113 <div class="spirit-nav">
1114 <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>
1115 </div>
1116 </body>
1117 </html>