United States

Compaq C++

# Compaq C++
Class Library Reference Manual

Previous | Contents | Index

# Chapter 6
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. For more information see the Guide to DECthreads manual.

Note User-defined objects are not automatically thread safe. Users must supply synchronization for such objects if they are shared between threads.

# Mutex class

> Provides a means whereby users can synchronize access to user-defined objects.

## Header File

> `#include <mutex.hxx>`

> Alternative Header

> `#include <mutex.h>`

## Declaration

>     class Mutex
>     {
>     public:
>                  Mutex();
>                  ~Mutex();

>        void      lock();
>        void      unlock();
>        int       trylock();
>     };

## Description

> The synchronization process consists of locking and unlocking `Mutex` objects associated with user-defined objects. Digital recommends that users create a `Mutex` object for each user-defined object that needs to be synchronized between threads. Users are then responsible for locking and unlocking the `Mutex` object to coordinate access to the associated object.

> To do the locking and unlocking, you can use the `lock` and `unlock` member functions (see Example). Alternatively, if a user-defined object is derived from the `istream` or `ostream` classes, you can use the `lock` and `unlock` parameterized manipulators, where the parameter is the `Mutex` object (see the Global Declarations section in Chapter 4).

## Constructors and Destructors

> ### Mutex()

> Constructs a `Mutex` object, in effect creating but not locking a recursive mutex.

> ### ~Mutex()

> Deletes a `Mutex` object.

## Member Functions

> ### void lock()

> Locks a recursive mutex. If the mutex is locked by another thread, the current thread is blocked until the mutex becomes available.

> ### void unlock()

> Unlocks a recursive mutex.

> ### int trylock()

> Immediately returns to the caller a value of 0 if the mutex is already locked by another thread. Otherwise, this function locks the mutex and returns a value of 1.

## Example

    #include <string.hxx>
    #include <mutex.hxx>
       .
       .
       .
    String string1;
    Mutex string1_lock;

    string1_lock.lock();
    string1 = "Hello, ";
    string1 += "how are you?";
    cout << string1;
    string1_lock.unlock();

> This example synchronizes a sequence of operations on a `String` object, using the `lock()` and `unlock()` member functions.

# Chapter 7
Objection Package

The Objection package provides a way to implement simple error handling. You can use this package to catch run-time errors encountered in using classes, and to change or restore actions associated with such errors.

# Global Declaration

> This `typedef` is used by, but is not a member of, the `Objection` class.

## Header

> `#include <objection.hxx>`

> Alternative Header

> `#include <Objection.h>`

## Declaration

>     typedef int Objection_action(const char*);

## Type

> ### Objection_action

> Is the type of an action routine that can be called by the function `Objection::raise` .

# Objection class

> Provides the capability to handle and report errors.

## Header

> `#include <objection.hxx>`

> Alternative Header

> `#include <Objection.h>`

## Declaration

>     class Objection
>     {

>     public:
>                           Objection();
>                           Objection(Objection_action *);
>         int               raise(const char * = "");
>         Objection_action  *appoint(Objection_action *);
>         Objection_action  *appoint();
>         Objection_action  *ignore();
>     };

## Description

> This class provides ways to handle objections. An objection is a potential error condition that your program can encounter. The user appoints an error-handling function. An `Objection` object's `raise()` function invokes the appointed function by passing it a character string that contains an error message. At any point in your program, you can appoint a new error-handling function, reappoint the original function, or specify that an objection be ignored.

## Constructors

> ### Objection()

> Constructs an `Objection` object with no default action (error handler).

> ### Objection(Objection_action *new_action)

> Constructs an `Objection` object with a pointer to the default error handler. The handler is a function that takes one parameter of type `const char *msg` and returns an `int` . See the `raise()` member function for more information.

## Member Functions

> ### Objection_action *appoint()

> Specifies that the handler for the objection is the default error handler (if one exists) and returns the previous action associated with the specified objection. Specifies that the objection not be ignored.

> ### Objection_action *appoint(Objection_action *new_action)

> Specifies a new handler for the objection and returns the previous action associated with the specified objection. Specifies that the objection not be ignored.

> ### Objection_action *ignore()

> Specifies that the objection be ignored (no error handler is invoked if the objection is raised). This function returns the previous action associated with the specified objection.

> ### int raise(const char *msg = "")

> Raises a specified objection, passing a string (error message) to an error handler (if one exists). If no handler exists, or if the handler returns a 0, the default handler is called. The `raise` function returns the value returned by the last handler it called.

