.\" '\" tep
.\" to invoke 'tbl', 'eqn', 'pic' in the proper order
.\"
.\" @(#)cplx.intro.3 1.5 00/02/18 SMI;
.\"
.TH CPLX.INTRO 3CC4 "24 March 1994"
.\"
.SH NAME
cplx.intro complex \- introduction to C++ complex number math library
.SH SYNOPSIS
.LP
.nf
.ft B
#include <complex.h>
.sp .5v
class complex {
public:
	complex(double real, double imag= 0.0);
	complex();
	... \fI// remainder not shown here\fB
};

#include <iostream.h>
.sp .5v
ostream& operator<< (ostream&, const complex&);
istream& operator>> (istream&, complex&);
.ft R
.fi
.\"
.SH DESCRIPTION
.LP
This implementation of a complex number class and library is based on
the complex math library supplied by USL.
Code written for use with the USL library should work the same way
with this implementation.
.LP
Class
.B complex,
whose definition is found in header file 
.B <complex.h>,
uses a typical Cartesian coordinate implementation of mathematical
complex numbers.
The class includes:
.br
\(bu\ functions to convert between polar and Cartesian coordinates.
See 
.BR cartpol (3CC4).
.br
\(bu\ overloaded versions of the arithmetic operations,
some of which are optimized for combining real and complex operations.
See 
.BR cplxops (3CC4).
.br
\(bu\ overloaded versions of the usual trigonometric functions.
See 
.BR cplxtrig (3CC4).
.br
\(bu\ overloaded versions of the usual exponential and logarithm functions.
See 
.BR cplxexp (3CC4).
.br
\(bu\ error handling which may be overridden by the user.
See 
.BR cplxerr (3CC4).
.br
\(bu\ functions to read and write complex numbers via iostreams.
See \fBios.intro\fR(3CC4).
.SS Constructors
.TP
.B complex()
Creates a complex number initialized to (0.0, 0.0).
.TP
.B complex(x, y)
Creates a complex number initialized to (\fBx\fR, \fBy\fR),
where \fBx\fR and \fBy\fR have numerical types.
Argument \fBy\fR may be omitted, in which case its value is taken as 0.
.SS Input/Output
.LP
The library provides default input and output routines for complex.
Either or both of these may be replaced by the programmer
by writing functions with the same signatures.
The default versions are described here.
.TP
.B "input_stream >> x"
Expects the representation of a complex number to have the form
.ti +.5i
.BI ( " real " , " imag " ) 
.br
where 
.Ireal 
and 
.Iimag 
are integral or floating-point numbers
in standard C++ format.
Any amount of whitespace may preceed or follow the parentheses and comma.
If the first non-whitespace character is not `\fB(\fR', that character
will be replaced in the stream and there will be nothing further
extracted.
Otherwise, if the value is not well-formed,
extraction from the stream will stop as soon as this is determined,
and the stream will be put into a "failed" state.
(See the iostream documentation.)  In either case,
or if there is any other error condition,
complex variable \fBx\fR will get the value (0,0).
If the input is in the proper form,
\fBx\fR will get the represented complex value.
.TP
.B "output_stream << x"
Writes the value of complex \fBx\fR to the output stream in the form
expected by the input function as noted above.
.\"
.SH "SEE ALSO"
.LP
.na
.BR cartpol (3CC4),
.BR cplxerr (3CC4),
.BR cplxexp (3CC4),
.BR cplxops (3CC4),
.BR cplxtrig (3CC4),
.BR ios.intro (3CC4).
.BR intro (2),
.BR ieee_values (3),
.BR perror (3),
.I "Complex Tutorial"
.\" .TZ ????
.ad
.\"
.SH DIAGNOSTICS
In general, one of the values (0, 0),
(0, \(+-\fBHUGE_VAL\fR), (\(+-\fBHUGE_VAL\fR, 0),
or (\(+-\fBHUGE_VAL\fR, \(+-\fBHUGE_VAL\fR)
will be returned when a result is too large or is mathematically undefined.
\fBHUGE_VAL\fR is defined in the header \fB<math.h>\fR, which is
included by \fB<complex.h>\fR, and in this implementation has the value
corresponding to infinity.
See \fBieee_values\fR(3).
When such an error condition occurs, external variable \fBerrno\fR is set to
\fBEDOM\fR or \fBERANGE\fR.  See \fBperror\fR(3), \fBintro\fR(2).