Chapter Contents

Previous

Next
Standard Libraries

C++ Complex Library

The functions and operators pertaining to complex numbers are implemented by means of class complex and are contained in the C++ complex number mathematics library. The definition of class complex overloads the standard input, output, arithmetic, comparison, and assignment operators of C++, as well as the standard names of the exponential, logarithm, power, square root, and trigonometric functions (sine, cosine, hyperbolic sine, and hyperbolic cosine). Functions for converting between Cartesian and polar coordinates are also provided. This section describes the functions, classes, and operators found in class complex . Declarations for these functions and operators are contained in the header file complex.h . In the function descriptions, the form (a,b) is used to represent a complex number. This is equivalent to the mathematical expression a+bi .


Function Descriptions

The function descriptions for the complex library are organized as follows:

constructors and conversion operators
include constructors and conversion operators for complex variables.

cartesian and polar coordinate functions
include descriptions of abs() , arg() , conj() , imag() , norm() , polar() , and real() .

exponential, logarithmic, power, and square root functions
include descriptions of exp() , log() , pow() , and sqrt() .

trigonometric and hyperbolic functions
include descriptions of sin() , cos() , sinh() , and cosh() .

operators
include the operators available for the complex library ( + , * , == , and so on).

complex I/O functions
provide complex I/O, that is, the insertion and extraction operators << and >> .

Each set of function descriptions includes the following information:

In the following descriptions, specific diagnostic information is given for a function or group of functions, where appropriate. However, more general diagnostic information is not included in this book. Also, some of the complex library functions call SAS/C math library functions. If you find you need more information on error handling for math functions, or if you need more information about functions called by the complex library functions, see the SAS/C Library Reference. If you want to use signal handlers to trap overflows, see the SAS/C Library Reference, Volume 1 also.

complex()

Constructors and Conversion Operators

SYNOPSIS
#include <complex.h>
class complex
{
public:
   complex();
   complex(double real, double imag = 0.0);
};

DESCRIPTION
The following constructors are defined for class complex .

complex()
enables you to declare complex variables without initializing them. File-scope complex variables declared without an initializer have an initial value of (0,0) ; other uninitialized complex variables have an undefined initial value.

complex(double real, double imag = 0.0)
allows explicit initialization of complex variables. For example, the following two statements are valid:
complex c1(1.0, 2.0);
// The imaginary part is 0.0.
complex c2(1.0);
This constructor also allows for implicit conversion from arithmetic types to complex values. For example, the following two statements are valid:
complex c3 = 3.4; // c3 is (3.4, 0.0).
c3=10; // c3 is (10.0, 0.0).
Using this constructor, you can also create complex values within expressions. Here is an example:
// Uses complex::operator +
c2 = c3 + complex(1.2, 3.5);


abs, arg, conj, imag, norm, polar, real

Cartesian and Polar Functions

SYNOPSIS
#include <complex.h>
class complex
{
public:
   friend double abs(complex a);
   friend double arg(complex a);
   friend complex conj(complex a);
   friend double imag(complex a);
   friend double norm(complex a);
   friend complex polar(double r,
                        double t);
   friend double real(complex a);
};

DESCRIPTION
The following functions are defined for class complex , where d , r , and t are of type double and a and z are of type complex .

d = abs(a)
returns the absolute value (magnitude) of a .

d = arg(a)
returns the angle of a (measured in radians) in the half-open interval (-[pi] to [pi]].

z = conj(a)
returns the conjugation of a . If a is (x,y) , then conj(a) is (x,-y) .

d = imag(a)
returns the imaginary part of a .

d = norm(a)
returns the square of the magnitude of a .

z = polar(r, t)
returns a complex . The arguments represent a pair of polar coordinates where r is the magnitude and t is the angle (measured in radians). polar(r,t) is defined by the formula r*e i*t.

d = real(a)
returns the real part of a .


exp, log, pow, sqrt

Exponential, Logarithmic, Power, and Square Root Functions

