<complex>

Description
Synopsis
Macros
Classes
Template functions

Description

Include the standard header <complex> to define template class complex and a host of supporting template functions. Unless otherwise specified, functions that can return multiple values return an imaginary part in the half-open interval (-pi, pi].

Synopsis

namespace std {
#define __STD_COMPLEX

        // TEMPLATE CLASSES
template<class T>
    class complex;
template<>
    class complex<float>;
template<>
    class complex<double>;
template<>
    class complex<long double>;

        // TEMPLATE FUNCTIONS
template<class T>
    complex<T> operator+(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator+(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator+(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator-(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator-(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator-(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator*(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator*(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator*(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator/(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator/(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator/(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator+(const complex<T>& lhs);
template<class T>
    complex<T> operator-(const complex<T>& lhs);
template<class T>
    bool operator==(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    bool operator==(const complex<T>& lhs,
        const T& rhs);
template<class T>
    bool operator==(const T& lhs,
        const complex<T>& rhs);
template<class T>
    bool operator!=(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    bool operator!=(const complex<T>& lhs,
        const T& rhs);
template<class T>
    bool operator!=(const T& lhs,
        const complex<T>& rhs);
template<class U, class E, class T>
    basic_istream<E, T>&
        operator>>(basic_istream<E, T>& is,
            complex<U>& x);
template<class U, class E, class T>
    basic_ostream<E, T>&
        operator<<(basic_ostream<E, T>& os,
            const complex<U>& x);
template<class T>
    T real(const complex<T>& x);
template<class T>
    T imag(const complex<T>& x);
template<class T>
    T abs(const complex<T>& x);
template<class T>
    T arg(const complex<T>& x);
template<class T>
    T norm(const complex<T>& x);
template<class T>
    complex<T> conj(const complex<T>& x);
template<class T>
    complex<T> polar(const T& rho, const T& theta = 0);
template<class T>
    complex<T> cos(const complex<T>& x);
template<class T>
    complex<T> cosh(const complex<T>& x);
template<class T>
    complex<T> exp(const complex<T>& x);
template<class T>
    complex<T> log(const complex<T>& x);
template<class T>
    complex<T> log10(const complex<T>& x);
template<class T>
    complex<T> pow(const complex<T>& x, int y);
template<class T>
    complex<T> pow(const complex<T>& x, const T& y);
template<class T>
    complex<T> pow(const complex<T>& x,
        const complex<T>& y);
template<class T>
    complex<T> pow(const T& x, const complex<T>& y);
template<class T>
    complex<T> sin(const complex<T>& x);
template<class T>
    complex<T> sinh(const complex<T>& x);
template<class T>
    complex<T> sqrt(const complex<T>& x);

namespace tr1 {
    template<class T>
        complex<T> acos(complex<T>& x);
    template<class T>
        complex<T> asin(complex<T>& x);
    template<class T> 
        complex<T> atan(complex<T>& x);
    template<class T> 
        complex<T> acosh(complex<T>& x);
    template<class T> 
        complex<T> asinh(complex<T>& x);
    template<class T> 
        complex<T> atanh(complex<T>& x);
    template<class T> 
        complex<T> fabs(complex<T>& x);
    } // namespace tr1
} // namespace std

Macros

__STD_COMPLEX

#define __STD_COMPLEX

The macro is defined, with an unspecified expansion, to indicate compliance with the specifications of this header.

Classes

complex
complex<float>
complex<double>
complex<long double>

complex

Description
Synopsis
Constructor
complex::complex
Member functions
complex::imag
complex::operator*=
complex::operator+=
complex::operator-=
complex::operator/=
complex::operator=
complex::real
complex::value_type
Description

The template class describes an object that stores two objects of type T, one that represents the real part of a complex number and one that represents the imaginary part. An object of class T:

In particular, no subtle differences may exist between copy construction and default construction followed by assignment. And none of the operations on objects of class T may throw exceptions.

Explicit specializations of template class complex exist for the three floating-point types. In this implementation, a value of any other type T is type cast to double for actual calculations, with the double result assigned back to the stored object of type T.

Synopsis
template<class T>
    class complex {
public:
    typedef T value_type;
    T real() const;
    T imag() const;
    complex(const T& re = 0, const T& im = 0);
    template<class U>
        complex(const complex<U>& x);
    template<class U>
        complex& operator=(const complex<U>& rhs);
    template<class U>
        complex& operator+=(const complex<U>& rhs);
    template<class U>
        complex& operator-=(const complex<U>& rhs);
    template<class U>
        complex& operator*=(const complex<U>& rhs);
    template<class U>
        complex& operator/=(const complex<U>& rhs);
    complex& operator=(const T& rhs);
    complex& operator+=(const T& rhs);
    complex& operator-=(const T& rhs);
    complex& operator*=(const T& rhs);
    complex& operator/=(const T& rhs);
    friend complex<T>
        operator+(const complex<T>& lhs, const T& rhs);
    friend complex<T>
        operator+(const T& lhs, const complex<T>& rhs);
    friend complex<T>
        operator-(const complex<T>& lhs, const T& rhs);
    friend complex<T>
        operator-(const T& lhs, const complex<T>& rhs);
    friend complex<T>
        operator*(const complex<T>& lhs, const T& rhs);
    friend complex<T>
        operator*(const T& lhs, const complex<T>& rhs);
    friend complex<T>
        operator/(const complex<T>& lhs, const T& rhs);
    friend complex<T>
        operator/(const T& lhs, const complex<T>& rhs);
    friend bool
        operator==(const complex<T>& lhs, const T& rhs);
    friend bool
        operator==(const T& lhs, const complex<T>& rhs);
    friend bool
        operator!=(const complex<T>& lhs, const T& rhs);
    friend bool
        operator!=(const T& lhs, const complex<T>& rhs);
    };
Constructor
complex::complex

complex(const T& re = 0, const T& im = 0);
template<class U>
    complex(const complex<U>& x);

The first constructor initializes the stored real part to re and the stored imaginary part to im. The second constructor initializes the stored real part to x.real() and the stored imaginary part to x.imag().

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex(const complex<U>& x);

is replaced by:

complex(const complex& x);

which is the copy constructor.

Member functions
complex::imag

T imag() const;

The member function returns the stored imaginary part.

complex::operator*=

template<class U>
    complex& operator*=(const complex<U>& rhs);
complex& operator*=(const T& rhs);

The first member function replaces the stored real and imaginary parts with those corresponding to the complex product of *this and rhs. It then returns *this.

The second member function multiplies both the stored real part and the stored imaginary part with rhs. It then returns *this.

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex& operator*=(const complex<U>& rhs);

is replaced by:

complex& operator*=(const complex& rhs);
complex::operator+=

template<class U>
    complex& operator+=(const complex<U>& rhs);
complex& operator+=(const T& rhs);

The first member function replaces the stored real and imaginary parts with those corresponding to the complex sum of *this and rhs. It then returns *this.

The second member function adds rhs to the stored real part. It then returns *this.

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex& operator+=(const complex<U>& rhs);

is replaced by:

complex& operator+=(const complex& rhs);
complex::operator-=

template<class U>
    complex& operator-=(const complex<U>& rhs);
complex& operator-=(const T& rhs);

The first member function replaces the stored real and imaginary parts with those corresponding to the complex difference of *this and rhs. It then returns *this.

The second member function subtracts rhs from the stored real part. It then returns *this.

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex& operator-=(const complex<U>& rhs);

is replaced by:

complex& operator-=(const complex& rhs);
complex::operator/=

template<class U>
    complex& operator/=(const complex<U>& rhs);
complex& operator/=(const T& rhs);

The first member function replaces the stored real and imaginary parts with those corresponding to the complex quotient of *this and rhs. It then returns *this.

The second member function multiplies both the stored real part and the stored imaginary part with rhs. It then returns *this.

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex& operator/=(const complex<U>& rhs);

is replaced by:

complex& operator/=(const complex& rhs);
complex::operator=

template<class U>
    complex& operator=(const complex<U>& rhs);
complex& operator=(const T& rhs);

The first member function replaces the stored real part with rhs.real() and the stored imaginary part with rhs.imag(). It then returns *this.

The second member function replaces the stored real part with rhs and the stored imaginary part with zero. It then returns *this.

In this implementation, if a translator does not support member template functions, the template:

template<class U>
    complex& operator=(const complex<U>& rhs);

is replaced by:

complex& operator=(const complex& rhs);

which is the default assignment operator.

complex::real

T real() const;

The member function returns the stored real part.

complex::value_type

typedef T value_type;

The type is a synonym for the template parameter T.

complex<float>

template<>
    class complex<float> {
public:
    complex(float re = 0, float im = 0);
    explicit complex(const complex<double>& x);
    explicit complex(const complex<long double>& x);
// rest same as template class complex
    };

The explicitly specialized template class describes an object that stores two objects of type float, one that represents the real part of a complex number and one that represents the imaginary part. The explicit specialization differs only in the constructors it defines. The first constructor initializes the stored real part to re and the stored imaginary part to im. The remaining two constructors initialize the stored real part to x.real() and the stored imaginary part to x.imag().

complex<double>

template<>
    class complex<double> {
public:
    complex(double re = 0, double im = 0);
    complex(const complex<float>& x);
    explicit complex(const complex<long double>& x);
// rest same as template class complex
    };

The explicitly specialized template class describes an object that stores two objects of type double, one that represents the real part of a complex number and one that represents the imaginary part. The explicit specialization differs only in the constructors it defines. The first constructor initializes the stored real part to re and the stored imaginary part to im. The remaining two constructors initialize the stored real part to x.real() and the stored imaginary part to x.imag().

complex<long double>

template<>
    class complex<long double> {
public:
    complex(long double re = 0, long double im = 0);
    complex(const complex<float>& x);
    complex(const complex<double>& x);
// rest same as template class complex
    };

The explicitly specialized template class describes an object that stores two objects of type long double, one that represents the real part of a complex number and one that represents the imaginary part. The explicit specialization differs only in the constructors it defines. The first constructor initializes the stored real part to re and the stored imaginary part to im. The remaining two constructors initialize the stored real part to x.real() and the stored imaginary part to x.imag().

Template functions

abs
acos
acosh
arg
asin
asinh
atan
atanh
conj
cos
cosh
exp
fabs
imag
log
log10
norm
operator!=
operator*
operator+
operator-
operator/
operator<<
operator==
operator>>
polar
pow
real
sin
sinh
sqrt
tan
tanh

abs

template<class T>
    T abs(const complex<T>& x);

The function returns the magnitude of x.

acos

template<class T>
    complex<T> acos(complex<T>& x);

The acos function computes the complex arc cosine of x, with branch cuts outside the interval [-1, +1] along the real axis.

As of z/OS® V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function acos produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
acos(complex<float>& x);
float complex cacosf(float complex z);
template <> complex<double> 
acos(complex<double>& x);
double complex cacos(double complex z);
template <> complex<long double> 
acos(complex<long double>& x);
long double complex 
cacosl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

acosh

template<class T>
    complex<T> acosh(complex<T>& x);

The acosh function computes the complex arc hyperbolic cosine of the x parameter, with a branch cut at values less than 1 along the real axis.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function acosh produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
acosh(complex<float>& x);
float complex cacoshf(float complex z);
template <> complex<double> 
acosh(complex<double>& x);
double complex cacosh(double complex z);
template <> complex<long double> 
acosh(complex<long double>& x);
long double complex 
cacoshl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

arg

template<class T>
    T arg(const complex<T>& x);

The function returns the phase angle of x.

asin

template<class T>
    complex<T> asin(complex<T>& x);

The asin function computes the complex arc sine x, with branch cuts outside the interval [-1, +1] along the real axis.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function asin produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
asin(complex<float>& x);
float complex casinf(float complex z);
template <> complex<double> 
asin(complex<double>& x);
double complex casin(double complex z);
template <> complex<long double> 
asin(complex<long double>& x);
long double complex 
casinl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

asinh

template<class T>
    complex<T> asinh(complex<T>& x);

The asinh function computes the complex arc hyperbolic sine of the x parameter, with branch cuts outside the interval [-i, +i] along the imaginary axis.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function asinh produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
asinh(complex<float>& x);
float complex casinhf(float complex z);
template <> complex<double> 
asinh(complex<double>& x);
double complex casinh(double complex z);
template <> complex<long double> 
asinh(complex<long double>& x);
long double complex 
casinhl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

atan

template<class T>
    complex<T> atan(complex<T>& x);

The atan function computes the complex arc tangent of x, with branch cuts outside the interval [-i, +i] along the imaginary axis.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function atan produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
atan(complex<float>& x);
float complex catanf(float complex z);
template <> complex<double> 
atan(complex<double>& x);
double complex catan(double complex z);
template <> complex<long double> 
atan(complex<long double>& x);
long double complex 
catanl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

atanh

template<class T>
    complex<T> atanh(complex<T>& x);

The atanh function computes the complex arc hyperbolic tangent of x, with branch cuts outside the interval [-1, +1] along the real axis.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function atanh produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
atanh(complex<float>& x);
float complex catanhf(float complex z);
template <> complex<double> 
atanh(complex<double>& x);
double complex catanh(double complex z);
template <> complex<long double> 
atanh(complex<long double>& x);
long double complex 
catanhl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

conj

template<class T>
    complex<T> conj(const complex<T>& x);

The function returns the conjugate of x.

cos

template<class T>
    complex<T> cos(const complex<T>& x);

The function returns the cosine of x.

cosh

template<class T>
    complex<T> cosh(const complex<T>& x);

The function returns the hyperbolic cosine of x.

exp

template<class T>
    complex<T> exp(const complex<T>& x);

The function returns the exponential of x.

fabs

template<class T>
    complex<T> fabs(complex<T>& x);

The fabs function computes the complex absolute value of x.

As of z/OS V1R12 XL C/C++ compiler, you can use C99 library facilities in your C++ code. This new TR1 template function fabs produces the same results as the existing C99 functions, as indicated in the following table.

TR1 template function Corresponding C99 function
template <> complex<float> 
fabs(complex<float>& x);
float complex cabsf(float complex z);
template <> complex<double> 
fabs(complex<double>& x);
double complex cabs(double complex z);
template <> complex<long double> 
fabs(complex<long double>& x);
long double complex 
cabsl(long double complex z);
Note:
To enable the TR1 headers, you must define the macro __IBMCPP_TR1__ as 1.

imag

template<class T>
    T imag(const complex<T>& x);

The function returns the imaginary part of x.

log

template<class T>
    complex<T> log(const complex<T>& x);

The function returns the logarithm of x. The branch cuts are along the negative real axis.

log10

template<class T>
    complex<T> log10(const complex<T>& x);

The function returns the base 10 logarithm of x. The branch cuts are along the negative real axis.

norm

template<class T>
    T norm(const complex<T>& x);

The function returns the squared magnitude of x.

operator!=

template<class T>
    bool operator!=(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    bool operator!=(const complex<T>& lhs,
        const T& rhs);
template<class T>
    bool operator!=(const T& lhs,
        const complex<T>& rhs);

The operators each return true only if real(lhs) != real(rhs) || imag(lhs) != imag(rhs).

operator*

template<class T>
    complex<T> operator*(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator*(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator*(const T& lhs,
        const complex<T>& rhs);

The operators each convert both operands to the return type, then return the complex product of the converted lhs and rhs.

operator+

template<class T>
    complex<T> operator+(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator+(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator+(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator+(const complex<T>& lhs);

The binary operators each convert both operands to the return type, then return the complex sum of the converted lhs and rhs.

The unary operator returns lhs.

operator-

template<class T>
    complex<T> operator-(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator-(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator-(const T& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator-(const complex<T>& lhs);

The binary operators each convert both operands to the return type, then return the complex difference of the converted lhs and rhs.

The unary operator returns a value whose real part is -real(lhs) and whose imaginary part is -imag(lhs).

operator/

template<class T>
    complex<T> operator/(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    complex<T> operator/(const complex<T>& lhs,
        const T& rhs);
template<class T>
    complex<T> operator/(const T& lhs,
        const complex<T>& rhs);

The operators each convert both operands to the return type, then return the complex quotient of the converted lhs and rhs.

operator<<

template<class U, class E, class T>
    basic_ostream<E, T>&
        operator<<(basic_ostream<E, T>& os,
            const complex<U>& x);

The template function inserts the complex value x in the output stream os, effectively by executing:

basic_ostringstream<E, T> ostr;
ostr.flags(os.flags());
ostr.imbue(os.imbue());
ostr.precision(os.precision());
ostr << '(' << real(x) << ','
    << imag(x) << ')';
os << ostr.str().c_str();

Thus, if os.width() is greater than zero, any padding occurs either before or after the parenthesized pair of values, which itself contains no padding. The function returns os.

operator==

template<class T>
    bool operator==(const complex<T>& lhs,
        const complex<T>& rhs);
template<class T>
    bool operator==(const complex<T>& lhs,
        const T& rhs);
template<class T>
    bool operator==(const T& lhs,
        const complex<T>& rhs);

The operators each return true only if real(lhs) == real(rhs) && imag(lhs) == imag(rhs).

operator>>

template<class U, class E, class T>
    basic_istream<E, T>&
        operator>>(basic_istream<E, T>& is,
            complex<U>& x);

The template function attempts to extract a complex value from the input stream is, effectively by executing:

is >> ch && ch == '('
    && is >> re >> ch && ch == ','
    && is >> im >> ch && ch == ')'

Here, ch is an object of type E, and re and im are objects of type U.

If the result of this expression is true, the function stores re in the real part and im in the imaginary part of x. In any event, the function returns is.

polar

template<class T>
    complex<T> polar(const T& rho,
        const T& theta = 0);

The function returns the complex value whose magnitude is rho and whose phase angle is theta.

pow

template<class T>
    complex<T> pow(const complex<T>& x, int y);
template<class T>
    complex<T> pow(const complex<T>& x,
        const T& y);
template<class T>
    complex<T> pow(const complex<T>& x,
        const complex<T>& y);
template<class T>
    complex<T> pow(const T& x,
        const complex<T>& y);

The functions each effectively convert both operands to the return type, then return the converted x to the power y. The branch cut for x is along the negative real axis.

real

template<class T>
    T real(const complex<T>& x);

The function returns the real part of x.

sin

template<class T>
    complex<T> sin(const complex<T>& x);

The function returns the sine of x.

sinh

template<class T>
    complex<T> sinh(const complex<T>& x);

The function returns the hyperbolic sine of x.

sqrt

template<class T>
    complex<T> sqrt(const complex<T>& x);

The function returns the square root of x, with phase angle in the half-open interval (-pi/2, pi/2]. The branch cuts are along the negative real axis.

tan

template<class T>
    complex<T> tan(const complex<T>& x);

The function returns the tangent of x.

tanh

template<class T>
    complex<T> tanh(const complex<T>& x);

The function returns the hyperbolic tangent of x.

Copyright note

Certain materials included or referred to in this document are copyright P.J. Plauger and/or Dinkumware, Ltd. or are based on materials that are copyright P.J. Plauger and/or Dinkumware, Ltd.

Notwithstanding the meta-data for this document, copyright information for this document is as follows:

Copyright © IBM Corp. 1999, 2010. & Copyright © P.J. Plauger and/or Dinkumware, Ltd. 1992-2006.