Compaq C++
Compaq C++
Class Library Reference Manual
Order Number:
AA-PM9XD-TE
June 2000
This document describes a library of C++ classes.
Revision/Update Information:
This is a revised manual.
Software Version:
C++ Version 5.3 or later
C++ Class Library Version 4.0
Compaq Computer Corporation
Houston, Texas
First Printing, September 1992 Third Revision, June 2000
© 2000 Compaq Computer Corporation.
COMPAQ, the Compaq logo, and Alpha, DEC, Ladebug, OpenVMS, Tru64 UNIX,
and VMS are registered in the U.S. Patent and Trademark Office.
The following are third-party trademarks:
AT&T is a registered trademark of American Telephone &
Telegraph Company.
UNIX is a registered trademark in the United States and other
countries, licensed exclusively through X/Open Company, Ltd.
All other product names mentioned herein may be trademarks or
registered trademarks of their respective companies.
Compaq shall not be liable for technical or editorial errors or
omissions contained herein. The information in this document is subject
to change without notice.
Confidential computer software. Valid license from Compaq required for
possession, use or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
This document is available on CD-ROM.
Preface
This manual describes the library of classes supplied with C++ Version
5.6 for Compaq Tru64 UNIX systems. It contains detailed information on
members of these classes (including member functions) and information
on other associated functions, variables, and macros.
Intended Audience
This manual is intended for experienced programmers who have a basic
understanding of the C++ language, and who are using C++ with the
Compaq Tru64 UNIX operating system in either a single or multiple platform
environment. Some familiarity with the operating system is assumed.
Document Structure
This manual consists of an introductory chapter and 10 chapters
describing each of the packages of predefined classes supplied with the
C++ compiler.
C++ Documents
The following documents are provided in the C++ documentation set:
Stroustrup, The C++ Programming Language, 3rd Edition, Addison-Wesley, 1997
|
Provides an exhaustive introduction to the C++ programming language,
and includes the text but not the annotation of The Annotated C++ Reference Manual.
|
Using C++ for Compaq Tru64 UNIX Systems
|
Describes the specifics of DIGITAL's C++ implementation.
|
Compaq C++ Installation Guide for Tru64 UNIX
|
Describes how to install C++ on your system.
|
C++ Command Reference Pages
|
Provides references for C++ commands and libraries.
|
Musser and Saini, STL Tutorial and Reference Guide, Addison-Wesley,
1995
|
Describes how to use the Standard Templates Library (STL).
|
Related Documents
The following documents are not included in the C++ documentation set;
refer to them for additional information about the C++ programming
language, C, or Compaq Tru64 UNIX programming.
The Annotated C++ Reference Manual
|
Contains the definitive language description of C++. The core text is
the same as in the "r" section of
The C++ Programming Language, 2nd Edition, but with additional
annotation and commentary.
|
Compaq Tru64 UNIX Guide to Languages and Programming
|
Describes the programming environment, languages, and tools for Compaq
Tru64 UNIX systems.
|
C User's Guide for Compaq Tru64 UNIX Systems
|
Provides information on using the C preprocessor, the C compiler, and
the
ld
linker to compile and run C programs on a Compaq Tru64 UNIX system.
|
Compaq Tru64 UNIX
Programmer's Guide
|
Describes the programming environment for Compaq Tru64 UNIX.
|
C Language Reference Manual
|
Provides a complete technical description of the C language, as
specified by the ANSI X3J11 committee. This manual also fully describes
all extensions to this standard implemented in C.
|
Ladebug Debugger Manual
|
Describes how to use DIGITAL's Ladebug debugger.
|
Conventions
Table 1 lists the conventions used in this manual.
Table 1 Conventions Used in this Manual
Convention |
Description |
class complex {
.
.
.
};
|
A vertical ellipsis indicates that some intervening program code or
output is not shown. Only the more pertinent material is shown in the
example.
|
,...
|
A horizontal ellipsis in a syntax description indicates that you can
enter additional parameters, options, or values. A comma preceding the
ellipsis indicates that successive items must be separated by commas.
|
The
complex
class...
The
get()
function...
|
Monospaced type denotes the names of C++ language elements, and also
the names of classes, members, and nonmembers. Monospaced type is also
used in text to reference code elements displayed in examples.
|
italic
|
Italic type denotes the names of variables that appear as parameters or
in arguments to functions.
|
boldface
|
Boldface type in text indicates the first instance of terms defined in
text.
|
UPPERCASE
lowercase
|
The Compaq Tru64 UNIX operating system differentiates between uppercase
and lowercase characters. Literal strings that appear in examples,
syntax descriptions, and function definitions must be typed exactly as
shown.
|
Reader's Comments
You may send your comments or suggestions regarding this manual, or any
C++ document, by electronic mail to the following Internet address:
-
compaq_cxx@compaq.com
Chapter 1 Overview
The C++ Class Library is a set of headers and other files implementing a
collection of basic C++ classes. In the library, these classes are
arranged in functionally related groups called
packages.
The C++ Class Library makes use of other run-time libraries. To ensure
that all necessary libraries are linked into the executable image,
certain switches need to be provided to the linker through the
cxx
command. For detailed information on the switches to use, see
Using Compaq C++ for Tru64 UNIX.
Note
Identifiers beginning with
cxxl
or
CXXL
are reserved for the C++ Class Library and should not be used by
customer programs except as specified in this manual.
|
1.1 Thread Safe Programming
Developers of multithreaded applications should note the following:
- Internal class library data is thread safe; multiple threads can
access the C++ Class Library simultaneously without compromising the
integrity of the internal data.
- The predefined stream objects,
cerr
,
cin
,
clog
, and
cout
are thread safe. However, you need to provide synchronization around
sequences of operations on these objects. For more information on
synchronizing access to the predefined stream objects, see Chapter 4.
- User-defined objects are not thread safe; users must provide
synchronization for such objects if they are shared between threads.
For more information on synchronizing access to user-defined objects,
see Chapter 6.
- The
ios
class member function
sync_with_stdio()
is not thread safe; if your application calls this function, the call
must come before any threads use the predefined stream objects:
cerr
,
cin
,
clog
, or
cout
.
- Generation of error messages within the vector package is not
thread safe; the package uses static data members to handle the current
error message and there is no synchronization between threads. Digital
recommends that you define a single Mutex object to synchronize all use
of the vector package.
- The task package is not thread safe; only one task can execute at a
time.
1.2 Using RMS Attributes with iostreams
The Class Library class
fstream
constructors amd
open()
member function do not support different RMS attributes, for example,
creating a stream-lf file.
To work around this restriction, use the C library
creat()
or
open()
call, which returns a file descriptor, and then use the
fstream
constructor, which accepts a file descriptor as its argument. For
example:
#include <fstream.hxx>
int main()
{
int fp;
// use either creat or open
//if ( !(fp= creat("output_file.test", 0, "rfm=stmlf")) )
if ( !(fp= open("output_file.test", O_WRONLY | O_CREAT | O_TRUNC , 0,
"rfm=stmlf")) )
perror("open");
ofstream output_file(fp); // use special constructor which takes
// a file descriptor as argument
// ...
}
|
1.3 Class Library Restrictions
The following are restrictions in the C++ Class Library:
- No Class Library support for 128-bit long doubles
The Class
Library does not include support for 128-bit long doubles.
- Conflict with redefinition of
clear()
If your program includes both
<curses.h>
and
<iostream.hxx>
, Compaq C++ might fail to compile your program because
clear()
is defined by both header files. In
<curses.h>
,
clear()
is defined as a macro whereas in
<iostream.hxx>
clear()
is defined as a member function. Workarounds: If your program
does not use either
clear()
or uses the <curses.h>
clear()
, include the
<iostream.hxx>
header first, followed by
<curses.h>
. If your program uses the
ios::clear()
function, undefine the
clear()
macro directly after the
#include <curses.h>
statement.
Chapter 2 complex Package
The complex package provides ways to perform arithmetical operations,
such as initialization, assignment, input, and output, on complex
values (that is, numbers with a real part and an imaginary part).
Additionally, this package supports operations that are unique to
complex values, such as principal argument operations, conjugate
operations, and conversions to and from polar coordinates.
With the
c_exception
class and its
c_exception
function, the complex package also provides a mechanism for reporting
and handling complex arithmetical errors.
The complex package makes use of other packages. To ensure that all
necessary libraries are linked into the executable program image,
certain switches need to be provided to the linker through the
cxx
command. For detailed information on the switches to use, see
Using Compaq C++ for Tru64 UNIX.
Global Declarations
These declarations are used by the complex package but they are not
members of the
complex
class.
Header
#include <complex.hxx>
Alternative Header
#include <complex.h>
Declarations
typedef int (*cxxl_p_complex_error_t)(c_exception &error_information);
static const complex_zero (0, 0);
cxxl_p_complex_error_t set_complex_error(cxxl_p_complex_error_t
p_complex_error);
|
Type
cxxl_p_complex_error_t
Is the type of the
complex_error
function.
Data
static const complex_zero (0, 0)
Is a constant object of type
complex
and value 0 created in each module that uses the complex package.
Function
cxxl_p_complex_error_t set_complex_error (cxxl_p_complex_error_t
p_complex_error)
Causes the function pointed to by
p_complex_error
to be called instead of the
complex_error
function on subsequent complex arithmetical errors. If
set_complex_error()
previously has not been called, then it returns 0; otherwise, it
returns the address of the last function passed to it.
See the Other Function section of
c_exception
class for a description of the error-handling function.
complex class
Provides a representation of, and lets you perform operations on,
complex values.
Header
#include <complex.hxx>
Alternative Header
#include <complex.h>
Declaration
class complex
{
friend complex polar(double, double = 0);
friend double abs(const complex &);
friend double norm(const complex &);
friend double arg(const complex &);
friend double arg1(const complex &);
friend complex conj(const complex &);
friend complex sin(const complex &);
friend complex sinh(const complex &); // c_exception OVERFLOW
friend complex cos(const complex &);
friend complex cosh(const complex &); // c_exception OVERFLOW
friend complex tan(const complex &);
friend complex tanh(const complex &);
friend double imag(const complex &);
friend double real(const complex &);
friend complex log(const complex &); // c_exception SING
// c_exception OVERFLOW UNDERFLOW
friend complex exp(const complex &);
friend complex pow(double, const complex &);
friend complex pow(const complex &, int);
friend complex pow(const complex &, double);
friend complex pow(const complex &, const complex &);
friend complex sqrt(const complex &);
friend complex sqr(const complex &);
friend complex operator-(const complex &);
friend complex operator+(const complex &, const complex &);
friend complex operator-(const complex &, const complex &);
friend complex operator*(const complex &, const complex &);
friend complex operator/(const complex &, const complex &);
friend int operator==(const complex &, const complex &);
friend int operator!=(const complex &, const complex &);
friend ostream &operator<<(ostream &, const complex &);
friend istream &operator>>(istream &, complex &);
public:
complex(double, double = 0);
complex();
inline complex &operator-=(const complex &);
inline complex &operator+=(const complex &);
complex &operator*=(const complex &);
complex &operator/=(const complex &);
};
|
Description
This class contains methods to perform complex value operations. These
include arithmetical, assignment, and comparison operators for complex
values; Cartesian and polar coordinates; mixed-mode arithmetic; and
mathematical functions for complex values equivalent to standard
mathematical functions.
Exception Handling
When a complex arithmetical error is detected, a
c_exception
object is created with one of the following values for
type
:
Value |
Error Description |
OVERFLOW
|
Value too large to be represented
|
SING
|
Function undefined for argument
|
UNDERFLOW
|
Value too small to be represented
|
This object is then passed to the
complex_error
function (see the
c_exception
class).
Constructors and Destructors
complex()
Constructs and initializes a complex value to 0.
complex(double x, double y = 0)
Constructs and initializes a complex value from Cartesian coordinates.
Overloaded Operators
complex operator + (const complex &z1, const complex
&z2)
Returns the arithmetical sum of the complex values z1 and
z2.
complex operator -- (const complex &z1)
Returns the arithmetical negation of a complex value.
complex operator -- (const complex &z1, const complex
&z2)
Returns the arithmetical difference of complex values. That is,
z2 is subtracted from z1.
complex operator * (const complex &z1, const complex
&z2)
Returns the arithmetical product of the complex values z1 and
z2.
complex operator / (const complex &z1, const complex
&z2)
Returns the arithmetical quotient of complex values. That is,
z1 is divided by z2.
inline complex &operator += (const complex &z1)
Assigns the arithmetical sum of complex values to the complex object on
the left side of an equation. That is, z1+=z2 is
equivalent to z1=z1+z2.
inline complex &operator --= (const complex &z1)
Assigns the arithmetical difference of two complex numbers to the
complex object on the left side of an equation. That is,
z1--=z2 is equivalent to
z1=z1--z2.
complex &operator *= (const complex &z2)
Assigns the arithmetical product of two complex numbers to the complex
object on the left side of an equation. That is,
z1*=z2 is equivalent to
z1=z1*z2.
complex &operator /= (const complex &z2)
Assigns the arithmetical quotient of two complex numbers to the complex
object on the left side of an equation. That is,
z1/=z2 is equivalent to
z1=z1/z2.
ostream &operator << (ostream &s, const complex
&z1)
Sends a complex value to an output stream in the format
(real,imag)
. It returns the left argument s.
istream &operator >> (istream &s, complex
&z1)
Takes a complex value from an input stream. The numbers may be of the
forms
(real,imag)
or
(real)
, where
real
and
imag
are what the iostream library accepts for parameters of type
double
. The iostream library also determines how to handle white space. This
operator returns the left argument s. The following input
format omissions will cause an error:
- Parenthesis missing before a complex value
- Comma missing before the imaginary part of a complex value, if any
- Parenthesis missing after the complex value
int operator == (const complex &z1, const complex &z2)
Compares two complex values and returns a nonzero value if the two
numbers are equal; otherwise, it returns 0.
int operator != (const complex &z1, const complex &z2)
Compares two complex values and returns a nonzero value if the two
numbers are not equal; otherwise, it returns 0.
Other Functions
double abs(const complex &z1)
Returns the absolute value (magnitude) of a complex value.
double arg(const complex &z1)
Returns the angle, in radians, of a complex value. The result is
normalized such that it is greater than or equal to 0, and less than
2*Pi sign .
double arg1(const complex &z1)
Returns the principal value of the angle, in radians, of a complex
value. The result is normalized such that it is greater than -Pi sign ,
and less than or equal to Pi sign .
complex conj(const complex &z1)
Returns the conjugate of a complex value; that is, if the number is
(real, imag)
, then the result is
(real, -imag)
.
complex cos(const complex &z1)
Returns the cosine of a complex value.
complex cosh(const complex &z1)
Returns the hyperbolic cosine of a complex value. The value of
real(z1)
must be small enough so that
exp(real(z1))
does not overflow; otherwise, the function creates a
c_exception
object and invokes the
complex_error
function.
complex exp(const complex &z1)
Returns the value of e (2.71828...) raised to the power of a complex
value. The conditions described for
cosh()
must be met; otherwise, it creates a
c_exception
object and invokes the
complex_error
function.
double imag(const complex &z1)
Returns the imaginary part of a complex value.
complex log(const complex &z1)
Returns the natural logarithm (base e, 2.71828...) of a complex value.
The conditions described for
cosh()
must be met; otherwise, it creates a
c_exception
object and invokes the
complex_error
function.
double norm(const complex &z1)
Returns the square of the absolute value (magnitude) of a complex value.
complex polar(double rho, double theta = 0)
Creates a complex value given a pair of polar coordinates (magnitude
rho and angle theta, in radians).
complex pow(const complex &z1, int i2)
Returns the value of z1 raised to the power of i2.
complex pow(const complex &z1, double x2)
Returns the value of z1 raised to the power of x2.
complex pow(double z1, const complex &z2)
Returns the value of z1 raised to the power of z2.
complex pow(const complex &z1, const complex &z2)
Returns the value of z1 raised to the power of z2.
double real(const complex &z1)
Returns the real part of a complex value.
complex sin(const complex &z1)
Returns the sine of a complex value.
complex sinh(const complex &z1)
Returns the hyperbolic sine of a complex value. The conditions
described for
cosh()
must be met; otherwise, it creates a
c_exception
object and invokes the
complex_error
function.
complex sqr(const complex &z1)
Returns the square of a complex value.
complex sqrt(const complex &z1)
Returns the square root of a complex value.
complex tan(const complex &z1)
Returns the tangent of a complex value.
complex tanh(const complex &z1)
Returns the hyperbolic tangent of a complex value. The conditions
described for
cosh()
must be met; otherwise, it creates a
c_exception
object and invokes the
complex_error
function.
Examples
|