5.1 Initialization Functions

An mpfr_t object must be initialized before storing the first value in it. The functions mpfr_init and mpfr_init2 are used for that purpose.

Function: void mpfr_init2 (mpfr_t x, mpfr_prec_t prec)

Initialize x, set its precision to be exactly prec bits and its value to NaN. (Warning: the corresponding MPF function initializes to zero instead.)

Normally, a variable should be initialized once only or at least be cleared, using mpfr_clear, between initializations. To change the precision of a variable which has already been initialized, use mpfr_set_prec. The precision prec must be an integer between MPFR_PREC_MIN and MPFR_PREC_MAX (otherwise the behavior is undefined).

Function: void mpfr_inits2 (mpfr_prec_t prec, mpfr_t x, ...)

Initialize all the mpfr_t variables of the given variable argument va_list, set their precision to be exactly prec bits and their value to NaN. See mpfr_init2 for more details. The va_list is assumed to be composed only of type mpfr_t (or equivalently mpfr_ptr). It begins from x, and ends when it encounters a null pointer (whose type must also be mpfr_ptr).

Function: void mpfr_clear (mpfr_t x)

Free the space occupied by the significand of x. Make sure to call this function for all mpfr_t variables when you are done with them.

Function: void mpfr_clears (mpfr_t x, ...)

Free the space occupied by all the mpfr_t variables of the given va_list. See mpfr_clear for more details. The va_list is assumed to be composed only of type mpfr_t (or equivalently mpfr_ptr). It begins from x, and ends when it encounters a null pointer (whose type must also be mpfr_ptr).

Here is an example of how to use multiple initialization functions (since NULL is not necessarily defined in this context, we use (mpfr_ptr) 0 instead, but (mpfr_ptr) NULL is also correct).

{
  mpfr_t x, y, z, t;
  mpfr_inits2 (256, x, y, z, t, (mpfr_ptr) 0);
  …
  mpfr_clears (x, y, z, t, (mpfr_ptr) 0);
}

Function: void mpfr_init (mpfr_t x)

Initialize x, set its precision to the default precision, and set its value to NaN. The default precision can be changed by a call to mpfr_set_default_prec.

Warning! In a given program, some other libraries might change the default precision and not restore it. Thus it is safer to use mpfr_init2.

Function: void mpfr_inits (mpfr_t x, ...)

Initialize all the mpfr_t variables of the given va_list, set their precision to the default precision and their value to NaN. See mpfr_init for more details. The va_list is assumed to be composed only of type mpfr_t (or equivalently mpfr_ptr). It begins from x, and ends when it encounters a null pointer (whose type must also be mpfr_ptr).

Warning! In a given program, some other libraries might change the default precision and not restore it. Thus it is safer to use mpfr_inits2.

Macro: MPFR_DECL_INIT (name, prec)

This macro declares name as an automatic variable of type mpfr_t, initializes it and sets its precision to be exactly prec bits and its value to NaN. name must be a valid identifier. You must use this macro in the declaration section. This macro is much faster than using mpfr_init2 but has some drawbacks:

• You must not call mpfr_clear with variables created with this macro (the storage is allocated at the point of declaration and deallocated when the brace-level is exited).
• You cannot change their precision.
• You should not create variables with huge precision with this macro.
• Your compiler must support ‘Non-Constant Initializers’ (standard in C++ and ISO C99) and ‘Token Pasting’ (standard in ISO C89). If prec is not a constant expression, your compiler must support ‘variable-length automatic arrays’ (standard in ISO C99). GCC 2.95.3 and above supports all these features. If you compile your program with GCC in C89 mode and with ‘-pedantic’, you may want to define the MPFR_USE_EXTENSION macro to avoid warnings due to the MPFR_DECL_INIT implementation.

Function: void mpfr_set_default_prec (mpfr_prec_t prec)

Set the default precision to be exactly prec bits, where prec can be any integer between MPFR_PREC_MIN and MPFR_PREC_MAX. The precision of a variable means the number of bits used to store its significand. All subsequent calls to mpfr_init or mpfr_inits will use this precision, but previously initialized variables are unaffected. The default precision is set to 53 bits initially.

Function: mpfr_prec_t mpfr_get_default_prec (void)

Return the current default MPFR precision in bits.

Here is an example on how to initialize floating-point variables:

{
  mpfr_t x, y;
  mpfr_init (x);                /* use default precision */
  mpfr_init2 (y, 256);          /* precision exactly 256 bits */
  …
  /* When the program is about to exit, do ... */
  mpfr_clear (x);
  mpfr_clear (y);
  mpfr_free_cache ();           /* free the cache for constants like pi */
}

The following functions are useful for changing the precision during a calculation. A typical use would be for adjusting the precision gradually in iterative algorithms like Newton-Raphson, making the computation precision closely match the actual accurate part of the numbers.

Function: void mpfr_set_prec (mpfr_t x, mpfr_prec_t prec)

Reset the precision of x to be exactly prec bits, and set its value to NaN. The previous value stored in x is lost. It is equivalent to a call to mpfr_clear(x) followed by a call to mpfr_init2(x, prec), but more efficient as no allocation is done in case the current allocated space for the significand of x is enough. The precision prec can be any integer between MPFR_PREC_MIN and MPFR_PREC_MAX. In case you want to keep the previous value stored in x, use mpfr_prec_round instead.

Function: mpfr_prec_t mpfr_get_prec (mpfr_t x)

Return the precision of x, i.e., the number of bits used to store its significand.