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 the same sign as kind;
  - if abs(kind) = `MPFR_ZERO_KIND`, x is set to the zero of the same sign as kind;
  - if abs(kind) = `MPFR_REGULAR_KIND`, x is set to the regular number whose sign is the one of kind, and whose exponent and significand are given by exp and significand.

  In all cases, significand will be used directly for further computing involving x. This function does 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 and the significand is considered in [1/2,1). But if x is NaN, infinity or zero, contrary to `mpfr_get_exp` (where the behavior is undefined), the return value is here an unspecified, valid value of the `mpfr_exp_t` type. 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]