United States

Compaq C++

# Compaq C++

# Class Library Reference Manual

Order Number: AA-PY3EC-TK

# December 1999

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
First Revision, June 1993
Second Revision, April 1996
Third Revision, December 1999

The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

© 1992-1999 Digital Equipment Corporation

Compaq, the Compaq logo, and Alpha, DEC, DEC FUSE, DECthreads, DIGITAL, OpenVMS, ULTRIX, VAX, VMS are Registered in U.S. Patent and Trademark Office.

Compaq. the Compaq logo, and Alpha, DEC, DEC FUSE, DECthreads, DIGITAL, Ladebug, OpenVMS, Tru64 UNIX. ULTRIX, VAX, VMS are Registered in 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.

This document is available on CD-ROM.

Contents | Index

# Preface

This manual describes the library of classes supplied with C++ Version 5.6 for OpenVMS 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 OpenVMS 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.

# Associated Documents

The following documents contain information related to this manual:

- Using Compaq C++ for OpenVMS VAX
  This manual supplies information needed to use C++ on OpenVMS systems.
- Stroustrup, Bjarne. Stroustrup, The C++ Programming Language, 3rd Edition, Addison-Wesley, 1997. Reading, Massachusetts. Addison-Wesley, 1997.
  This text combines a user guide and language reference manual.
- Stroustrup, Bjarne and Margaret Ellis. The Annotated C++ Reference Manual. Reading, Massachusetts. Addison-Wesley, 1990.
  This text contains the current language definition of C++.

- C Run-Time Library Reference Manual for OpenVMS Systems
  This manual describes C run-time library routines that are supported for C++.
- Compaq C++ Installation Guide for OpenVMS VAX
  This guide supplies information needed to ensure that the C++ Class Library installs correctly on OpenVMS systems and is accessible to the C++ compiler.

# Conventions

Table 1 lists the conventions used in this manual.

Table 1 Conventions Used in this Manual
Conventions | Meaning
--- | ---
`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.

# 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:

  cxx_docs@zko.dec.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.

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. Error message examples in this manual are displayed without their OpenVMS facility, error severity, or message identification code prefixes. You can achieve this result by entering the following DCL command:
    $ set message/nofac/nosev/noid

# 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 standard 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.

# 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

#1
    complex zz(3,-5);

> Declares `zz` to be a complex object and initializes it to the value of real part `3` and imaginary part `-5` .

#2
    complex myarray[30];

> Declares an array of 30 complex objects, all initialized to (0,0).

#3
    complex zz;
    while (!(cin >> zz).eof())
        cout << zz << endl;

> Reads a stream of complex values [for example, ( `3.400000,5.000000` )] and writes them in the default format [for example, ( `3.4, 5` )].

#4
    complex cc = complex (3.4,5);
    cout << real(cc) << "+" << imag(cc) << "*i";

> Prints out `3.4` as the real part of a complex object and `5` as the imaginary part. The result is `3.4+5*i` .

Next | Contents | Index

privacy and legal statement