Next: Memory Handling, Previous: Floating-Point Values on Special Numbers, Up: MPFR Basics [Index]

### 4.6 Exceptions

MPFR defines a global (or per-thread) flag for each supported exception. A macro evaluating to a power of two is associated with each flag and exception, in order to be able to specify a group of flags (or a mask) by OR’ing such macros.

Flags can be cleared (lowered), set (raised), and tested by functions described in Exception Related Functions.

The supported exceptions are listed below. The macro associated with each exception is in parentheses.

- Underflow (`MPFR_FLAGS_UNDERFLOW`): An underflow occurs when the exact result of a function is a non-zero real number and the result obtained after the rounding, assuming an unbounded exponent range (for the rounding), has an exponent smaller than the minimum value of the current exponent range. (In the round-to-nearest mode, the halfway case is rounded toward zero.)

  Note: This is not the single possible definition of the underflow. MPFR chooses to consider the underflow after rounding. The underflow before rounding can also be defined. For instance, consider a function that has the exact result 7 multiplied by two to the power e−4, where e is the smallest exponent (for a significand between 1/2 and 1), with a 2-bit target precision and rounding toward plus infinity. The exact result has the exponent e−1. With the underflow before rounding, such a function call would yield an underflow, as e−1 is outside the current exponent range. However, MPFR first considers the rounded result assuming an unbounded exponent range. The exact result cannot be represented exactly in precision 2, and here, it is rounded to 0.5 times 2 to e, which is representable in the current exponent range. As a consequence, this will not yield an underflow in MPFR.

- Overflow (`MPFR_FLAGS_OVERFLOW`): An overflow occurs when the exact result of a function is a non-zero real number and the result obtained after the rounding, assuming an unbounded exponent range (for the rounding), has an exponent larger than the maximum value of the current exponent range. In the round-to-nearest mode, the result is infinite. Note: unlike the underflow case, there is only one possible definition of overflow here.
- Divide-by-zero (`MPFR_FLAGS_DIVBY0`): An exact infinite result is obtained from finite inputs.
- NaN (`MPFR_FLAGS_NAN`): A NaN exception occurs when the result of a function is NaN.
- Inexact (`MPFR_FLAGS_INEXACT`): An inexact exception occurs when the result of a function cannot be represented exactly and must be rounded.
- Range error (`MPFR_FLAGS_ERANGE`): A range exception occurs when a function that does not return a MPFR number (such as comparisons and conversions to an integer) has an invalid result (e.g., an argument is NaN in `mpfr_cmp`, or a conversion to an integer cannot be represented in the target type).

Moreover, the group consisting of all the flags is represented by the `MPFR_FLAGS_ALL` macro (if new flags are added in future MPFR versions, they will be added to this macro too).

Differences with the ISO C99 standard:

- In C, only quiet NaNs are specified, and a NaN propagation does not raise an invalid exception. Unless explicitly stated otherwise, MPFR sets the NaN flag whenever a NaN is generated, even when a NaN is propagated (e.g., in NaN + NaN), as if all NaNs were signaling.
- An invalid exception in C corresponds to either a NaN exception or a range error in MPFR.

Next: Memory Handling, Previous: Floating-Point Values on Special Numbers, Up: MPFR Basics [Index]