Next: Complex Functions, Previous: Reporting Bugs, Up: Top [Index]
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"
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.
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.
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 initialize 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 initialized once, or at least cleared out between each initialization. After a variable has been initialized, it may be assigned to any number of times.
For efficiency reasons, avoid to initialize and clear out a variable in loops. Instead, initialize 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 reinitialize it, a complex variable will have the same allocated space during all its life.
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).
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.
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.
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: Top [Index]