SYNOPSIS
#include <complex.h>
class complex
{
public:
   friend complex exp(complex a);
   friend complex log(complex a);
   friend complex pow(double a, complex b);
   friend complex pow(complex a, int b);
   friend complex pow(complex a, double b);
   friend complex pow(complex a,
                      complex b);
   friend complex sqrt(complex a);
};

DESCRIPTION
The following functions are overloaded by the C++ complex library, where z is of type complex and a and b are of the types indicated by the function prototypes in the SYNOPSIS.

z = exp(a)
returns e a.

z = log(a)
returns the natural logarithm of a .

z = pow(a, b)
returns a b .

z = sqrt(a)
returns the square root of a that is contained in the first or fourth quadrant of the complex plane.

DIAGNOSTICS
The exp() and log() functions have special diagnostic considerations.

exp() function
If overflow is caused by the real part of a being small or the imaginary part of a being large, then exp(a) returns (0,0) and errno is set to ERANGE

If the real part of a is large enough to cause overflow, exp(a) returns different values under the following conditions pertaining to the sine and cosine of the imaginary part of a .

In Return Values for exp(a) , the real portion of a complex number a depends on the cos(imag(a)) and the imaginary part depends on the sin(imag(a)) . HUGE corresponds to the largest representable double .

Return Values for exp(a)
cos(imag(a))
sin(imag(a)) exp(a) returns
positive positive (HUGE, HUGE)
positive negative or 0 (HUGE, -HUGE)
negative or 0 positive (-HUGE, HUGE)
negative or 0 negative or 0 (-HUGE, -HUGE)

As you can see from this table, the translation is simple. If the cosine is positive, exp(a) returns HUGE for the real portion of a ; if the cosine is negative, exp(a) returns -HUGE for the real part. If the cosine is not positive, exp(a) returns -HUGE for the real part. The same rules hold true for the sine and the imaginary part of a . In all overflow cases, errno is set to ERANGE .

log() function
When a is (0,0), log(a) returns (-HUGE,0) and errno is set to EDOM .


sin, cos, sinh, cosh

Trigonometric and Hyperbolic Functions

SYNOPSIS
#include <complex.h>
class complex
{
public:
   friend complex sin(complex a);
   friend complex cos(complex a);
   friend complex sinh(complex a);
   friend complex cosh(complex a);
};

DESCRIPTION
The following functions are defined for class complex , where a and z are of type complex .

z = sin(a)
returns the sine of a .

z = cos(a)
returns the cosine of a .

z = sinh(a)
returns the hyperbolic sine of a .

z = cosh(a)
returns the hyperbolic cosine of a .

DIAGNOSTICS
sin(a) and cos(a) return (0,0) if the real part of a causes overflow. If the imaginary part of a is large enough to cause overflow, sin(a) and cos(a) return values as shown in Return Values for cos(a) and Return Values for sin(a) . HUGE corresponds to the largest representable double .

Return Values for cos(a)
cos(real(a))
sin(real(a)) cos(a) returns
positive or 0 positive or 0 (HUGE, -HUGE)
positive or 0 negative (HUGE, HUGE)
negative positive or 0 (-HUGE, -HUGE)
negative negative (-HUGE, HUGE)

Return Values for sin(a)
sin(real(a)) cos(real(a)) sin(a) returns
positive or 0 positive or 0 (HUGE, HUGE)
positive or 0 negative (HUGE, -HUGE)
negative positive or 0 (-HUGE, HUGE)
negative negative (-HUGE, -HUGE)

sinh(a) and cosh(a) return (0,0) if the imaginary part of a causes overflow. If the real part of a is large enough to cause overflow, sinh(a) and cosh(a) return values according to Return Values for cosh(a) and sinh(a) .

Return Values for cosh(a) and sinh(a)
cos(imag(a)) sin(imag(a))
cosh(a) and sinh(a) both return
positive or 0 positive or 0 (HUGE, HUGE)
positive or 0 negative (HUGE, -HUGE)
negative positive or 0 (-HUGE, HUGE)
negative negative (-HUGE, -HUGE)

