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

### 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 that has already been initialized, use `mpfr_set_prec` or `mpfr_prec_round`; note that if the precision is decreased, the unused memory will not be freed, so that it may be wise to choose a large enough initial precision in order to avoid reallocations. 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 C90). 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 C90 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.

  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)` ¶

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