5.12 Exception Related Functions

Function: mp_exp_t mpfr_get_emin (void)

Function: mp_exp_t mpfr_get_emax (void)

Return the (current) smallest and largest exponents allowed for a floating-point variable. The smallest positive value of a floating-point variable is one half times 2 raised to the smallest exponent and the largest value has the form (1 - epsilon) times 2 raised to the largest exponent.

Function: int mpfr_set_emin (mp_exp_t exp)

Function: int mpfr_set_emax (mp_exp_t exp)

Set the smallest and largest exponents allowed for a floating-point variable. Return a non-zero value when exp is not in the range accepted by the implementation (in that case the smallest or largest exponent is not changed), and zero otherwise. If the user changes the exponent range, it is her/his responsibility to check that all current floating-point variables are in the new allowed range (for example using mpfr_check_range), otherwise the subsequent behavior will be undefined, in the sense of the ISO C standard.

Function: mp_exp_t mpfr_get_emin_min (void)

Function: mp_exp_t mpfr_get_emin_max (void)

Function: mp_exp_t mpfr_get_emax_min (void)

Function: mp_exp_t mpfr_get_emax_max (void)

Return the minimum and maximum of the smallest and largest exponents allowed for mpfr_set_emin and mpfr_set_emax. These values are implementation dependent; it is possible to create a non portable program by writing mpfr_set_emax(mpfr_get_emax_max()) and mpfr_set_emin(mpfr_get_emin_min()) since the values of the smallest and largest exponents become implementation dependent.

Function: int mpfr_check_range (mpfr_t x, int t, mp_rnd_t rnd)

This function forces x to be in the current range of acceptable values, t being the current ternary value: negative if x is smaller than the exact value, positive if x is larger than the exact value and zero if x is exact (before the call). It generates an underflow or an overflow if the exponent of x is outside the current allowed range; the value of t may be used to avoid a double rounding. This function returns zero if the rounded result is equal to the exact one, a positive value if the rounded result is larger than the exact one, a negative value if the rounded result is smaller than the exact one. Note that unlike most functions, the result is compared to the exact one, not the input value x, i.e. the ternary value is propagated.

Note: If x is an infinity and t is different from zero (i.e., if the rounded result is an inexact infinity), then the overflow flag is set. This is useful because mpfr_check_range is typically called (at least in MPFR functions) after restoring the flags that could have been set due to internal computations.

Function: int mpfr_subnormalize (mpfr_t x, int t, mp_rnd_t rnd)

This function rounds x emulating subnormal number arithmetic: if x is outside the subnormal exponent range, it just propagates the ternary value t; otherwise, it rounds x to precision EXP(x)-emin+1 according to rounding mode rnd and previous ternary value t, avoiding double rounding problems. More precisely in the subnormal domain, denoting by e the value of emin, x is rounded in fixed-point arithmetic to an integer multiple of two to the power e-1; as a consequence, 1.5 multiplied by two to the power e-1 when t is zero is rounded to two to the power e with rounding to nearest.

PREC(x) is not modified by this function. rnd and t must be the used rounding mode for computing x and the returned ternary value when computing x. The subnormal exponent range is from emin to emin+PREC(x)-1. If the result cannot be represented in the current exponent range (due to a too small emax), the behavior is undefined. Note that unlike most functions, the result is compared to the exact one, not the input value x, i.e. the ternary value is propagated. This is a preliminary interface.

This is an example of how to emulate double IEEE-754 arithmetic using MPFR:

{
  mpfr_t xa, xb;
  int i;
  volatile double a, b;

  mpfr_set_default_prec (53);
  mpfr_set_emin (-1073);
  mpfr_set_emax (1024);

  mpfr_init (xa); mpfr_init (xb);

  b = 34.3; mpfr_set_d (xb, b, GMP_RNDN);
  a = 0x1.1235P-1021; mpfr_set_d (xa, a, GMP_RNDN);

  a /= b;
  i = mpfr_div (xa, xa, xb, GMP_RNDN);
  i = mpfr_subnormalize (xa, i, GMP_RNDN);

  mpfr_clear (xa); mpfr_clear (xb);
}

Warning: this emulates a double IEEE-754 arithmetic with correct rounding in the subnormal range, which may not be the case for your hardware.

Function: void mpfr_clear_underflow (void)

Function: void mpfr_clear_overflow (void)

Function: void mpfr_clear_nanflag (void)

Function: void mpfr_clear_inexflag (void)

Function: void mpfr_clear_erangeflag (void)

Clear the underflow, overflow, invalid, inexact and erange flags.

Function: void mpfr_set_underflow (void)

Function: void mpfr_set_overflow (void)

Function: void mpfr_set_nanflag (void)

Function: void mpfr_set_inexflag (void)

Function: void mpfr_set_erangeflag (void)

Set the underflow, overflow, invalid, inexact and erange flags.

Function: void mpfr_clear_flags (void)

Clear all global flags (underflow, overflow, inexact, invalid, erange).

Function: int mpfr_underflow_p (void)

Function: int mpfr_overflow_p (void)

Function: int mpfr_nanflag_p (void)

Function: int mpfr_inexflag_p (void)

Function: int mpfr_erangeflag_p (void)

Return the corresponding (underflow, overflow, invalid, inexact, erange) flag, which is non-zero iff the flag is set.