Constant gmp_mpfr_sys::C::MPC::GNU_MPC_Basics[−][src]

pub const GNU_MPC_Basics: ();

This constant is a place-holder for documentation; do not use it in code.

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