C++ Library Reference | ![]() ![]() ![]() ![]() ![]() |
The Complex Arithmetic Library
Complex numbers are numbers made up of a real and an imaginary part. For example:
3.2 + 4i1 + 3i1 + 2.3i
In the degenerate case,
0
+
3i
is an entirely imaginary number generally written as3i
, and5
+
0i
is an entirely real number generally written as5
. You can represent complex numbers using thecomplex
data type.
Note The complex arithmetic library (libcomplex
) is available only for compatibility mode (-compat
[=4
]). In standard mode (the default mode), complex number classes with similar functionality are included with the C++ Standard LibrarylibCstd
.
2.1 The Complex Library
The complex arithmetic library implements a complex number data type as a new data type and provides:
- Operators
- Mathematical functions (defined for the built-in numerical types)
- Extensions (for iostreams that allow input and output of complex numbers)
- Error handling mechanisms
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.
2.1.1 Using the Complex Library
To use the complex library, include the header file
complex.h
in your program, and compile and link with the-library=complex
option.2.2 Type
complex
The complex arithmetic library defines one class: class
complex
. An object of classcomplex
can hold a single complex number. The complex number is constructed of two parts:The numerical values of each part are held in fields of type
double
. Here is the relevant part of the definition ofcomplex
:The value of an object of class
complex
is a pair ofdouble
values. The first value represents the real part; the second value represents the imaginary part.2.2.1 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 both0
:
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);creates a complex variable with the value:
4.533 + 0iIf 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);creates a complex variable with the value:
8.999 + 2.333iYou can also create a complex number using the
polar
function, which is provided in the complex arithmetic library (see Section 2.3 "Mathematical Functions"). Thepolar
function creates a complex value given a pair of polar coordinates, magnitude and angle.There is no destructor for type
complex
.2.2.2 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) {...}; // illegalb = a *= b; // illegalYou 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.
2.3 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 callcomplex_error
with a message instead. The following tables describe the remainder of the complex arithmetic library functions.
2.4 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 headererrno.h
(see the man pageperror
(3)). No function setserrno
to zero, but many functions set it to other values.To determine whether a particular operation fails:
1. Seterrno
to zero before the operation.2. Test the operation.The function
complex_error
takes a reference to typec_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 functioncomplex_error
that performs other error handling. Error handling is described in the man pagecplxerr
(3CC4).Default error handling is described in the man pages
cplxtrig
(3CC4) andcplxexp
(3CC4) It is also summarized in the following table.
2.5 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&); //inserteristream& operator>>(istream&, complex&); //extractorFor basic information on extractors and inserters, see Section 3.2 "Basic Structure of iostream Interaction" and Section 3.3.1 "Output Using iostream".
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;and the input
(3.45,
5)
, the value ofx
is equivalent to3.45
+
5.0i
. The reverse is true for inserters. Givencomplex 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 asdouble
s.2.6 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 typecomplex
, and there arecomplex
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. Integeri
is converted to typecomplex
via the constructorcomplex::complex(double,double=0)
, the integer first being converted to typedouble
. The result is to be divided byy
, adouble
, soy
is also converted tocomplex
and the complex divide operation is used. The quotient is thus typecomplex
, so the complex sine routine is called, yielding anothercomplex
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; // OKa != b; // OKa < b; // error: operator < cannot be applied to type complexa >= b; // error: operator >= cannot be applied to type complexSimilarly, there is no automatic conversion from type
complex
to any other type, because the concept is not well-defined. You can specify whether you want the real part, imaginary part, or magnitude, for example.
complex a;double f(double);f(abs(a)); // OKf(a); // error: no match for f(complex)2.7 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 that take exponents of typedouble
andint
as well ascomplex
, since the computations for the former are much simpler.The standard C math library header
math.h
is included automatically when you includecomplex.h
. The C++ overloading rules then result in efficient evaluation of expressions like this:
double x;complex x = sqrt(x);In this example, the standard math function
sqrt(double)
is called, and the result is converted to typecomplex
, rather than converting to typecomplex
first and then callingsqrt(complex)
. This result falls right out of the overload resolution rules, and is precisely the result you want.2.8 Complex Man Pages
The remaining documentation of the complex arithmetic library consists of the man pages listed in the following table.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |