GNU MPC Basics (GNU MPC 1.3.0)

Next: Complex Functions, Previous: Reporting Bugs, Up: GNU MPC [Index]

## 4 GNU MPC Basics

All declarations needed to use GNU MPC are collected in the include file `mpc.h`. It is designed to work with both C and C++ compilers. You should include that file in any program using the GNU MPC library by adding the line

       #include "mpc.h"

### 4.1 Nomenclature and Types

Complex number or Complex for short, is a pair of two arbitrary precision floating-point numbers (for the real and imaginary parts). The C data type for such objects is `mpc_t`.

The Precision is the number of bits used to represent the mantissa of the real and imaginary parts; the corresponding C data type is `mpfr_prec_t`. For more details on the allowed precision range, see Section “Nomenclature and Types” in GNU MPFR.

The rounding mode specifies the way to round the result of a complex operation, in case the exact result can not be represented exactly in the destination mantissa; the corresponding C data type is `mpc_rnd_t`. A complex rounding mode is a pair of two rounding modes: one for the real part, one for the imaginary part.

### 4.2 Function Classes

There is only one class of functions in the GNU MPC library, namely functions for complex arithmetic. The function names begin with `mpc_`. The associated type is `mpc_t`.

### 4.3 GNU MPC Variable Conventions

As a general rule, all GNU MPC functions expect output arguments before input arguments. This notation is based on an analogy with the assignment operator.

GNU MPC allows you to use the same variable for both input and output in the same expression. For example, the main function for floating-point multiplication, `mpc_mul`, can be used like this: `mpc_mul (x, x, x, rnd_mode)`. This computes the square of x with rounding mode `rnd_mode` and puts the result back in x.

Before you can assign to an GNU MPC variable, you need to initialise it by calling one of the special initialization functions. When you are done with a variable, you need to clear it out, using one of the functions for that purpose.

A variable should only be initialised once, or at least cleared out between each initialization. After a variable has been initialised, it may be assigned to any number of times.

For efficiency reasons, avoid to initialise and clear out a variable in loops. Instead, initialise it before entering the loop, and clear it out after the loop has exited.

You do not need to be concerned about allocating additional space for GNU MPC variables, since each of its real and imaginary part has a mantissa of fixed size. Hence unless you change its precision, or clear and reinitialise it, a complex variable will have the same allocated space during all its life.

### 4.4 Rounding Modes

A complex rounding mode is of the form `MPC_RNDxy` where `x` and `y` are one of `N` (to nearest), `Z` (towards zero), `U` (towards plus infinity), `D` (towards minus infinity), `A` (away from zero, that is, towards plus or minus infinity depending on the sign of the number to be rounded). The first letter refers to the rounding mode for the real part, and the second one for the imaginary part. For example `MPC_RNDZU` indicates to round the real part towards zero, and the imaginary part towards plus infinity.

The ‘`round to nearest`’ mode works as in the IEEE P754 standard: in case the number to be rounded lies exactly in the middle of two representable numbers, it is rounded to the one with the least significant bit set to zero. For example, the number 5, which is represented by (101) in binary, is rounded to (100)=4 with a precision of two bits, and not to (110)=6.

### 4.5 Return Value

Most GNU MPC functions have a return value of type `int`, which is used to indicate the position of the rounded real and imaginary parts with respect to the exact (infinite precision) values. If this integer is `i`, the macros `MPC_INEX_RE(i)` and `MPC_INEX_IM(i)` give 0 if the corresponding rounded value is exact, a negative value if the rounded value is less than the exact one, and a positive value if it is greater than the exact one. Similarly, functions computing a result of type `mpfr_t` return an integer that is 0, positive or negative depending on whether the rounded value is the same, larger or smaller then the exact result.

Some functions, such as `mpc_sin_cos`, compute two complex results; the macros `MPC_INEX1(i)` and `MPC_INEX2(i)`, applied to the return value `i` of such a function, yield the exactness value corresponding to the first or the second computed value, respectively.

### 4.6 Branch Cuts And Special Values

Some complex functions have branch cuts, across which the function is discontinous. In GNU MPC, the branch cuts chosen are the same as those specified for the corresponding functions in the ISO C99 standard.

Likewise, when evaluated at a point whose real or imaginary part is either infinite or a NaN or a signed zero, a function returns the same value as those specified for the corresponding function in the ISO C99 standard.

Next: Complex Functions, Previous: Reporting Bugs, Up: GNU MPC [Index]