The Complex Arithmetic Library

3

Introduction

Complex numbers are numbers made up of a real and an imaginary part. For example:


3.2 + 4i 1 + 3i 1 + 2.3i

In the degenerate case, 0 + 3i is an entirely imaginary number generally written as 3i, and 5 + 0i is an entirely real number generally written as 5. You can represent complex numbers using the complex data type.

The complex arithmetic library implements a complex number data type as a new data type. It provides all operators and many mathematical functions defined for the built-in numerical types, and also provides extensions for iostreams that allow input and output of complex numbers. The complex arithmetic library provides error handling.

Complex numbers can also be represented as an absolute value (or magnitude) and an argument (or angle). The library provides functions to convert between the real and imaginary (Cartesian) representation and the magnitude and angle (polar) representation.

The complex conjugate of a number has the opposite sign in its imaginary part.

The Complex Library

To use the complex library, include the header file complex.h in your program, and link with the -lcomplex or -library=complex option.

Type `complex`

The complex arithmetic library defines one class: class complex. An object of class complex can hold a single complex number. The complex number is constructed of two parts: the real part and the imaginary part. The numerical values of each part are held in fields of type double. Here is the relevant part of the definition of complex:


class complex { double re, im; };

The value of an object of class complex is a pair of double values. The first value represents the real part; the second value represents the imaginary part.

Constructors of Class `complex`

There are two constructors for complex. Their definitions are:


complex::complex() { re=0.0; im=0.0; } complex::complex(double r, double i = 0.0) { re=r; im=i; }

If you declare a complex variable without parameters, the first constructor is used and the variable is initialized, so that both parts are 0. The following example creates a complex variable whose real and imaginary parts are both 0:

complex aComp;

complex aComp;

You can give either one or two parameters. In either case, the second constructor is used. When you give only one parameter, it is taken as the value for the real part and the imaginary part is set to 0. For example:

complex aComp(4.533);

complex aComp(4.533);

creates a complex variable with the value:

4.533 + 0i

4.533 + 0i

If you give two values, the first is taken as the value of the real part and the second as the value of the imaginary part. For example:

complex aComp(8.999, 2.333);

complex aComp(8.999, 2.333);

creates a complex variable with the value:

8.999 + 2.333i

8.999 + 2.333i

You can also create a complex number using the polar function, which is provided in the complex arithmetic library (see "Mathematical Functions" on page 44). The polar function creates a complex value given a pair of polar coordinates, magnitude and angle.

There is no destructor for type complex.

Arithmetic Operators

The complex arithmetic library defines all the basic arithmetic operators. Specifically, the following operators work in the usual way and with the usual precedence:

+  -  /  *  =

The operator - has its usual binary and unary meanings.

In addition, you can use the following operators in the usual way:

+=  -=  *=  /=

However, these last four operators do not produce values that you can use in expressions. For example, the following does not work:


complex a, b; ... if ((a+=2)==0) {...}; // illegal b = a *= b; // illegal

You can also use the following equality operators in their regular meaning:

==  !=

When you mix real and complex numbers in an arithmetic expression, C++ uses the complex operator function and converts the real values to complex values.

Mathematical Functions

The complex arithmetic library provides a number of mathematical functions. Some are peculiar to complex numbers; the rest are complex-number versions of functions in the standard C mathematical library.

All of these functions produce a result for every possible argument. If a function cannot produce a mathematically acceptable result, it calls complex_error and returns some suitable value. In particular, the functions try to avoid actual overflow and call complex_error with a message instead. Table 3-1 and Table 3-2 describe the remainder of the complex arithmetic library functions.

Table 3-1 Complex Arithmetic Library Functions

Complex Arithmetic
Library Function
Description

double abs(const complex)

Returns the magnitude of a complex number.

double ang(const complex)

Returns the angle of a complex number.

complex conj(const complex)

Returns the complex conjugate of its argument.

double imag(const complex&)

Returns the imaginary part of a complex number.

double norm(const complex)

Returns the square of the magnitude of its argument. Faster than abs, but more likely to cause an overflow. For comparing magnitudes.

complex polar(double mag,
double ang=0.0)

