'\" t
.\" to invoke 'tbl', 'eqn', 'pic' in the proper order
.\"
.\" @(#)cplxerr.3 1.8 00/02/18 SMI;
.\"
.TH CPLXERR 3CC4 "07 August 1997"
.\"
.SH NAME
cplxerr complex error \- error-handling functions in the C++ complex number math library
.SH SYNOPSIS
.LP
.nf
.ft B
#include <complex.h>
.sp .5v
class complex { ... };
.sp .5v
static const complex complex_zero(0.0, 0.0);
.sp .5v
const int SING		= ...;
const int OVERFLOW	= ...;
const int UNDERFLOW	= ...;
.sp .5v
class c_exception
{
public:
	c_exception(char *n, const complex& a1, const complex& a2=complex_zero);
	c_exception(unsigned char *n, const complex& a1, const complex& a2=complex_zero);
.sp .5v
	friend int complex_error(c_exception&); // user may override
private:
	int type;
	char *name;
	complex arg1, arg2;
	complex retval;
};
.ft R
.fi
.\"
.SH DESCRIPTION
.LP
Functions
.BR exp() ,
.BR log() ,
.BR log10() ,
.BR sinh() ", and"
.B cosh() 
invoke function \fBcomplex_error()\fR under the conditions
described in \fBcplxexp\fR(3CC4) and \fBcplxtrig\fR(3CC4).
If \fBcomplex_error()\fR returns zero,
the return values and setting of \fBerrno\fR will take place as described.
In addition, a message describing the kind of error,
the function which detected it,
and the value causing the error will be written to \fBcerr\fR
(see iostream documentation).
If \fBcomplex_error\fR returns non-zero, \fBerrno\fR is not set
and no message is written.

The default version of \fBcomplex_error()\fR just returns zero.
The programmer may supply a replacement version of the function
to take any action deemed appropriate.
The function takes one parameter of type
``reference to \fBc_exception\fR'',
of which the function is a friend.
.SS "class c_exception"
The class consists of the following fields:
.TP
.B "int type"
An integer describing the type of value, which has one of the values below,
declared in the header as constants:
.br
\fBSING\fR		argument singularity, such as divide by zero
.br
\fBOVERFLOW\fR	overflow range error
.br
\fBUNDERFLOW\fR	underflow range error
.br
.TP
.B "char* name"
Points to a null-terminated string containing the name of the function
where the error was detected.
.TP
.B "complex arg1, arg2"
The arguments with which the function detecting the error was invoked.
(Those functions which invoke \fBcomplex_err()\fR have only
one argument, so \fBarg2\fR will be irrelevant.)
.TP
.B "complex retval"
The default return value for the invoking function if \fBcomplex_err()\fR
does not set some other value.
.LP
A replacement version of \fBcomplex_err()\fR should return zero if
setting
.B errno
and writing to
.B cerr
are desired, or return non-zero otherwise.
The replacement could also change the \fBretval\fR field of its
\fBc_exception\fR parameter if the default return value is not
desired.
.SH EXAMPLE
.LP
Suppose we want \fBerrno\fR to be set,
but we do not want to write anything to \fBcerr\fR (or anywhere else).
Our replacement \fBcomplex_err()\fR will return non-zero,
which will prevent a message from being written,
but will also prevent \fBerrno\fR from being set.
Our function will have to set \fBerrno\fR itself.
.in +.5i
.nf
.ft B
#include <complex.h>
.sp .5v
int c_exception(c_exception& x)
{
	switch( x.type ) {
	case UNDERFLOW:
	case OVERFLOW:
		errno = ERANGE;
		break;
	case SING:
		errno = EDOM;
		break;
	}
	return 1;
}
.ft R
.fi
.in -.5i
.\"
.SH "SEE ALSO"
.LP
.na
.BR cplx.intro (3CC4),
.BR cartpol (3CC4),
.BR cplxexp (3CC4),
.BR cplxops (3CC4),
.BR cplxtrig (3CC4),
.BR intro (2),
.BR ios.intro (3CC4),
.I C++ Library Reference, 
Chapter 2, "The Complex Arithmetic Library."
.\" .TZ ????
.ad