cxxl$help.HLP
Overview
The DEC C++ Class Library is a set of headers and other files
implementing a collection of C++ classes. In the library, these
classes are arranged in functionally related groups called packages.
For help on the C++ Standard Library, type
help cxxlstd
Thread_safety
Developers of multithreaded applications should note that:
o Internal class library data is thread safe; multiple threads can
access the DEC C++ Class Library simultaneously without compromising
the integrity of the internal data.
o 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. See also: help on
Predefined_stream_objects_synchronization.
o User-defined objects are not thread safe; users must provide
synchronization for such objects if they are shared between threads.
For more information, see help on the Mutex_package.
o 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 that use the predefined stream objects: cerr, cin, clog,
or cout.
o 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. Compaq
recommends that you define a single Mutex object to synchronize all use
of the Vector Package.
o The Task Package is not thread safe; only one task can execute at a time.
complex_package
The complex package provides ways to perform arithmetic 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
arithmetic errors.
Header:
#include <complex.hxx>
Additional Information on:
Global_Declarations
complex
c_exception
generic_package
The generic package provides ways to simulate parameterized types by
allowing the instantiation of class declarations using the macro
facilities of the DEC C++ preprocessor. You can use the generic
package to construct container classes. The actual types of the data
members are passed at compile time as parameters to the class when
you use the class name.
Header:
#include <generic.hxx>
To declare a generic type:
1. Define a name for the class and specify the number of type
parameters:
o To specify one type parameter, use the name2 macro
o To specify two type parameters, use the name3 macro
For example:
#define myclass(mytype) name2(myType, myClass)
2. Define the class body as a macro. For example:
#define myclass declare(myParam) class {...}
#define myclass implement(myParam) ...
3. Declare the actual class (any valid C++ type). For example:
declare(myClass, T)
By substituting one or another class, you can declare multiple
instances of the generic class template with various component types.
For example, depending on the type parameter you use, you can declare
such types as list of int, list of strings, or list of lists.
iostream_package
Classes in the iostream package provide methods to handle input and
output streams, including the reading and writing of built-in data
types. You can also extend certain methods described here to handle
class types.
This package includes, among others, the ios and streambuf classes,
and the subclasses derived from these base classes.
The istream (input stream) class supports input
operations(extractions); the ostream (output stream) class supports
output operations (insertions). The iostream class derives from both
istream and ostream, and supports both extractions and insertions.
The following stream objects are predefined:
cin An istream_withassign object linked to standard input
cout An istream_withassign object linked to standard output
cerr An ostream_withassign object linked to standard error that
supports unbuffered output
clog An ostream_withassign object linked to standard error that
supports buffered output
To generate output, you apply the insertion operator (<<) to cout.
For example:
cout << "Hello\n";
Providing input is similar to generating output except that you apply
the extraction operator (>>) to cin. For example:
int eye, jay;
cin >> eye >> jay;
If you include these fragments of code in a program, your system
expects users to type in two integer values (for eye and jay) from a
terminal. The iostream package supplies predefined extraction and
insertion operators for all built-in data types, including char*.
The iostream package also supports file manipulation. To connect a
specific file to your program, instantiate one of the following class
types:
ifstream For file input
ofstream For file output
fstream For both input and output
To format within character arrays, the iostream package includes the
following associated class types:
istrstream For fetching characters from an array
ostrstream For storing characters into an array
strstream For both fetching and storing characters into an
array
Additional Information on:
Parameterized_manipulators
filebuf
fstream
ifstream
ios
iostream
iostream_withassign
istream
istream_withassign
istrstream
ofstream
ostream
ostream_withassign
ostrstream
stdiobuf
stdiostream
streambuf
strstream
strstreambuf
Manipulators
IMANIP(TYPE)
IOMANIP(TYPE)
OMANIP(TYPE)
SMANIP(TYPE)
Predefined_stream_objects_synchronization
User-defined_stream_objects_synchronization
messages_package
The Messages package provides a way to retrieve messages stored in a
file separate from your program. It consists of a single class, Messages.
Objects of this class retrieve the text of messages for a given
message set number.
A message set number is an OpenVMS message identification code, including
a facility code (bits 16 through 27) and a facility-specific bit (bit 15);
all other bits should be 0. To process the message file, use the OpenVMS
Message Utility (see the OpenVMS Message Utility Manual for details).
Link the resulting object code into one of the following:
Your program
A shareable image that your program is linked against
A shareable image that is then specified with the set message
command
Header:
#include <messages.hxx>
Mutex_package
The Mutex package provides a way to synchronize access to user-defined
objects. It consists of a single class, Mutex, that manages the
creation, locking and unlocking of Mutex objects.
Construction of a Mutex object creates a recursive mutex that
users can lock and unlock using the appropriate member functions or
parameterized manipulators. A recursive mutex is a mutex that can be
locked many times by the same thread without causing the thread to enter
a deadlock state. To completely unlock this kind of mutex, the thread
must unlock the mutex the same number of times that the thread locked the
mutex.
Note that user-defined objects are not automatically thread safe. Users
must supply synchronization for such objects if they are shared between
threads.
Header:
#include <mutex.hxx>
Objection_package
The Objection package provides a way to implement simple error
handling in DEC C++. You can use this package to catch run-time errors
encountered when using classes, and to change or restore actions
associated with such errors.
Header:
#include <objection.hxx>
Stopwatch_package
The Stopwatch package provides ways to measure intervals of program
execution time. The package consists of a single class, Stopwatch.
Typically, you use this class during the performance-tuning phase of
program development.
Objects of the Stopwatch class measure program execution time and
return the result in floating-point seconds. The class includes the
start, stop, and reset functions familiar to users of a mechanical
stopwatch.
You can time the entire program or select certain portions of the
program to time; for example, a specified loop or program module. You
can create a different Stopwatch object for each independent program
activity, and name each according to the activity you intend to
measure.
Header:
#include <stopwatch.hxx>
String_package
The String package consists of the single class, String, which
provides ways to assign, concatenate, and compare character strings.
This class also provides methods for substring creation and for vector
access to a character string.
For some applications, services provided by the String class are like
those provided by the traditional C string library (strcpy, strcmp,
and so forth), but are more efficient and convenient in the context of
C++. Overloaded operators provide ways to assign, concatenate, and
compare strings. New operators provide simple notations for substring
creation and vector access into the string.
All comparisons are lexicographic with the ordering dependent on the
character set in which the string is encoded.
An index value of 0 indicates the first character in a String object.
Header:
#include <string.hxx>
task_package
The task package provides coroutine support. A coroutine, or task, is
a subroutine that can suspend execution to allow other tasks to run.
Static data is shared among all tasks; automatic and register data is
allocated separately for each task. Only one task can execute at a
time, even on a multiprocessor system.
Programming with tasks can be particularly appropriate for
simulations, real-time process control, or other applications that can
be reasonably represented as sets of concurrent activities.
This package includes the object and randint classes, and the
subclasses derived from these classes plus the histogram class.
Also, note the following:
o The sched class is intended for use only as a base class.
o The task package makes use of other libraries.
o The task package is not thread safe. You cannot create tasks
simultaneously from different threads.
Header:
#include <task.hxx>
Additional Information on:
Global_Declarations
erand
histogram
Interrupt_handler
object
qhead
qtail
randint
sched
task
timer
urand
vector_package
The vector package provides ways to define vectors or stacks of
objects of any type by using the macro expansion capability of the DEC
C++ preprocessor. When used with pointers, the vector package becomes
a versatile tool for constructing programs to solve complicated
mathematical problems.
Header:
#include <vector.hxx>
To declare a generic vector:
1. Include the vector.hxx header in your program and declare the
vector class as follows:
declare(vector, TYPE)
TYPE may be any other valid C++ type name. Make sure you define
the declare macro in every file that references this new vector
data type.
2. Expand the implementation of all function bodies as follows:
implement(vector, TYPE)
This implement macro must appear once in a program.
3. Declare objects of type vector, TYPE, and use the index operator
to reference these objects. The following is an example of
declaration and referencing:
class MyType {//...//};
declare(vector,MyType);
implement(vector,MyType);
vector(MyType) vec1(100), vec2(5);
MyType x,y;
//...
if(vec2[4] == y vec1[98]) = x;
The TYPE parameter must be an identifier. If it is not a class
name, a fundamental type, or a type name, use a typedef to
create a name for the type. For example:
typedef char * PCHAR;
declare (stack,PCHAR);
stack(PCHAR) ptrstack;
char *p = "Text";
ptrstack.push(p);
Additional Information on:
stack(TYPE)
vector(TYPE)
Customer_feedback
Customers with support contracts should seek support for problems through
local customer support centers.
Customers who do not have support contracts are encouraged to mail problem
reports to
compaq_cxx.bugs@compaq.com
Although these reports will certainly be used as a source of input
for fixing problems for new releases, we cannot give the reports
individual attention. We can take remedial action only on a best-effort
basis.
If you have questions, suggestions, or comments, please send mail to
compaq_cxx@compaq.com
When reporting problems to Compaq, please provide the following
information:
o Name and version of compiler (from a listing file)
o Name and version of operating system
o Smallest possible complete source and commands needed to
reproduce the problem
o An example of the incorrect results and the desired results