ceph/src/boost/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.77.1">
   7 <link rel="home" href="../index.html" title="Math Toolkit 2.5.1">
   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. If you do not try to catch the exception, you will not see the message!
  53       </p></td></tr>
  54 </table></div>
  55 <p>
  56       The kinds of errors that can be raised are:
  57     </p>
  58 <div class="variablelist">
  59 <p class="title"><b></b></p>
  60 <dl class="variablelist">
  61 <dt><span class="term">Domain Error</span></dt>
  62 <dd><p>
  63             Occurs when one or more arguments to a function are out of range.
  64           </p></dd>
  65 <dt><span class="term">Pole Error</span></dt>
  66 <dd><p>
  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.
  73           </p></dd>
  74 <dt><span class="term">Overflow Error</span></dt>
  75 <dd><p>
  76             Occurs when the result is either infinite, or too large to represent
  77             in the numeric type being returned by the function.
  78           </p></dd>
  79 <dt><span class="term">Underflow Error</span></dt>
  80 <dd><p>
  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.
  83           </p></dd>
  84 <dt><span class="term">Denormalisation Error</span></dt>
  85 <dd><p>
  86             Occurs when the returned result would be a denormalised value.
  87           </p></dd>
  88 <dt><span class="term">Rounding Error</span></dt>
  89 <dd><p>
  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
  93             result type.
  94           </p></dd>
  95 <dt><span class="term">Evaluation Error</span></dt>
  96 <dd><p>
  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.
 101           </p></dd>
 102 <dt><span class="term">Indeterminate Result Error</span></dt>
 103 <dd><p>
 104             Occurs when the result of a function is not defined for the values that
 105             were passed to it.
 106           </p></dd>
 107 </dl>
 108 </div>
 109 <p>
 110       The action undertaken by each error condition is determined by the current
 111       <a class="link" href="../policy.html" title="Chapter&#160;15.&#160;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).
 114     </p>
 115 <p>
 116       The available actions are:
 117     </p>
 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>
 122 <dd><p>
 123             Throws the exception most appropriate to the error condition.
 124           </p></dd>
 125 <dt><span class="term">errno_on_error</span></dt>
 126 <dd><p>
 127             Sets ::errno to an appropriate value, and then returns the most appropriate
 128             result
 129           </p></dd>
 130 <dt><span class="term">ignore_error</span></dt>
 131 <dd><p>
 132             Ignores the error and simply the returns the most appropriate result.
 133           </p></dd>
 134 <dt><span class="term">user_error</span></dt>
 135 <dd><p>
 136             Calls a <a class="link" href="pol_tutorial/user_def_err_pol.html" title="Calling User Defined Error Handlers">user-supplied
 137             error handler</a>.
 138           </p></dd>
 139 </dl>
 140 </div>
 141 <p>
 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>:
 144     </p>
 145 <div class="table">
 146 <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>
 147 <div class="table-contents"><table class="table" summary="Possible Actions for Domain Errors">
 148 <colgroup>
 149 <col>
 150 <col>
 151 </colgroup>
 152 <thead><tr>
 153 <th>
 154               <p>
 155                 Action
 156               </p>
 157             </th>
 158 <th>
 159               <p>
 160                 Behaviour
 161               </p>
 162             </th>
 163 </tr></thead>
 164 <tbody>
 165 <tr>
 166 <td>
 167               <p>
 168                 throw_on_error
 169               </p>
 170             </td>
 171 <td>
 172               <p>
 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>
 174               </p>
 175             </td>
 176 </tr>
 177 <tr>
 178 <td>
 179               <p>
 180                 errno_on_error
 181               </p>
 182             </td>
 183 <td>
 184               <p>
 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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 188               </p>
 189             </td>
 190 </tr>
 191 <tr>
 192 <td>
 193               <p>
 194                 ignore_error
 195               </p>
 196             </td>
 197 <td>
 198               <p>
 199                 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>
 200               </p>
 201             </td>
 202 </tr>
 203 <tr>
 204 <td>
 205               <p>
 206                 user_error
 207               </p>
 208             </td>
 209 <td>
 210               <p>
 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>.
 214               </p>
 215             </td>
 216 </tr>
 217 </tbody>
 218 </table></div>
 219 </div>
 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&#160;1.2.&#160;Possible Actions for Pole Errors</b></p>
 222 <div class="table-contents"><table class="table" summary="Possible Actions for Pole Errors">
 223 <colgroup>
 224 <col>
 225 <col>
 226 </colgroup>
 227 <thead><tr>
 228 <th>
 229               <p>
 230                 Action
 231               </p>
 232             </th>
 233 <th>
 234               <p>
 235                 Behaviour
 236               </p>
 237             </th>
 238 </tr></thead>
 239 <tbody>
 240 <tr>
 241 <td>
 242               <p>
 243                 throw_on_error
 244               </p>
 245             </td>
 246 <td>
 247               <p>
 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>
 249               </p>
 250             </td>
 251 </tr>
 252 <tr>
 253 <td>
 254               <p>
 255                 errno_on_error
 256               </p>
 257             </td>
 258 <td>
 259               <p>
 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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">quiet_NaN</span><span class="special">()</span></code>
 263               </p>
 264             </td>
 265 </tr>
 266 <tr>
 267 <td>
 268               <p>
 269                 ignore_error
 270               </p>
 271             </td>
 272 <td>
 273               <p>
 274                 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>
 275               </p>
 276             </td>
 277 </tr>
 278 <tr>
 279 <td>
 280               <p>
 281                 user_error
 282               </p>
 283             </td>
 284 <td>
 285               <p>
 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>.
 289               </p>
 290             </td>
 291 </tr>
 292 </tbody>
 293 </table></div>
 294 </div>
 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&#160;1.3.&#160;Possible Actions for Overflow Errors</b></p>
 297 <div class="table-contents"><table class="table" summary="Possible Actions for Overflow Errors">
 298 <colgroup>
 299 <col>
 300 <col>
 301 </colgroup>
 302 <thead><tr>
 303 <th>
 304               <p>
 305                 Action
 306               </p>
 307             </th>
 308 <th>
 309               <p>
 310                 Behaviour
 311               </p>
 312             </th>
 313 </tr></thead>
 314 <tbody>
 315 <tr>
 316 <td>
 317               <p>
 318                 throw_on_error
 319               </p>
 320             </td>
 321 <td>
 322               <p>
 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>
 324               </p>
 325             </td>
 326 </tr>
 327 <tr>
 328 <td>
 329               <p>
 330                 errno_on_error
 331               </p>
 332             </td>
 333 <td>
 334               <p>
 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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">()</span></code>
 338               </p>
 339             </td>
 340 </tr>
 341 <tr>
 342 <td>
 343               <p>
 344                 ignore_error
 345               </p>
 346             </td>
 347 <td>
 348               <p>
 349                 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>
 350               </p>
 351             </td>
 352 </tr>
 353 <tr>
 354 <td>
 355               <p>
 356                 user_error
 357               </p>
 358             </td>
 359 <td>
 360               <p>
 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>.
 364               </p>
 365             </td>
 366 </tr>
 367 </tbody>
 368 </table></div>
 369 </div>
 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&#160;1.4.&#160;Possible Actions for Underflow Errors</b></p>
 372 <div class="table-contents"><table class="table" summary="Possible Actions for Underflow Errors">
 373 <colgroup>
 374 <col>
 375 <col>
 376 </colgroup>
 377 <thead><tr>
 378 <th>
 379               <p>
 380                 Action
 381               </p>
 382             </th>
 383 <th>
 384               <p>
 385                 Behaviour
 386               </p>
 387             </th>
 388 </tr></thead>
 389 <tbody>
 390 <tr>
 391 <td>
 392               <p>
 393                 throw_on_error
 394               </p>
 395             </td>
 396 <td>
 397               <p>
 398                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
 399               </p>
 400             </td>
 401 </tr>
 402 <tr>
 403 <td>
 404               <p>
 405                 errno_on_error
 406               </p>
 407             </td>
 408 <td>
 409               <p>
 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
 412                 0.
 413               </p>
 414             </td>
 415 </tr>
 416 <tr>
 417 <td>
 418               <p>
 419                 ignore_error
 420               </p>
 421             </td>
 422 <td>
 423               <p>
 424                 <span class="bold"><strong>Returns 0</strong></span>
 425               </p>
 426             </td>
 427 </tr>
 428 <tr>
 429 <td>
 430               <p>
 431                 user_error
 432               </p>
 433             </td>
 434 <td>
 435               <p>
 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>.
 439               </p>
 440             </td>
 441 </tr>
 442 </tbody>
 443 </table></div>
 444 </div>
 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&#160;1.5.&#160;Possible Actions for Denorm Errors</b></p>
 447 <div class="table-contents"><table class="table" summary="Possible Actions for Denorm Errors">
 448 <colgroup>
 449 <col>
 450 <col>
 451 </colgroup>
 452 <thead><tr>
 453 <th>
 454               <p>
 455                 Action
 456               </p>
 457             </th>
 458 <th>
 459               <p>
 460                 Behaviour
 461               </p>
 462             </th>
 463 </tr></thead>
 464 <tbody>
 465 <tr>
 466 <td>
 467               <p>
 468                 throw_on_error
 469               </p>
 470             </td>
 471 <td>
 472               <p>
 473                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underflow_error</span></code>
 474               </p>
 475             </td>
 476 </tr>
 477 <tr>
 478 <td>
 479               <p>
 480                 errno_on_error
 481               </p>
 482             </td>
 483 <td>
 484               <p>
 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.
 488               </p>
 489             </td>
 490 </tr>
 491 <tr>
 492 <td>
 493               <p>
 494                 ignore_error
 495               </p>
 496             </td>
 497 <td>
 498               <p>
 499                 <span class="bold"><strong>Returns the denormalised value.</strong></span>
 500               </p>
 501             </td>
 502 </tr>
 503 <tr>
 504 <td>
 505               <p>
 506                 user_error
 507               </p>
 508             </td>
 509 <td>
 510               <p>
 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>.
 514               </p>
 515             </td>
 516 </tr>
 517 </tbody>
 518 </table></div>
 519 </div>
 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&#160;1.6.&#160;Possible Actions for Rounding Errors</b></p>
 522 <div class="table-contents"><table class="table" summary="Possible Actions for Rounding Errors">
 523 <colgroup>
 524 <col>
 525 <col>
 526 </colgroup>
 527 <thead><tr>
 528 <th>
 529               <p>
 530                 Action
 531               </p>
 532             </th>
 533 <th>
 534               <p>
 535                 Behaviour
 536               </p>
 537             </th>
 538 </tr></thead>
 539 <tbody>
 540 <tr>
 541 <td>
 542               <p>
 543                 throw_on_error
 544               </p>
 545             </td>
 546 <td>
 547               <p>
 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>
 549               </p>
 550             </td>
 551 </tr>
 552 <tr>
 553 <td>
 554               <p>
 555                 errno_on_error
 556               </p>
 557             </td>
 558 <td>
 559               <p>
 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
 564                 zero).
 565               </p>
 566             </td>
 567 </tr>
 568 <tr>
 569 <td>
 570               <p>
 571                 ignore_error
 572               </p>
 573             </td>
 574 <td>
 575               <p>
 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>
 579               </p>
 580             </td>
 581 </tr>
 582 <tr>
 583 <td>
 584               <p>
 585                 user_error
 586               </p>
 587             </td>
 588 <td>
 589               <p>
 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>.
 593               </p>
 594             </td>
 595 </tr>
 596 </tbody>
 597 </table></div>
 598 </div>
 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&#160;1.7.&#160;Possible Actions for Internal Evaluation Errors</b></p>
 601 <div class="table-contents"><table class="table" summary="Possible Actions for Internal Evaluation Errors">
 602 <colgroup>
 603 <col>
 604 <col>
 605 </colgroup>
 606 <thead><tr>
 607 <th>
 608               <p>
 609                 Action
 610               </p>
 611             </th>
 612 <th>
 613               <p>
 614                 Behaviour
 615               </p>
 616             </th>
 617 </tr></thead>
 618 <tbody>
 619 <tr>
 620 <td>
 621               <p>
 622                 throw_on_error
 623               </p>
 624             </td>
 625 <td>
 626               <p>
 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>
 628               </p>
 629             </td>
 630 </tr>
 631 <tr>
 632 <td>
 633               <p>
 634                 errno_on_error
 635               </p>
 636             </td>
 637 <td>
 638               <p>
 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.
 642               </p>
 643             </td>
 644 </tr>
 645 <tr>
 646 <td>
 647               <p>
 648                 ignore_error
 649               </p>
 650             </td>
 651 <td>
 652               <p>
 653                 Returns the closest approximation found.
 654               </p>
 655             </td>
 656 </tr>
 657 <tr>
 658 <td>
 659               <p>
 660                 user_error
 661               </p>
 662             </td>
 663 <td>
 664               <p>
 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>.
 668               </p>
 669             </td>
 670 </tr>
 671 </tbody>
 672 </table></div>
 673 </div>
 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&#160;1.8.&#160;Possible Actions for Indeterminate Result Errors</b></p>
 676 <div class="table-contents"><table class="table" summary="Possible Actions for Indeterminate Result Errors">
 677 <colgroup>
 678 <col>
 679 <col>
 680 </colgroup>
 681 <thead><tr>
 682 <th>
 683               <p>
 684                 Action
 685               </p>
 686             </th>
 687 <th>
 688               <p>
 689                 Behaviour
 690               </p>
 691             </th>
 692 </tr></thead>
 693 <tbody>
 694 <tr>
 695 <td>
 696               <p>
 697                 throw_on_error
 698               </p>
 699             </td>
 700 <td>
 701               <p>
 702                 Throws <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
 703               </p>
 704             </td>
 705 </tr>
 706 <tr>
 707 <td>
 708               <p>
 709                 errno_on_error
 710               </p>
 711             </td>
 712 <td>
 713               <p>
 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>.
 717               </p>
 718             </td>
 719 </tr>
 720 <tr>
 721 <td>
 722               <p>
 723                 ignore_error
 724               </p>
 725             </td>
 726 <td>
 727               <p>
 728                 <span class="bold"><strong>Returns a default result that depends on the
 729                 function where the error occurred.</strong></span>
 730               </p>
 731             </td>
 732 </tr>
 733 <tr>
 734 <td>
 735               <p>
 736                 user_error
 737               </p>
 738             </td>
 739 <td>
 740               <p>
 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>.
 744               </p>
 745             </td>
 746 </tr>
 747 </tbody>
 748 </table></div>
 749 </div>
 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>.
 754     </p>
 755 <h4>
 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>
 758     </h4>
 759 <p>
 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:
 763     </p>
 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>.
 768         </li>
 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.
 772         </li>
 773 <li class="listitem">
 774           If there is more than one error, only the first detected will be reported
 775           in the throw message.
 776         </li>
 777 </ul></div>
 778 <h4>
 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
 781       More Information</a>
 782     </h4>
 783 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">policy section</a>.
 786     </p>
 787 <p>
 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>.
 790     </p>
 791 <p>
 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>.
 795     </p>
 796 <p>
 797       The various kind of errors are described in more detail below.
 798     </p>
 799 <h4>
 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
 802       Errors</a>
 803     </h4>
 804 <p>
 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
 807       of:
 808     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 810 </pre>
 811 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use
 817       for the function that was called.
 818     </p>
 819 <p>
 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&#160;15.&#160;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.
 824     </p>
 825 <p>
 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
 829       6</a>:
 830     </p>
 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">
 838 <p>
 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>
 841       </p>
 842 <p>
 843         <span class="emphasis"><em>"the corresponding mathematical function value has a non-zero
 844         imaginary component; or</em></span>
 845       </p>
 846 <p>
 847         <span class="emphasis"><em>"the corresponding mathematical function is not mathematically
 848         defined.</em></span>
 849       </p>
 850 </blockquote></div>
 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>
 857 <p>
 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.
 863     </p>
 864 <p>
 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
 870       for more details.
 871     </p>
 872 <h4>
 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
 875       at a pole</a>
 876     </h4>
 877 <p>
 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:
 880     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 882 </pre>
 883 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 889       is the current policy in use for the function that was called.
 890     </p>
 891 <p>
 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>
 895       and return NaN.
 896     </p>
 897 <p>
 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.
 903     </p>
 904 <p>
 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
 910       for more details.
 911     </p>
 912 <h4>
 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
 915       Overflow</a>
 916     </h4>
 917 <p>
 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:
 920     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 922 </pre>
 923 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 928       is the current policy in use for the function that was called.
 929     </p>
 930 <p>
 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">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</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.
 936     </p>
 937 <h4>
 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
 940       Underflow</a>
 941     </h4>
 942 <p>
 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:
 945     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 947 </pre>
 948 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 953       is the current policy in use for the called function.
 954     </p>
 955 <p>
 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.
 959     </p>
 960 <h4>
 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
 963       Errors</a>
 964     </h4>
 965 <p>
 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:
 968     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 970 </pre>
 971 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a>
 976       is the current policy in use for the called function.
 977     </p>
 978 <p>
 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.
 982     </p>
 983 <h4>
 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
 986       Errors</a>
 987     </h4>
 988 <p>
 989       When a special function calculates a result that is known to be erroneous,
 990       or where the result is incalculable then it calls:
 991     </p>
 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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
 993 </pre>
 994 <p>
 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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current
