Next: , Previous: , Up: MPFR Interface   [Index]

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:

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.

Note: when MPFR is built with the --enable-thread-safe configure option, the default precision is local to each thread. See Memory Handling, for more information.

Function: mpfr_prec_t mpfr_get_default_prec (void)

Return the current default MPFR precision in bits. See the documentation of mpfr_set_default_prec.

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.

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: 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.

Next: , Previous: , Up: MPFR Interface   [Index]