Rounding-Related Functions (GNU MPFR 4.1.1)
Description: How to install and use GNU MPFR, a library for reliable multiple precision floating-point arithmetic, version 4.1.1.

### 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 C89 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);