The ti(complex) container defines the standard operations that can be
performed on i(complex numbers). Before using tt(complex) containers the
header file tthi(complex) must be included.

The complex number's real and imaginary types are specified as the container's
data type. Examples:
        verb(    complex<double>
    complex<int>
    complex<float>)

Note that the real and imaginary parts of complex numbers have the same
datatypes.

When initializing (or assigning) a complex object, the i(imaginary part)
may be omitted from the initialization or assignment resulting in its value
being 0 (zero). By default, both parts are zero.

    Below it is silently assumed that the used tt(complex) type is
tt(complex<double>). Given this assumption, complex numbers may be initialized
as follows:
    itemization(
    itt(target):   A default initialization: real and imaginary parts are 0.
    itt(target(1)): The i(real part) is 1, imaginary part is 0
    itt(target(0, 3.5)): The real part is 0, imaginary part is 3.5
    itt(target(source)): tt(target) is initialized with the values of
tt(source).
    )
    Anonymous complex values may also be used. In the next example two
anonymous complex values are pushed on a stack of complex numbers, to be
popped again thereafter:
        verbinclude(-a examples/complexstack.cc)

    The following member functions and operators are defined for complex
numbers (below, tt(value) may be either a primitive i(scalar type) or a
tt(complex) object):
    itemization(
        it() Apart from the standard container operators, the following
operators are supported from the tt(complex) container.
        itemization(
        ithtq(operator+)(complex operator+(value))( this
member returns the sum of the current tt(complex) container and tt(value).)
        ithtq(operator-)(complex operator-(value))( this
member returns the difference between the current tt(complex) container and
tt(value).)
        ithtq(operator*)(complex operator*(value))( this
member returns the product of the current tt(complex) container and
tt(value).)
        ithtq(operator/)(complex operator/(value))( this
member returns the quotient of the current tt(complex) container and
tt(value).)
        ithtq(operator+=)(complex operator+=(value))( this
member adds tt(value) to the current tt(complex) container, returning the
new value.)
        ithtq(operator-=)(complex operator-=(value))(
this member subtracts tt(value) from the current tt(complex) container,
returning the new value.)
        ithtq(operator*=)(complex operator*=(value))( this
member multiplies the current tt(complex) container by tt(value), returning
the new value)
        ithtq(operator/=)(complex operator/=(value))( this
member divides the current tt(complex) container by tt(value), returning the
new value.)
        )
        ithtq(real)(Type real())(returns the i(real part) of a
complex number.)
        ithtq(imag)(Type imag())(returns the i(imaginary part)
of a complex number.)
        it() Several i(mathematical functions) are available for the
tt(complex) container, such as ti(abs), ti(arg), ti(conj), ti(cos),
ti(cosh), ti(exp), ti(log), ti(norm), ti(polar), ti(pow),
ti(sin), ti(sinh) and ti(sqrt). All these functions are free functions,
not member functions, accepting complex numbers as their arguments. For
example,
    verb(abs(complex<double>(3, -5));
pow(target, complex<int>(2, 3));)

it() Complex numbers may be hi(operator>>) extracted from tt(istream)
objects and inserted hi(operator<<) into tt(ostream) objects. The insertion
results in an i(ordered pair) tt((x, y)), in which tt(x) represents the real
part and tt(y) the imaginary part of the complex number. The same form may
also be used when extracting a complex number from an tt(istream)
object. However, simpler forms are also allowed. E.g., when extracting
tt(1.2345) the imaginary part is set to 0.
    )