1000       policy in use for the called function.
1001     </p>
1002 <p>
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>.
1004     </p>
1005 <p>
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.
1011     </p>
1012 <p>
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
1018       for more details.
1019     </p>
1020 <h4>
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
1023       Result Errors</a>
1024     </h4>
1025 <p>
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:
1028     </p>
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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
1030 </pre>
1031 <p>
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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the current policy in use for the
1040       function that was called.
1041     </p>
1042 <p>
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.
1048     </p>
1049 <h4>
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
1052       Errors</a>
1053     </h4>
1054 <p>
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
1059       of a call to:
1060     </p>
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">&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;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">);</span>
1062 </pre>
1063 <p>
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&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> is the
1069       current policy in use for the called function.
1070     </p>
1071 <p>
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>.
1073     </p>
1074 <p>
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.
1080     </p>
1081 <p>
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
1087       for more details.
1088     </p>
1089 <h4>
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
1092       from typecasts</a>
1093     </h4>
1094 <p>
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
1100       function:
1101     </p>
1102 <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;15.&#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>
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">&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>
1104 </pre>
1105 <p>
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>.
1110     </p>
1111 </div>
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 &#169; 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&#229;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>)
1120       </p>
1121 </div></td>
1122 </tr></table>
1123 <hr>
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>
1126 </div>
1127 </body>
1128 </html>