> If no default handler exists, then the function returns 0. A 0 is also returned if the objection is ignored. Generally, the return of a nonzero value means that the error handling succeeded, and the return of a 0 value means the error handling failed.

  The following example changes the default error handler for the
  `stack(int)::overflow_error` objection:

    #include <stdlib.h>
    #include <vector.hxx>
    #include <objection.hxx>

    vectordeclare(int)
    stackdeclare(int)

    vectorimplement(int)
    stackimplement(int)

    stack(int) s(10);

    int error(const char *errmsg)
    {
        cerr << "ERROR TRAPPED: " << errmsg << " -- ABORTING\n";
        cerr.flush();
        abort();
        return 0;
    }

    void main()
    {
        Objection_action *save_action;
        save_action = stack(int)::overflow_error.appoint(error);
        for(int i=0; i<100; i++)  //push too many things onto stack
            s.push(i);
        stack(int)::overflow_error.appoint(save_action);
    }

  When this example executes, the following message prints out:

    ERROR TRAPPED: Stack underflow -- ABORTING
    %SYSTEM-F-OPCCUS, opcode reserved to customer fault at PC=00010BE5, PSL=03C00000
    %TRACE-F-TRACEBACK, symbolic stack dump follows
    module name     routine name                     line       rel PC    abs PC

                                                               0000012D  00010BE5
                                                               0000000E  00009346
    OBJECTION_EXAMP error                            5984      00000045  00003D29
    CXXL_OBJECTION  Objection::raise                  779      00000026  00008F5A
    OBJECTION_EXAMP main                             5993      0000005B  00003D87
                                                               00000072  0002DB5E

Note The message printed on your system differs somewhat from that shown here.

# Chapter 8
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.

# Stopwatch class

> Provides the means to measure intervals of time between specified program events.

## Header

> `#include <stopwatch.hxx>`

> Alternative Header

> `#include <Stopwatch.h>`

## Declaration

>     class Stopwatch
>     {
>     public:
>                          Stopwatch();

>        void              start();
>        void              stop();
>        void              reset();
>        int               status() const;
>        double            system() const;
>        double            user() const;
>        double            real() const;

>        static double     resolution();
>     };

## Description

> Objects of this 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.

## Constructor

> ### Stopwatch()

> Constructs a `Stopwatch` object with both time and running status initialized to 0.

## Member Functions

> ### double real() const

> Returns real time (clock time) in double-precision, floating-point seconds. You can call this function while the stopwatch is running.

> ### void reset()

> Resets the current time measurement to 0 without affecting the value of `status()` . If `status()` is initially nonzero, time measurement continues uninterrupted after resetting.

> ### double resolution()

> Returns the (system dependent) resolution of measured time in double-precision, floating-point seconds.

> ### void start()

> Begins measuring program execution time when `status()` is initially 0 ( `status()` becomes nonzero as a consequence of the call). If `status()` is initially nonzero, the call has no effect.

> ### int status() const

> Indicates whether the stopwatch is running (returns a value of 1) or not running (returns a value of 0).

> ### void stop()

> Halts measurement of program execution time when `status()` is initially nonzero ( `status()` becomes 0 as a consequence of the call). If `status()` is initially 0, the call has no effect.

> ### double system() const

> Returns the system CPU time in double-precision, floating-point seconds. You can call this function while the stopwatch is running.

> ### double user() const

> Returns the user CPU time in double-precision, floating-point seconds. You can call this function while the stopwatch is running.

## System Environment

> On OpenVMS systems, user time returns the total accumulated CPU time, and system time returns 0. Resolution is 1/100 second.

## Example

    Stopwatch w ;
    w.start() ;
    //...
    // some computation you want to time goes here
    //...
    w.stop() ;
    cout << "elapsed time was " << w.user() << "\n";

> Displays the number of seconds the computation takes to run. The result is a double-precision value.

# Chapter 9
String Package

The String package consists of the single class `String` . This class 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.

# String class

> Provides the capabilities for manipulating sequences of characters.

## Header

> `#include <string.hxx>`

> Alternative Header

> None.

## Declaration

>     class String
>     {
>         friend ostream  &operator<<(ostream &, const String &);
>         friend istream  &operator>>(istream &, String &);
>         friend int      operator==(const String &, const String &);
>         friend int      operator==(const String &, const char *);
>         friend int      operator==(const char *, const String &);
>         friend int      operator!=(const String &, const String &);
>         friend int      operator!=(const String &, const char *);
>         friend int      operator!=(const char *, const String &);
>         friend int      operator<(const String &, const String &);
>         friend int      operator<(const String &, const char *);
>         friend int      operator<(const char *, const String &);
>         friend int      operator>(const String &, const String &);
>         friend int      operator>(const String &, const char *);
>         friend int      operator>(const char *, const String &);
>         friend int      operator<=(const String &, const String &);
>         friend int      operator<=(const String &, const char *);
>         friend int      operator<=(const char *, const String &);
>         friend int      operator>=(const String &, const String &);
>         friend int      operator>=(const String &, const char *);
>         friend int      operator>=(const char *, const String &);
>         friend String   operator+(const String &, const String &);
>         friend String   operator+(const String &, const char *);
>         friend String   operator+(const char *, const String &);

>     public:
>                         String();
>                         String(const String &);
>                         String(const char *);
>                         String(const char &);
>                         ~String();

>         String          &operator=(const String &);
>         String          &operator=(const char *);
>                         operator char * () const;
>                         operator const char * () const;
>         String          &operator+=(const String &);
>         String          &operator+=(const char *);
>         String          operator()(int, int) const;
>         unsigned int    length() const;
>         String          upper() const;
>         String          lower() const;
>         int             match(const String &) const;
>         int             index(const String &) const;
>         char            operator[](int) const;
>         char            &operator[](int);
>     };

## Description

> This class provides the means for manipulating sequences of characters, each of which is of the type `char` . For some applications, the services provided 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.

## Constructors and Destructors

> ### String()

> Constructs a `String` object initialized to an empty string.

> ### String(const char *s)

> Constructs a `String` object and initializes it to the null-terminated sequence of characters.

> ### String(const char &c)

> Constructs a `String` object with a reference to a `char` datum to initialize the string.

> ### String(const String &x)

> Constructs a `String` object with a reference to another `String` to initialize the first `String` .

> ### ~String()

> Deletes a `String` object; no user action is required.

## Overloaded Operators

> ### String operator + (const char *s, const String &x)

> Concatenates a null-terminated sequence of characters to a `String` object.

> ### String operator + (const String &x, const char *s)

> Concatenates a `String` object with a null-terminated sequence of characters.

> ### String operator + (const String &x, const String &y)

> Concatenates a `String` object with another `String` object.

> ### String &operator = (const char *s)

> Assigns a `String` object to a null-terminated sequence of characters.

> ### String &operator = (const String &x)

> Assigns a `String` object to another `String` object.

> ### int operator < (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is less than a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator < (const String &x, const char *s)

> Tests if a `String` object is less than a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator < (const String &x, const String &y)

> Compares two `String` objects to determine if the first is less than the second; if so, it returns 1. Otherwise, it returns 0.

> ### int operator > (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is greater than a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator > (const String &x, const char *s)

> Tests if a `String` object is greater than a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator > (const String &x, const String &y)

> Compares two `String` objects to determine if the first is greater than the second; if so, it returns 1. Otherwise, it returns 0.

> ### String &operator += (const char *st2)

> Concatenates a null-terminated sequence of characters to a `String` object.

> ### String &operator += (const String &st2)

> Concatenates a `String` object to another `String` object.

> ### ostream &operator << (ostream &s, const String &x)

> Inserts the sequence of characters represented by x into the stream s.

> ### istream &operator >> (istream &s, String &x)

> Extracts characters from s using the istream extraction operator, then stores characters in x, replacing the current contents of x and dynamically allocating x as necessary.

> ### int operator == (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is equal to a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator == (const String &x, const char *s)

> Tests if a `String` object is equal to a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator == (const String &x, const String &y)

> Compares two `String` objects to determine equality. If one is equal to the other, it returns 1; otherwise, it returns 0.

> ### int operator != (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is not equal to a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator != (const String &x, const char *s)

> Tests if a `String` object is not equal to a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator != (const String &x, const String &y)

> Compares two `String` objects to determine inequality. If they are not equal, the function returns 1; otherwise, it returns 0.

> ### int operator <= (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is less than or equal to a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator <= (const String &x, const char *s)

> Tests if a `String` object is less than or equal to a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator <= (const String &x, const String &y)

> Compares two `String` objects to determine if the first is less than or equal to the second; if so, it returns 1. Otherwise, it returns 0.

> ### int operator >= (const char *s, const String &x)

> Tests if a null-terminated sequence of characters is equal to or greater than a `String` object; if so, it returns 1. Otherwise, it returns 0.

> ### int operator >= (const String &x, const char *s)

> Tests if a `String` object is equal to or greater than a null-terminated sequence of characters; if so, it returns 1. Otherwise, it returns 0.

> ### int operator >= (const String &x, const String &y)

> Compares two `String` objects to determine if the first is equal to or greater than the second; if so, it returns 1. Otherwise, it returns 0.

> ### String operator () (int index, int count) const

> Creates a new `String` object defined as a substring of the current `String` , with index as the starting character and count as the length of the substring.

> ### char operator [] (int position) const

> Returns the character at the requested position within the string. If the position is past the end of the string, it returns 0. If the position is negative, the results are undefined.

> ### char &operator [] (int position)

> Returns a reference to the character at the requested position within the string. This reference is potentially invalid after any subsequent call to a non-const member function for the object. If the position is past the end of the string or if the position is negative, the results are undefined.

## Other Member Functions

> ### int index(const String &x) const

> Returns the index value of the first position where an element of a `String` object coincides with the value of x.

> ### unsigned int length() const

> Returns the length (number of characters) in a `String` object.

> ### String lower() const

> Returns a new `String` object constructed from a `String` except that every character is lowercase regardless of its original case.

> ### int match(const String &x) const

> Compares two strings and returns the first index position at which they differ; it returns --1 if the strings match completely. The `String` argument can be a character pointer.

> ### String upper() const

> Returns a new `String` constructed from a `String` except that every character is uppercase regardless of its original case.

##

### Examples

#1
    String x ("The Times of John Doe");
    char *y = "Pink Triangles";

    if (x != y) cout << "We have two different strings.\n";

    x = y;

    cout << x;

> Previous | Next | Contents | Index

> privacy and legal statement