RISCOS.com

www.riscos.com Technical Support:
Acorn C/C++

 

The Complex Math library


The Complex Math library is a part of the C++ library, ported from that supplied with AT&T's CFront product.


Introduction

complex - introduction to C++ complex mathematics library

Synopsis

#include <complex.h>
class complex;

Description

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.

Diagnostics

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.

See also

cartesian/polar, complex_error, complex operators, exp, log, pow, sqrt, cplxtrig.


cartesian/polar

cartesian/polar - functions for the C++ Complex Math Library

Synopsis

#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);

};

Description

The following functions are defined for complex, where:

  • d, m, and a are of type int
  • x and y are of type complex.

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 - PI TO  PI .

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.

See also

Introduction, complex_error, complex operators, exp, log, pow, sqrt, cplxtrig


complex_error

complex_error - error-handling function for the C++ Complex Math Library

Synopsis

#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 );

};

Description

In the following description of the complex error handling routine:

  • i is of type int
  • x is of type c_exception.

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.

Default error handling procedures
  Types of Errors
type SING OVERFLOW UNDERFLOW
errno EDOM ERANGE ERANGE
EXP real too large/small -- (±H, ±H) (0, 0)
imag too large -- (0, 0) --
LOG arg = (0, 0) M, (H, 0) -- --
SINH real too large -- (±H, ±H) --
imag too large -- (0, 0) --
COSH real too large -- (±H, ±H) --
imag too large -- (0, 0) --
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

See also

Introduction, cartesian/polar, complex operators, exp, log, pow, sqrt, cplxtrig


exp, log, pow, sqrt

exp, log, pow, sqrt - exponential, logarithm, power, square root functions for the C++ complex library

Synopsis

#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);

};

Description

The following math functions are overloaded by the complex library, where:

  • x, y, and z are of type complex.

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.

Diagnostics

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

See also

Introduction, cartesian/polar, complex_error, complex operators, cplxtrig


complex operators

complex_operators: operators for the C++ complex math library

Synopsis

#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);

};

Description

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:

  • x, y, and z are of type complex.
Arithmetic 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.

Comparison operators

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.

Assignment operators

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.

Warning

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.

See also

Introduction, cartesian/polar, complex_error, exp, log, pow, sqrt, cplxtrig


cplxtrig

cplxtrig - trigonometric and hyperbolic functions for the C++ complex library

Synopsis

#include <complex.h>

class complex {

public:
  friend complex sin(complex);
  friend complex cos(complex);

  friend complex sinh(complex);
  friend complex cosh(complex);

};

Description

The following trigonometric functions are defined for complex, where:

  • x and y are of type complex.

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.

Diagnostics

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

See also

Introduction, cartesian/polar, complex_error, complex operators, exp, log, pow, sqrt

© 3QD Developments Ltd 2013