Takes a pair of polar coordinates that represent the magnitude and angle of a complex number and returns the corresponding complex number.

double real(const complex&)

Returns the real part of a complex number.

Table 3-1 Complex Arithmetic Library Functions
Complex Arithmetic Library Function	Description
`double abs(const complex)`	Returns the magnitude of a complex number.
`double ang(const complex)`	Returns the angle of a complex number.
`complex conj(const complex)`	Returns the complex conjugate of its argument.
`double imag(const complex&)`	Returns the imaginary part of a complex number.
`double norm(const complex)`	Returns the square of the magnitude of its argument. Faster than `abs`, but more likely to cause an overflow. For comparing magnitudes.
`complex polar(double mag,` `double ang=0.0)`	Takes a pair of polar coordinates that represent the magnitude and angle of a complex number and returns the corresponding complex number.
`double real(const complex&)`	Returns the real part of a complex number.

Table 3-2 Complex Mathematical and Trigonometric Functions
Complex Arithmetic Library Function	Description
`complex acos(const complex)`	Returns the angle whose cosine is its argument.
`complex asin(const complex)`	Returns the angle whose sine is its argument.
`complex atan(const complex)`	Returns the angle whose tangent is its argument.
`complex cos(const complex)`	Returns the cosine of its argument.
`complex cosh(const complex)`	Returns the hyperbolic cosine of its argument.
`complex exp(const complex)`	Computes `e**x`, where `e` is the base of the natural logarithms, and `x` is the argument given to `exp`.
`complex log(const complex)`	Returns the natural logarithm of its argument.
`complex log10(const complex)`	Returns the common logarithm of its argument.
`complex pow(double b, const complex exp)` `complex pow(const complex b, int exp)` `complex pow(const complex b, double exp)` `complex pow(const complex b, const complex exp)`	Takes two arguments: `pow(`b, exp`)`. It raises b to the power of exp.
`complex sin(const complex)`	Returns the sine of its argument.
`complex sinh(const complex)`	Returns the hyperbolic sine of its argument.
`complex sqrt(const complex)`	Returns the square root of its argument.
`complex tan(const complex)`	Returns the tangent of its argument.
`complex tanh(const complex)`	Returns the hyperbolic tangent of its argument.

Error Handling

The complex library has these definitions for error handling:


extern int errno; class c_exception { ... }; int complex_error(c_exception&);

The external variable errno is the global error state from the C library. errno can take on the values listed in the standard header errno.h (see the man page perror(3)). No function sets errno to zero, but many functions set it to other values. To determine whether a particular operation fails, set errno to zero before the operation, then test it afterward.

The function complex_error takes a reference to type c_exception and is called by the following complex arithmetic library functions:

exp
log
log10
sinh
cosh

The default version of complex_error returns zero. This return of zero means that the default error handling takes place. You can provide your own replacement function complex_error which performs other error handling. Error handling is described in the man page cplxerr(3C++).

Default error handling is described in the man pages cplxtrig(3C++) and cplxexp(3C++). It is also summarized in Table 3-3

Table 3-3 Complex Arithmetic Library Functions

Complex Arithmetic Library Function
Default Error Handling Summary

exp

If overflow occurs, sets errno to ERANGE and returns a huge complex number.

log, log10

If the argument is zero, sets errno to EDOM and returns a huge complex number.

sinh, cosh

If the imaginary part of the argument causes overflow, returns a complex zero. If the real part causes overflow, returns a huge complex number. In either case, sets errno to ERANGE.

Table 3-3 Complex Arithmetic Library Functions
Complex Arithmetic Library Function	Default Error Handling Summary
`exp`	If overflow occurs, sets `errno` to `ERANGE` and returns a huge complex number.
`log, log10`	If the argument is zero, sets `errno` to `EDOM` and returns a huge complex number.
`sinh, cosh`	If the imaginary part of the argument causes overflow, returns a complex zero. If the real part causes overflow, returns a huge complex number. In either case, sets `errno` to `ERANGE`.

Input and Output

The complex arithmetic library provides default extractors and inserters for complex numbers, as shown in the following example:


