5.11 Rounding Related Functions

Function: void mpfr_set_default_rounding_mode (mpfr_rnd_t rnd)

Set the default rounding mode to rnd. The default rounding mode is to nearest initially.

Function: mpfr_rnd_t mpfr_get_default_rounding_mode (void)

Get the default rounding mode.

Function: int mpfr_prec_round (mpfr_t x, mpfr_prec_t prec, mpfr_rnd_t rnd)

Round x according to rnd with precision prec, which must be an integer between MPFR_PREC_MIN and MPFR_PREC_MAX (otherwise the behavior is undefined). If prec is greater or equal to the precision of x, then new space is allocated for the significand, and it is filled with zeros. Otherwise, the significand is rounded to precision prec with the given direction. In both cases, the precision of x is changed to prec.

Here is an example of how to use mpfr_prec_round to implement Newton’s algorithm to compute the inverse of a, assuming x is already an approximation to n bits:

  mpfr_set_prec (t, 2 * n);
  mpfr_set (t, a, MPFR_RNDN);         /* round a to 2n bits */
  mpfr_mul (t, t, x, MPFR_RNDN);      /* t is correct to 2n bits */
  mpfr_ui_sub (t, 1, t, MPFR_RNDN);   /* high n bits cancel with 1 */
  mpfr_prec_round (t, n, MPFR_RNDN);  /* t is correct to n bits */
  mpfr_mul (t, t, x, MPFR_RNDN);      /* t is correct to n bits */
  mpfr_prec_round (x, 2 * n, MPFR_RNDN); /* exact */
  mpfr_add (x, x, t, MPFR_RNDN);      /* x is correct to 2n bits */

Warning! You must not use this function if x was initialized with MPFR_DECL_INIT or with mpfr_custom_init_set (see Custom Interface).

Function: int mpfr_can_round (mpfr_t b, mpfr_exp_t err, mpfr_rnd_t rnd1, mpfr_rnd_t rnd2, mpfr_prec_t prec)

Assuming b is an approximation of an unknown number x in the direction rnd1 with error at most two to the power E(b)-err where E(b) is the exponent of b, return a non-zero value if one is able to round correctly x to precision prec with the direction rnd2, and 0 otherwise (including for NaN and Inf). This function does not modify its arguments.

If rnd1 is MPFR_RNDN, then the sign of the error is unknown, but its absolute value is the same, so that the possible range is twice as large as with a directed rounding for rnd1.

Note: if one wants to also determine the correct ternary value when rounding b to precision prec with rounding mode rnd, a useful trick is the following:

if (mpfr_can_round (b, err, MPFR_RNDN, MPFR_RNDZ,
    prec + (rnd == MPFR_RNDN)))
   ...

Indeed, if rnd is MPFR_RNDN, this will check if one can round to prec+1 bits with a directed rounding: if so, one can surely round to nearest to prec bits, and in addition one can determine the correct ternary value, which would not be the case when b is near from a value exactly representable on prec bits.

Function: mpfr_prec_t mpfr_min_prec (mpfr_t x)

Return the minimal number of bits required to store the significand of x, and 0 for special values, including 0. (Warning: the returned value can be less than MPFR_PREC_MIN.)

The function name is subject to change.

Function: const char * mpfr_print_rnd_mode (mpfr_rnd_t rnd)

Return a string ("MPFR_RNDD", "MPFR_RNDU", "MPFR_RNDN", "MPFR_RNDZ", "MPFR_RNDA") corresponding to the rounding mode rnd, or a null pointer if rnd is an invalid rounding mode.