|
www.riscos.com Technical Support: |
The Complex Math library is a part of the C++ library, ported from that supplied with AT&T's CFront product.
complex - introduction to C++ complex mathematics library
#include <complex.h> class complex;
This section describes complex mathematics functions and operators found in the C++ Library.
The Complex Mathematics library implements the data type of complex numbers as a class, complex. It overloads the standard input, output, arithmetic, assignment, and comparison operators, discussed in complex operators. It also overloads the standard exponential, logarithm, power, and square root functions, discussed in exp, log, pow, sqrt, and the trigonometric functions of sine, cosine, hyperbolic sine, and hyperbolic cosine, discussed in cplxtrig, for the class complex. Routines for converting between Cartesian and polar coordinate systems are discussed in cartesian/polar. Error handling is described in complex_error.
Functions in the Complex Mathematics Library may return the conventional values (0, 0), (0, ±HUGE), (±HUGE, 0), or (±HUGE, ±HUGE), when the function is undefined for the given arguments or when the value is not representable. (HUGE is the largest-magnitude single-precision floating-point number and is defined in the file <math.h>. The header file <math.h> is included in the file <complex.h>.) In these cases, the external variable errno is set to the value EDOM or ERANGE.
#include <complex.h>
class complex {
public:
friend double abs(complex);
friend double arg(complex);
friend complex conj(complex);
friend double imag(complex);
friend double norm(complex);
friend complex polar(double, double = 0);
friend double real(complex);
};
The following functions are defined for complex, where:
d = abs(x)
Returns the absolute value or magnitude of x.
d = norm(x)
Returns the square of the magnitude of x. It is faster than abs, but more likely to cause an overflow error. It is intended for comparison of magnitudes.
d = arg(x)
Returns the angle of x, measured in radians in the range -
TO .
y = conj(x)
Returns the complex conjugate of x. That is, if x is (real, imag), then conj(x ) is (real, -imag).
y = polar(m, a)
Creates a complex given a pair of polar coordinates, magnitude m, and angle a, measured in radians.
d = real(x)
Returns the real part of x.
d = imag(x)
Returns the imaginary part of x.
#include <complex.h>
class c_exception
{
int type;
char *name;
complex arg1;
complex arg2;
complex retval;
public:
c_exception( char *n, const complex& a1,
const complex& a2 = complex_zero );
friend int complex_error( c_exception& );
friend complex exp( complex );
friend complex sinh( complex );
friend complex cosh( complex );
friend complex log( complex );
};
In the following description of the complex error handling routine:
i = complex_error(x)
Invoked by functions in the C++ Complex Mathematics Library when errors are detected.
Users may define their own procedures for handling errors, by defining a function named complex_error in their programs. complex_error must be of the form described above.
The element type is an integer describing the type of error that has occurred, from the following list of constants (defined in the header file):
| SING | argument singularity |
| OVERFLOW | overflow range error |
| UNDERFLOW | underflow range error |
The element name points to a string containing the name of the function that incurred the error. The variables arg1 and arg2 are the arguments with which the function was invoked. retval is set to the default value that will be returned by the function unless the user's complex_error sets it to a different value.
If the user's complex_error function returns non-zero, no error message will be printed, and errno will not be set.
If complex_error is not supplied by the user, the default error-handling procedures, described with the complex math functions involved, will be invoked upon error. These procedures are also summarised in the table below. In every case, errno is set to EDOM or ERANGE and the program continues.
Note that complex math functions call functions included in the math library which has its own error handling routine, matherr. Users may also override this routine by supplying their own version.
| Key: | M | Message is printed (EDOM error) |
|---|---|---|
| (H, 0) | (HUGE, 0) is returned | |
| (±H, ±H) | (±HUGE, ±HUGE) is returned | |
| (0, 0) | (0, 0) is returned |
#include <complex.h>
class complex {
public:
friend complex exp(complex);
friend complex log(complex);
friend complex pow(double, complex);
friend complex pow(complex, int);
friend complex pow(complex, double);
friend complex pow(complex, complex);
friend complex sqrt(complex);
};
The following math functions are overloaded by the complex library, where:
z = exp(x)
Returns ex.
z = log(x)
Returns the natural logarithm of x.
z = pow(x, y)
Returns xy
z = sqrt(x)
Returns the square root of x, contained in the first or fourth quadrants of the complex plane.
exp returns (0, 0) when the real part of x is so small, or the imaginary part is so large, as to cause overflow. When the real part is large enough to cause overflow, exp returns (HUGE, HUGE) if the cosine and sine of the imaginary part of x are positive, (HUGE, -HUGE) if the cosine is positive and the sine is not, (-HUGE, HUGE) if the sine is positive and the cosine is not, and (-HUGE, -HUGE) if neither sine nor cosine is positive. In all these cases, errno is set to ERANGE.
log returns (-HUGE, 0) and sets errno to EDOM when x is (0, 0). A message indicating SING error is printed on the standard error output.
These error-handling procedures may be changed with the function complex_error (see complex_error).
#include <complex.h>
class complex {
public:
friend complex operator+(complex, complex);
friend complex operator-(complex);
friend complex operator-(complex, complex);
friend complex operator*(complex, complex);
friend complex operator/(complex, complex);
friend int operator==(complex, complex);
friend int operator!=(complex, complex);
void operator+=(complex);
void operator-=(complex);
void operator*=(complex);
void operator/=(complex);
};
The basic arithmetic operators, comparison operators, and assignment operators are overloaded for complex numbers. The operators have their conventional precedences. In the following descriptions for complex operators:
z = x + y
Returns a complex which is the arithmetic sum of complex numbers x and y.
z = -x
Returns a complex which is the arithmetic negation of complex number x.
z = x - y
Returns a complex which is the arithmetic difference of complex numbers x and y.
z = x * y
Returns a complex which is the arithmetic product of complex numbers x and y.
z = x / y
Returns a complex which is the arithmetic quotient of complex numbers x and y.
x == y
Returns non-zero if complex number x is equal to complex number y; returns 0 otherwise.
x != y
Returns non-zero if complex number x is not equal to complex number y; returns 0 otherwise.
x += y
Complex number x is assigned the value of the arithmetic sum of itself and complex number y.
x -= y
Complex number x is assigned the value of the arithmetic difference of itself and complex number y.
x *= y
Complex number x is assigned the value of the arithmetic product of itself and complex number y.
x /= y
Complex number x is assigned the value of the arithmetic quotient of itself and complex number y.
The assignment operators do not produce a value that can be used in an expression. That is, the following construction is syntactically invalid:
complex x, y, z; x = ( y += z );
whereas:
x = ( y + z ); x = ( y == z );
are valid.
#include <complex.h>
class complex {
public:
friend complex sin(complex);
friend complex cos(complex);
friend complex sinh(complex);
friend complex cosh(complex);
};
The following trigonometric functions are defined for complex, where:
y = sin(x)
Returns the sine of x.
y = cos(x)
Returns the cosine of x.
y = sinh(x)
Returns the hyperbolic sine of x.
y = cosh(x)
Returns the hyperbolic cosine of x.
If the imaginary part of x would cause overflow sinh and cosh return (0, 0). When the real part is large enough to cause overflow, sinh and cosh return (HUGE, HUGE) if the cosine and sine of the imaginary part of x are non-negative, (HUGE, -HUGE) if the cosine is non-negative and the sine is less than 0, (-HUGE, HUGE) if the sine is non-negative and the cosine is less than 0, and (-HUGE, -HUGE) if both sine and cosine are less than 0. In all these cases, errno is set to ERANGE.
These error-handling procedures may be changed with the function complex_error (see complex_error).