ostream& operator<<(ostream&, const complex&); //inserter istream& operator>>(istream&, complex&); //extractor

See sections "Basic Structure of Iostream Interaction" on page 51 and "Output Using Iostreams" on page 53 for basic information on extractors and inserters.

For input, the complex extractor >> extracts a pair of numbers (surrounded by parentheses and separated by a comma) from the input stream and reads them into a complex object. The first number is taken as the value of the real part; the second as the value of the imaginary part. For example, given the declaration and input statement:

complex x;

cin >> x;

complex x; cin >> x;

and the input (3.45, 5), the value of x is equivalent to 3.45 + 5.0i. The reverse is true for inserters. Given complex x(3.45, 5), cout<<x prints (3.45, 5).

The input usually consists of a pair of numbers in parentheses separated by a comma; white space is optional. If you provide a single number, with or without parentheses and white space, the extractor sets the imaginary part of the number to zero. Do not include the symbol i in the input text.

The inserter inserts the values of the real and imaginary parts enclosed in parentheses and separated by a comma. It does not include the symbol i. The two values are treated as doubles.

Mixed-Mode Arithmetic

Type complex is designed to fit in with the built-in arithmetic types in mixed-mode expressions. Arithmetic types are silently converted to type complex, and there are complex versions of the arithmetic operators and most mathematical functions. For example:


int i, j; double x, y; complex a, b; a = sin((b+i)/y) + x/j;

The expression b+i is mixed-mode. Integer i is coverted to type complex via the constructor complex::complex(double,double=0), the integer first being converted to type double. The result is to be divided by y, a double, so y is also converted to complex and the complex divide operation is used. The quotient is thus type complex, so the complex sine routine is called, yielding another complex result, and so on.

Not all arithmetic operations and conversions are implicit, or even defined, however. For example, complex numbers are not well-ordered mathematically speaking, and complex numbers can be compared for equality only.

complex a, b;

a == b // OK

a != b // OK

a < b // error: operator < cannot be applied to type complex

a >= b // error: operator >= cannot be applied to type complex

complex a, b; a == b // OK a != b // OK a < b // error: operator < cannot be applied to type complex a >= b // error: operator >= cannot be applied to type complex

complex a; double f(double); f(abs(a)); // OK f(a); // error: no match for f(complex)

Efficiency

The design of the complex class addresses efficiency concerns.

The simplest functions are declared inline to eliminate function call overhead.

Several overloaded versions of functions are provided when that makes a difference. For example, the pow function has versions which take exponents of type double and int as well as complex, since the computations for the former are much simpler.

The standard C math library header math.h is included automatically when you include complex.h. The C++ overloading rules then result in efficient evaluation of expressions like this:

double x;

complex x = sqrt(x);

double x; complex x = sqrt(x);

In this example, the standard math function sqrt(double) is called, and the result is converted to type complex, rather than converting to type complex first and then calling sqrt(complex). This result falls right out of the overload resolution rules, and is precisely the result you want.

Complex Man Pages

The man pages listed in Table 3-4 comprise the remainder of the documentation of the complex arithmetic library.Table 3-4 Man Pages for Type complex Man Page Overview cplx.intro(3C++) General introduction to the complex arithmetic library cartpol(3C++) Cartesian and polar functions cplxerr(3C++) Error-handling functions cplxexp(3C++) Exponential, log, and square root functions cplxops(3C++) Arithmetic operator functions cplxtrig(3C++) Trigonometric functions

Man Page	Overview
`cplx.intro`(3C++)	General introduction to the complex arithmetic library
`cartpol`(3C++)	Cartesian and polar functions
`cplxerr`(3C++)	Error-handling functions
`cplxexp`(3C++)	Exponential, log, and square root functions
`cplxops`(3C++)	Arithmetic operator functions
`cplxtrig`(3C++)	Trigonometric functions

The Complex Arithmetic Library

3

Introduction

The Complex Library

Type complex

Constructors of Class complex

Arithmetic Operators

Mathematical Functions

Table 3-1 Complex Arithmetic Library Functions

Table 3-2 Complex Mathematical and Trigonometric Functions