1 CXXL This is the online help for the C++ Class Library. For help on the C++ Standard Library, type help cxxlstd 2 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 2 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. HP 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. 2 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 3 Global_Declarations The following declarations are used by the complex package but they are not members of a particular class: 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 3 complex This class contains methods to perform complex value operations. These include arithmetic, 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. 3 c_exception Objects of this class handle exceptions for complex arithmetic. This includes information on functions, parameters, error types, and default return values. 2 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 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. 2 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 3 Parameterized_manipulators Each of these manipulators takes a single argument, operates on it as described, and returns it. 4 lock(Mutex &) Locks a recursive mutex 4 resetiosflags(long) Clears, in the stream (istream or ostream), the format bits denoted by the argument. 4 setfill(int) Sets the fill character (istream or ostream) to be the value specified by the argument. 4 setiosflags(long) Turns on, in the stream (istream or ostream), the format bits denoted by the argument. 4 setprecision(int) Sets the precision (istream or ostream) to be the value specified by the argument. 4 setw(int w) Sets the field width of the stream (left-hand operand: ostream or istream) to the value specified by the argument. 4 unlock(Mutex &) unlocks a recursive mutex 3 filebuf This class specializes the streambuf class to use a file as a repository of characters. Writing to the file consumes characters; reading from the file produces characters. Files that allow searches are said to be seekable. When a file is readable and writable, the filebuf object permits character insertion and extraction. Header: #include 3 fstream This class specializes the class iostream to files using a filebuf object to do the input and output. Your program can perform common operations, such as opening and closing files, without explicitly mentioning filebuf objects. Header: #include 3 ifstream This class specializes the class istream to files using a filebuf object to do the input. Your program can perform common operations, such as opening and closing files, without explicitly mentioning filebuf objects. Header: #include 3 ios Classes derived from the ios class provide an interface for transferring formatted and unformatted information into and out of streambuf objects. Header: #include 4 Deriving_a_user_class If you derive your own class from the ios class, or from one of its derived classes, the ios sub-object must be properly initialized during instantiation. Specifically, you must ensure that the streambuf pointer within the ios sub-object is valid. To do this, you can specify the ios(streambuf *) constructor as a member initializer for your class constructor. Optionally, you can call the ios::init(streambuf *) member function. 3 iostream This class combines the classes istream and ostream. You use it to carry out bidirectional operations (inserting into and extracting from a single sequence of characters). Header: #include 3 iostream_withassign This class adds an assignment operator and a constructor with no operands to the iostream class. Header: #include 3 istream This class provides facilities for formatted and unformatted extraction from streambuf objects. Header: #include 3 istream_withassign This class adds an assignment operator and a constructor with no operands to the istream class. Header: #include 3 istrstream This class specializes the istream class to perform extractions from arrays of bytes in memory. Header: #include 3 ofstream This class specializes the class ostream to files using a filebuf object to do the output. Your program can perform common operations, such as opening and closing files, without explicitly mentioning filebuf objects. Header: #include 3 ostream Objects of this class perform formatted and unformatted insertions into streambuf objects. Header: #include 3 ostream_withassign This class adds an assignment operator and a constructor with no operands to the ostream class. Header: #include 3 ostrstream This class specializes the ostream class to perform insertions into arrays of bytes in memory. Header: #include 3 stdiobuf This class specializes the streambuf class for stdio FILEs. It uses unbuffered mode, which causes all operations to be reflected immediately in the FILE. Header: #include 3 stdiostream This class specializes the ios class for stdio FILEs; it also specializes the ios class to use stdiobuf as its associated streambuf. Header: #include 3 streambuf This class supports buffers into which you can insert (put) or extract (get) characters. It contains only the basic members for manipulating the characters. To implement the functions of this class, use a class derived from the streambuf class. The protected members of this class present an interface to the derived classes organized around the get, put, and reserve areas (arrays of bytes), which are managed cooperatively by the base and derived classes. The reserve area is a sequence of characters with an associated get pointer, put pointer, or both. This area serves mainly as a resource in which to allocate space for the put and get areas. As characters enter and exit the reserve area, the put and get areas change but the reserve area remains fixed. A collection of character pointer values defines the three areas. These pointers infer a boundary condition; therefore, it may be helpful to consider such pointers as pointing just before the byte but they actually point right at it. Classes derived from streambuf vary in their handling of the get and put pointers. The simplest are unidirectional buffers that permit only get and put operations. Such classes serve as producers and consumers of characters. Queue-like buffers (such as strstream and strstreambuf) have a put and a get pointer that move independently of each other. In such buffers, stored characters are queued until later fetched. File-like buffers (such as filebuf) allow both get and put operations but have their get and put pointers linked together, so that when one pointer moves so does the other. To manage the collections of characters in the get and put areas, you can call virtual functions. Services supplied by virtual functions include fetching more characters from an ultimate producer and flushing a collection of characters to an ultimate consumer. Header: #include 3 strstream This class specializes iostream for storing in and fetching from arrays of bytes. It handles all predefined data types, and provides an extensive set of options for performing input and output on these data types. Header: #include 3 strstreambuf Objects of this class let you use an array of bytes (a string of characters) in memory as a streambuf for stream input/output operations on various kinds of data. Mapping between abstract get and put pointers and char* pointers is direct in the sense that a char* is interpreted as pointing immediately ahead of the char it points to. Moving the pointers corresponds to incrementing and decrementing the char* values. To accommodate the need for strings of arbitrary length, this class supports a dynamic mode. When a strstreambuf object is in dynamic mode, space for the character is allocated as needed. When the sequence is extended too far, it is copied to a new array. Header: #include 3 Manipulators Manipulators are supplied to let executing programs insert values into or extract values from a stream to cause some special effect as follows: ios &dec(ios &s) Sets the conversion base format to decimal. ios &hex(ios &s) Sets the conversion base format to hexadecimal. ios &oct(ios &s) Sets the conversion base format to octal. ios &lock(ios &s) Locks a predefined object ios &unlock(ios &s) Unlcks a predefined object istream &ws(istream &i) Extracts (skips) white-space characters. ostream &endl(ostream &o) Ends a line by inserting a new-line character and flushing. ostream &ends(ostream &o) Ends a string by inserting a null (0) character. ostream &flush(ostream &o) Flushes ostreams. 3 IMANIP(TYPE) This class supplies predefined parameterized manipulators and provides macros for user-defined parameterized manipulators for istream objects. Header: #include 3 IOMANIP(TYPE) This class supplies predefined parameterized manipulators and provides macros for user-defined parameterized manipulators for iostream objects. Header: #include 3 OMANIP(TYPE) This class supplies predefined parameterized manipulators and provides macros for user-defined parameterized manipulators for ostream objects. Header: #include 3 SMANIP(TYPE) This class supplies predefined parameterized manipulators and provides macros for user-defined parameterized manipulators for ios objects. Header: #include 3 Predefined_stream_objects_synchronization Two unparameterized locking and unlocking manipulators, lock and unlock, are available for use in synchronizing access to the predefined stream objects: cerr, cin, clog, and cout. If your application needs to lock two or more of these objects at the same time, the application must adhere to this locking order: cin, cerr, clog, cout The unlocking order is not important. When your application calls a member function for a predefined stream object, the member function will typically lock the object for the duration of the call. Therefore, if your application has locked one of the stream objects and then uses another, this use must also adhere to the predefined locking order. For example, your application should not send output to cerr while cout is locked. The locking order necessarily matches the default 'ties' between the stream objects as follows: cin is tied to cout cerr is tied to cout clog is tied to cout cout has no ties Any input/output operation on a stream object causes the iostream Package to flush the object to which it is tied. Thus, an output to cerr flushes cout. 3 User-defined_stream_objects_synchronization Two parameterized locking and unlocking manipulators, lock and unlock, are available for use in synchronizing access to user-defined stream objects. To use these manipulators, you must first define a Mutex object which you then pass to the manipulator. The association of a Mutex object with a stream object is not enforced by the iostream package. This association is enforced only by a program developer. For more information, see help on the Mutex_package. 2 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 2 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 2 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 2 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 2 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 2 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 3 Global_Declarations These enums, externs, and typedefs of the task package are used by one or more classes but they are not members of any particular class. 4 Print_Function_Values The following values are used in the verbosity argument to print member functions: 0 Requests a brief report CHAIN Requests information about tasks on the object's remember chain, and about other objects on the object's o_next chain STACK Requests information about the run-time stack VERBOSE Requests detailed information on the class object 4 Queue_Mode_Values The following values are used by the qhead and qtail classes for managing queues: EMODE Generates a run-time error if full on enqueue or empty on dequeue WMODE Suspends task execution if full on enqueue or empty on dequeue ZMODE Returns NULL if full on enqueue or empty on dequeue 4 Exception_Codes The following codes handle exceptions for the classes indicated: E_OLINK = 1 Cannot delete an object with a remembered task (object class) E_ONEXT = 2 Cannot delete an object which is on a list (object class) E_GETEMPTY = 3 Cannot get an object from an empty queue (qhead class) E_PUTOBJ = 4 Cannot put an object into a full queue (qtail class) E_PUTFULL = 5 Cannot put an object into a queue if the object is on another queue (qtail class) E_BACKOBJ = 6 Cannot putback an object into a queue if the object is on another queue (qhead class) E_BACKFULL = 7 Cannot putback an object into a full queue (qhead class) E_SETCLOCK = 8 Cannot set the clock after it has advanced past 0 (sched class) E_CLOCKIDLE = 9 Cannot advance the clock when clock_task is RUNNING or TERMINATED (sched class) E_RESTERM = 10 Cannot resume a TERMINATED task (sched class) E_RESRUN = 11 Cannot resume a RUNNING task (sched class) E_NEGTIME = 12 Cannot delay a negative amount of time (sched class) E_RESOBJ = 13 Cannot resume a task or timer if it is already on another queue (sched class) E_HISTO = 14 Cannot construct a histogram with less than 1 bucket or the left not less than the right (histogram class) E_STACK = 15 Cannot extend stack (task class) E_STORE = 16 Cannot allocate more memory (object, qhead, qtail, and task classes) E_TASKMODE = 17 Cannot create a task with a mode other than DEDICATED or SHARED (task class) E_TASKDEL = 18 Cannot delete a task which is IDLE or RUNNING (task class) E_TASKPRE = 19 Cannot preempt a task which is IDLE or TERMINATED (task class) E_TIMERDEL = 20 Cannot delete a timer which is IDLE or RUNNING (timer class) E_SCHTIME = 21 Cannot execute something at a time which already passed (sched class) E_SCHOBJ = 22 Cannot use class sched other than as a base class (sched class) E_QDEL = 23 Cannot delete a queue which has an object in the queue (qhead and qtail classes) E_RESULT = 24 Cannot call result() on thistask (task class) E_WAIT = 25 Cannot call wait() on thistask (task class) E_FUNCS = 26 Encountered an unexpected exception or access violation E_FRAMES = 27 Not used in DEC C++ E_REGMASK = 28 Not used in DEC C++ E_FUDGE_SIZE = 29 Not used in DEC C++ E_NO_HNDLR = 30 Cannot handle a signal for which there is no handler (Interrupt_handler class) E_BADSIG = 31 Cannot handle a signal with an invalid signal number (Interrupt_handler class) E_LOSTHNDLR = 32 Cannot handle a signal which is not on a stack of them for the given signal (Interrupt_handler class) E_TASKNAMEOVERRUN = 33 Not used in DEC C++ 4 Maximum_stack_size To keep track of the maximum stack size that can be printed by the function task::print(), set the _hwm (high-water marking) data member to a nonzero value before creation of the first task. Declaration: extern int _hwm 3 erand Objects of this class are generators of exponentially distributed random numbers. 3 histogram Objects of this class generate histograms. 3 Interrupt_handler Interrupt handlers let tasks wait for external events (system signals), and allow the declaration of handler functions for these events. You can use classes derived from the Interrupt_handler class to overload the interrupt() function. When the signal is raised, the task system immediately calls the interrupt() function. The task system then schedules its own internal interrupt alerter for execution. Control returns to the task (if any) that was running when the signal was raised. When control returns to the scheduler, the interrupt alerter runs and schedules for execution those tasks that were waiting for the interrupt handler. If the run chain is empty, the scheduler does not cause the program to exit if there are any interrupt handlers that have been created but not yet destroyed. 3 object This class is a base class for many other classes within the task package. You can also use it to derive user classes to be placed in the task package's queues and so forth. All objects derived from the object class can declare the virtual function object::pending(), which the scheduler uses to determine if an object is ready or not. You can provide each kind of object with its own method of determining its state of readiness. Each pending object contains a list (the remember chain) of the waiting task objects. 3 qhead This class provides facilities for taking objects off a queue. A queue is a data structure with an associated list of objects of the object class, or a class derived from the object class in first-in, first-out order. All access to a queue is through either the attached qhead or the attached qtail. You create a queue by creating either a qhead or a qtail. The other end of the queue is created automatically. You can then obtain a pointer to the tail with the qhead::tail function. Objects have definitions of when they are ready and pending (not ready). The qhead objects are ready when the queue is not empty and pending when the queue is empty. 3 qtail This class provides facilities for putting objects into a queue. A queue is a data structure with an associated list of objects of the object class, or a class derived from the object class in first-in, first-out order. All access to a queue is through either the attached qhead or the attached qtail. You create a queue by creating either a qhead or a qtail. The other end of the queue is created automatically. You can then obtain a pointer to the head with the qtail::head function. Objects have definitions of when they are ready and pending (not ready). The qtail objects are ready when the queue is not full and pending when the queue is full. 3 randint Objects of this class generate uniformly distributed random numbers. Each random-number generator object produces a sequence that is independent of other random-number generator objects. 3 sched This class provides facilities for checking on the state of a task, manipulating the simulated clock, canceling a task, and checking on the result of a task. You can create instances of classes derived from the sched class, but not instances of the sched class itself. 3 task All coroutine classes are derived from this class. All work for an object of a given coroutine type occurs within the constructor for that type. The coroutine class must be exactly one level of derivation from the task class. When the object is created, the constructor takes control and runs until halted by one of the following functions: wait() sleep() resultis() When a task executes a blocking function on an object that is ready, the operation succeeds immediately and the task continues running; if the object is pending, the task waits. Control then returns to the scheduler, which selects the next task from the ready list or run chain. When a pending object becomes ready, the system puts any task waiting for that object back on the run chain. A task can be in one of the following states: RUNNING Running or ready to run IDLE Waiting for a pending object TERMINATED Completed; not able to resume running (but you can retrieve the result) 3 timer Objects of this class are timers. When a timer is created its state is RUNNING, and it is scheduled to change its state to TERMINATED after a specified number of time units. When the timer becomes TERMINATED, tasks waiting for it are scheduled to resume execution. 3 urand Objects of this class generate uniformly distributed random integers within a given range from a low to a high value. 2 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 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); 3 stack(TYPE) This class provides a generic (parameterized) data abstraction for a fixed-sized stack of objects of some given type. Before a stack can be declared or implemented, the base class, a vector with the same type parameter, must also be declared or implemented. 3 vector(TYPE) This class provides the (parameterized) data abstraction for a fixed-sized vector of objects of some given type. 2 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 !-- HTML EXCLUDE START ! compaq_cxx.bugs@compaq.com !-- HTML EXCLUDE STOP !-- HTML INCLUDE START ! ! compaq_cxx.bugs@compaq.com !-- HTML INCLUDE STOP 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 !-- HTML EXCLUDE START ! compaq_cxx@compaq.com !-- HTML EXCLUDE STOP !-- HTML INCLUDE START ! ! compaq_cxx@compaq.com !-- HTML INCLUDE STOP When reporting problems to HP, 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