In all overflow cases, errno is set to ERANGE .


Complex Operators

Operators for the C++ Complex Library

SYNOPSIS
#include <complex.h>
class complex
{
public:
   friend complex operator +(complex a,
                             complex b);
   friend complex operator -(complex a);
   friend complex operator -(complex a,
                             complex b);
   friend complex operator *(complex a,
                             complex b);
   friend complex operator /(complex a,
                             complex b);
   friend complex operator /(complex a,
                             double d);
   friend int operator ==(complex a,
                          complex b);
   friend int operator !=(complex a,
                          complex b);
   void operator +=(complex a);
   void operator -=(complex a);
   void operator *=(complex a);
   void operator /=(complex a);
   void operator /=(double d);
};

DESCRIPTION
The usual arithmetic operators, comparison operators, and assignment operators are overloaded for complex numbers. The usual precedence relations among these operators are in effect. In the descriptions below, a and b are of type complex and d is of type double .

Arithmetic operators
The following are the arithmetic operators.

a + b
is the arithmetic sum of a and b .

-a
is the arithmetic negation of a .

a - b
is the arithmetic difference of a and b .

a * b
is the arithmetic product of a and b .

a/b and a/d
are the arithmetic quotient of a and b or a and d .

Comparison operators
The following are the comparison operators.

a == b
is nonzero if a is equal to b ; it is zero otherwise.

a != b
is nonzero if a is not equal to b ; it is zero otherwise.

Assignment operators
The following are the assignment operators.

a += b
assigns to a the arithmetic sum of itself and b .

a -= b
assigns to a the arithmetic difference of itself and b .

a *= b
assigns to a the arithmetic product of itself and b .

a /= b and a /= d
assign to a the arithmetic quotient of themselves and b or d .

CAUTION
The assignment operators do not yield a value that can be used in an expression. For example, the following construction is not valid:
complex a, b, c;
a = (b += c);


operator << and operator >>

\> operator">

Complex I/O Functions

SYNOPSIS
#include <complex.h>
class complex
{
public:
   ostream& operator <<(ostream& os,
                        complex c);
   istream& operator >>(istream& is,
                        complex& c);
};

DEFINITION
The following functions provide insertion and extraction capabilities for complex numbers.

ostream& operator << (ostream& os,
complex c)
writes a complex number c to os . The output is formatted in the following manner:
(real-part,imag-part)

where real-part and imag-part are the real and imaginary parts of the complex number, respectively. Both real-part and imag-part are formatted as doubles. For more information, refer to the descrip tion of the operator <<(ostream&, double) in class ostream . The formatting of real-part and imag-part is controlled by flags associated with the stream. See enum format_state .

istream& operator >>(istream& is,
complex& c)
reads a formatted complex number from is into c . The istream should contain the complex number to be read in one of these formats:
(real-part,imag-part)
(real-part)

where real-part and imag-part are the real and imaginary parts of the complex number, respectively. Both real-part and imag-part should be formatted as double s. For more information, refer to the description of the operator >>(istream&, double&) in class istream. The formatting of real-part and imag-part is controlled by flags associated with the stream. See enum format_state .

Remember the following when performing complex I/O:

If your input variable represents a real number such as 5e-2 or (502), the >> operator interprets it as a complex number with an imaginary part of 0.

DIAGNOSTICS
If the istream does not contain a properly formatted complex number, operator >> sets the ios::failbit bit in the stream's I/O state.

EXAMPLES
Here is an example of using operator << :
complex c(3.4,2.1);
cout << "This is a complex: " << c << endl;
This code writes the following string to cout :
This is a complex: (3.4,2.1)
Here is an example of using operator >> . Suppose cin contains (1.2, 3.4) . Then the following code reads the value (1.2, 3.4) and the value of c becomes (1.2,3.4) .
complex c;
cin >> c;


Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.