GNU MPFR 3.1.4: Custom Interface
Description: How to install and use GNU MPFR, a library for reliable multiple precision floating-point arithmetic, version 3.1.4.

Next: Internals, Previous: Compatibility with MPF, Up: MPFR Interface [Index]

### 5.15 Custom Interface

Some applications use a stack to handle the memory and their objects. However, the MPFR memory design is not well suited for such a thing. So that such applications are able to use MPFR, an auxiliary memory interface has been created: the Custom Interface.

The following interface allows one to use MPFR in two ways:

- Either directly store a floating-point number as a `mpfr_t` on the stack.
- Either store its own representation on the stack and construct a new temporary `mpfr_t` each time it is needed.

Nothing has to be done to destroy the floating-point numbers except garbaging the used memory: all the memory management (allocating, destroying, garbaging) is left to the application.

Each function in this interface is also implemented as a macro for efficiency reasons: for example `mpfr_custom_init (s, p)` uses the macro, while `(mpfr_custom_init) (s, p)` uses the function.

Note 1: MPFR functions may still initialize temporary floating-point numbers using `mpfr_init` and similar functions. See Custom Allocation (GNU MP).

Note 2: MPFR functions may use the cached functions (`mpfr_const_pi` for example), even if they are not explicitly called. You have to call `mpfr_free_cache` each time you garbage the memory iff `mpfr_init`, through GMP Custom Allocation, allocates its memory on the application stack.

Function: size_t mpfr_custom_get_size (mpfr_prec_t prec)

  Return the needed size in bytes to store the significand of a floating-point number of precision prec.

Function: void mpfr_custom_init (void *significand, mpfr_prec_t prec)

  Initialize a significand of precision prec, where significand must be an area of `mpfr_custom_get_size (prec)` bytes at least and be suitably aligned for an array of `mp_limb_t` (GMP type, see Internals).

Function: void mpfr_custom_init_set (mpfr_t x, int kind, mpfr_exp_t exp, mpfr_prec_t prec, void *significand)

  Perform a dummy initialization of a `mpfr_t` and set it to:

  - if `ABS(kind) == MPFR_NAN_KIND`, x is set to NaN;
  - if `ABS(kind) == MPFR_INF_KIND`, x is set to the infinity of sign `sign(kind)`;
  - if `ABS(kind) == MPFR_ZERO_KIND`, x is set to the zero of sign `sign(kind)`;
  - if `ABS(kind) == MPFR_REGULAR_KIND`, x is set to a regular number: `x = sign(kind)*significand*2^exp`.

  In all cases, it uses significand directly for further computing involving x. It will not allocate anything. A floating-point number initialized with this function cannot be resized using `mpfr_set_prec` or `mpfr_prec_round`, or cleared using `mpfr_clear`! The significand must have been initialized with `mpfr_custom_init` using the same precision prec.

Function: int mpfr_custom_get_kind (mpfr_t x)

  Return the current kind of a `mpfr_t` as created by `mpfr_custom_init_set`. The behavior of this function for any `mpfr_t` not initialized with `mpfr_custom_init_set` is undefined.

Function: void * mpfr_custom_get_significand (mpfr_t x)

  Return a pointer to the significand used by a `mpfr_t` initialized with `mpfr_custom_init_set`. The behavior of this function for any `mpfr_t` not initialized with `mpfr_custom_init_set` is undefined.

Function: mpfr_exp_t mpfr_custom_get_exp (mpfr_t x)

  Return the exponent of x, assuming that x is a non-zero ordinary number. The return value for NaN, Infinity or zero is unspecified but does not produce any trap. The behavior of this function for any `mpfr_t` not initialized with `mpfr_custom_init_set` is undefined.

Function: void mpfr_custom_move (mpfr_t x, void *new_position)

  Inform MPFR that the significand of x has moved due to a garbage collect and update its new position to `new_position`. However the application has to move the significand and the `mpfr_t` itself. The behavior of this function for any `mpfr_t` not initialized with `mpfr_custom_init_set` is undefined.

Next: Internals, Previous: Compatibility with MPF, Up: MPFR Interface [Index]