Rounding-Related Functions (GNU MPFR 4.2.0)

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 than 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; no memory reallocation to free the unused limbs is done. 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 EXP(b) − err where EXP(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 assuming an unbounded exponent range, and 0 otherwise (including for NaN and Inf). In other words, if the error on b is bounded by two to the power k ulps, and b has precision prec, you should give err = prec − k. This function does not modify its arguments.

If rnd1 is MPFR_RNDN or MPFR_RNDF, the error is considered to be either positive or negative, thus the possible range is twice as large as with a directed rounding for rnd1 (with the same value of err).

When rnd2 is MPFR_RNDF, let rnd3 be the opposite direction if rnd1 is a directed rounding, and MPFR_RNDN if rnd1 is MPFR_RNDN or MPFR_RNDF. The returned value of mpfr_can_round (b, err, rnd1, MPFR_RNDF, prec) is non-zero iff after the call mpfr_set (y, b, rnd3) with y of precision prec, y is guaranteed to be a faithful rounding of x.

Note: The ternary value cannot be determined in general with this function. However, if it is known that the exact value is not exactly representable in precision prec, then one can use the following trick to determine the (non-zero) ternary value in any rounding mode rnd2 (note that MPFR_RNDZ below can be replaced by any directed rounding mode):

if (mpfr_can_round (b, err, MPFR_RNDN, MPFR_RNDZ,
                    prec + (rnd2 == MPFR_RNDN)))
  {
    /* round the approximation b to the result r of prec bits
       with rounding mode rnd2 and get the ternary value inex */
    inex = mpfr_set (r, b, rnd2);
  }

Indeed, if rnd2 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.

A detailed example is available in the examples subdirectory, file can_round.c.

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.

Function: const char * mpfr_print_rnd_mode (mpfr_rnd_t rnd) ¶: Return a string ("MPFR_RNDN", "MPFR_RNDZ", "MPFR_RNDU", "MPFR_RNDD", "MPFR_RNDA", "MPFR_RNDF") corresponding to the rounding mode rnd, or a null pointer if rnd is an invalid rounding mode.

Macro: int mpfr_round_nearest_away (int (foo)(mpfr_t, type1_t, ..., mpfr_rnd_t), mpfr_t rop, type1_t op, ...) ¶

Given a function foo and one or more values op (which may be a mpfr_t, a long int, a double, etc.), put in rop the round-to-nearest-away rounding of foo(op,...). This rounding is defined in the same way as round-to-nearest-even, except in case of tie, where the value away from zero is returned. The function foo takes as input, from second to penultimate argument(s), the argument list given after rop, a rounding mode as final argument, puts in its first argument the value foo(op,...) rounded according to this rounding mode, and returns the corresponding ternary value (which is expected to be correct, otherwise mpfr_round_nearest_away will not work as desired). Due to implementation constraints, this function must not be called when the minimal exponent emin is the smallest possible one. This macro has been made such that the compiler is able to detect mismatch between the argument list op and the function prototype of foo. Multiple input arguments op are supported only with C99 compilers. Otherwise, for C90 compilers, only one such argument is supported.

Note: this macro is experimental and its interface might change in future versions.

unsigned long ul;
mpfr_t f, r;
/* Code that inits and sets r, f, and ul, and if needed sets emin */
int i = mpfr_round_nearest_away (mpfr_add_ui, r, f, ul);