Header

#include <complex.hxx>

Alternative Header

#include <complex.h>

Descriptions

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

Is the type of the complex_error function.

Data

Is a constant object of type complex and value 0 created in each module that uses the complex package.

Function

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 section called “Other Function” of c_exception class for a description of the error-handling function.

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

OVERFLOW

SING

UNDERFLOW

This object is then passed to the complex_error function (see c_exception class).

Constructors and Destructors

Constructs and initializes a complex value to 0.

Constructs and initializes a complex value from Cartesian coordinates.

Overloaded Operators

Returns the arithmetical sum of the complex values z1 and z2.

Returns the arithmetical negation of a complex value.

Returns the arithmetical difference of complex values. That is, z2 is subtracted from z1.

Returns the arithmetical product of the complex values z1 and z2.

Returns the arithmetical quotient of complex values. That is, z1 is divided by z2.

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.

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.

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.

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.

Sends a complex value to an output stream in the fo(real,imag)rmat. It returns the left argument s.

Compares two complex values and returns a nonzero value if the two numbers are equal; otherwise, it returns 0.

Compares two complex values and returns a nonzero value if the two numbers are not equal; otherwise, it returns 0.

Other Functions

Returns the absolute value (magnitude) of a complex value.

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 * π.

Returns the principal value of the angle, in radians, of a complex value. The result is normalized such that it is greater than −π, and less than or equal to π.

Returns the conjugate of a complex value; that is, if the number is (real, imag), then the result is (real, -imag).

Returns the cosine of a complex value.

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.

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.

Returns the imaginary part of a complex value.

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.

Returns the square of the absolute value (magnitude) of a complex value.

Creates a complex value given a pair of polar coordinates (magnitude rho and angle theta, in radians).

Returns the value of z1 raised to the power of i2.

Returns the value of z1 raised to the power of x2.

Returns the value of z1 raised to the power of z2.

Returns the value of z1 raised to the power of z2.

Returns the real part of a complex value.

Returns the sine of a complex value.

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.

Returns the square of a complex value.

Returns the square root of a complex value.

Returns the tangent of a complex value.

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

Header

#include <complex.hxx>

Alternative Header

#include <complex.h>

Declaration

class c_exception
{
    friend complex   exp(const complex &);
    friend complex   sinh(const complex &);
    friend complex   cosh(const complex &);
    friend complex   log(const complex &);
    friend int       complex_error(c_exception &);

public:
    int              type;
    char             *name;
    complex          arg1;
    complex          arg2;
    complex          retval;

public:
    c_exception(char *, const complex &, const
    complex & = complex_zero);
};

Description

Objects of this class handle exceptions for complex arithmetic. This includes information on functions, parameters, error types, and default return values.

Data Members

Is the left argument of the function that incurred the error.

Is the right argument of the function that incurred the error.

Is the name of the function that incurred the error.

Is the value to be returned by the function that incurred the error. You may use the complex_error(c_exception &) function to change this value.

Is one of these kinds of error: SING, OVERFLOW, or UNDERFLOW.

Constructor

Constructs a complex arithmetical exception object, with reference to the name and arguments of the function that incurred the error.

Other Function

To substitute your own error-handling function, pass a pointer to your function to the set_complex_error function. (See the section called “Function”).

The complex arithmetical functions that invoke the error handling function always return the value specified in error_information.retval. Your error-handling function may set this value.

Header

#include <generic.hxx>

Alternative Header

#include <generic.h>

Compile-Time Parameters

TYPE, TYPE1, TYPE2 – The types for which this class is parameterized; TYPE, TYPE1, or TYPE2 must be an identifier.

CLASS – The class that is parameterized. For a vector of integers, for example, CLASS is vector and TYPE is int.

Declarations

typedef int  (*GPT)(int, char *);
int          genericerror(int n, char *msg);

Type

Is a pointer to a generic error-handling function.

Function

Is the default error-handling function; it prints an error number (n) and message (msg) on cerr and calls abort().

Macros

Macros provide preprocessor facilities for simulating parameterized types. The following macros are defined for the generic package:

Calls the current error handler for a given instance of a parameterized class. CLASS denotes the name of the generic class (for example, vector). TYPE denotes the type parameter for which to instantiate the generic class (for example, int to get a vector of integers); the type must be an identifier (for example, char* is not valid). N denotes the first argument to pass to the error handler; the default is the function genericerror(int, char*). S denotes the second argument to pass to the error handler.

Declares the class specified by a macro with the name of the generic class. The word declare follows the class name (for example, vectordeclare). It also defines the inline member functions of the class. CLASS denotes the name of the generic class (for example, vector). TYPE denotes the type parameter for which to instantiate the generic class (for example, int to get a vector of integers). The type must be an identifier (for examplechar*, is not valid).

Declares the class specified by a macro with the name of the generic class. The name is followed by the word declare2. The declare2 macro differs from the declare macro only in that you use it to declare two type parameters, TYPE1 and TYPE2.

Is the name of the pointer to the error handler for a given instance of a parameterized class (for example, intvectorhandler to handle errors for a vector of integers). CLASS denotes the name of the generic class (for example, vector). TYPE denotes the type parameter for which to instantiate the generic class (for example, int to get a vector of integers). The type must be an identifier (for example, char* is not valid).

Defines the noninline member functions of a class, specified by a macro with the name of the generic class. The name is followed by the word implement (for example, vectorimplement). The implement macro takes the same arguments as the declare macro.

Defines the noninline member functions of a class, specified by a macro with the name of the generic class. The name is followed by the word implement2. The implement2 macro differs from the implement macro only in that you use it to declare two type parameters, TYPE1 and TYPE2.

Concatenates two identifier segments to form a new identifier using the ## operator.

Concatenates three identifier segments to form a new identifier using the ## operator.

Concatenates four identifier segments to form a new identifier using the ## operator.

Specifies a function as the current error handler for a given instance of a parameterized class. Initially, the error-handling function is set to genericerror(int, char*). CLASS denotes the name of the generic class (for example, vector). TYPE denotes the type parameter for which to instantiate the generic class (for example, int to get a vector of integers); the type must be an identifier (for example, char* is not valid). HANDLER denotes a pointer to the function you want to set to the new error handler. Also, you can use the set_handler macro in a function declaration or definition.

Example

extern "C"
{
#include <stdlib.h>
#include <stddef.h>
#include <stdio.h>
}

#include <generic.hxx>

#define my_vector(T) name2(T, my_vector)

// Declare a vector of objects of type T (the class and extern data)
#define my_vectordeclare(T) \
    class my_vector(T) \
    { \
    private: \
        int s; \
        T *p; \
    public: \
        my_vector(T)(int); \
        ~my_vector(T)(); \
        T &operator[](int); \
    }; \
    extern GPT errorhandler(my_vector, T); \
    extern GPT set_handler(my_vector, T, GPT);

// Implement a vector of objects of type T
// (Define the functions and global data)
#define my_vectorimplement(T) \
    my_vector(T)::my_vector(T)(int size) \
    { \
        s = size; \
        p = new T[size]; \
    } \
    my_vector(T)::~my_vector(T)() \
    { \
        delete[] p; \
    } \
    T &my_vector(T)::operator[](int i) \
    { \
        if(i < 0 || i >= s) \
        { \
            callerror(my_vector, T, i, "Index out of bounds"); \
            static T error_object; \
            return error_object; \
        } \
        return p[i]; \
    } \
    GPT errorhandler(my_vector, T) = &genericerror; \
    GPT set_handler(my_vector, T, GPT new_genericerror) \
    { \
        GPT old_genericerror = errorhandler(my_vector, T); \
        errorhandler(my_vector, T) = new_genericerror; \
        return old_genericerror; \
    }

// Declare and implement vector of int
declare(my_vector, int)
implement(my_vector, int)

// Error-handling function
my_handler(
    int n,
    char *msg
    )

{
    fflush(stderr);
    printf("in my_handler(%d,\"%s\")\n", n, msg);
    fflush(stdout);
    return 0;
}


int main(int argc, char *argv[])
{
    my_vector(int) v1(10);

    GPT old_error_handler;

    // Set the handler to a function that does not abort
    old_error_handler = set_handler(my_vector, int, &my_handler);
    v1[12345] = 0;

    // Restore the handler and cause an error
    // This should abort
    old_error_handler = set_handler(my_vector, int, old_error_handler);
    v1[12345] = 0;

    return EXIT_SUCCESS;
}

See Also

Chapter 11, "vector Package"

Header

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declarations

typedef long    streamoff
typedef long    streampos

ios             &dec(ios &s);
ios             &hex(ios &s);
ios             &oct(ios &s);
ios             &lock(ios &s);
ios             &unlock(ios &s);

istream         &ws(istream &i);
ostream         &endl(ostream &o);
ostream         &ends(ostream &o);
ostream         &flush(ostream &o);

Types

Is the type representing a character offset into a stream. For more information, see the description of the seekoff and seekpos functions in the streambuf class.

Is the type representing a character position in a stream. For more information, see the description of the seekoff and seekpos functions in the streambuf class.

Manipulators

The following functions insert values into a stream, extract values from a stream, or specify the conversion base format. For more information on the conversion base format flags, see the iostream class.

Sets the conversion base format for s to decimal, essentially clearing the ios::oct and ios::hex flags and setting the ios::dec flag.

Sets the conversion base format for s to hexadecimal, essentially clearing the ios::oct and ios::dec flags and setting the ios::hex flag.

Sets the conversion base format for s to octal, essentially clearing the ios::dec and ios::hex flags and setting the ios::oct flag.

Extracts (skips) white-space characters from i.

Ends a line by inserting a new-line character into o and flushing o.

Ends a string by inserting a null '/0' character into o.

Flushes o.

Synchronizing Access to Predefined Stream Objects

The following unparameterized manipulators are for use in synchronizing access to the predefined stream objects, cerr, cin, clog, and cout:

Locks s if s is one of the predefined stream objects.

Unlocks s if s is one of the predefined stream objects.

For example, if your application needs to lock both cerr and cout, lock cerr first and cout second. The unlocking order is not important.

Keep in mind that 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.

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.

Examples

Header

include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Declarations

SMANIP(long)       resetiosflags(long);
SMANIP(long)       setiosflags(long);
SMANIP(int)        setfill(int);
SMANIP(int)        setprecision(int);
SMANIP(int)        setw(int w);

SMANIPREF(Mutex)   lock(Mutex &m)
SMANIPREF(Mutex)   unlock(Mutex &m)

Functions

These functions are used for extending the iostream package with user-defined parameterized manipulators.

In the stream (ios or a stream derived from ios), clears the format flags denoted by x.

Sets the fill character to be the value specified by x. The fill character is a data member of the ios class; however, setting it with this function affects only output streams.

In the stream (ios or a stream derived from ios), turns on the format flags denoted by x. If you are setting a flag that is part of a collection (for example, basefield), note that this manipulator does not clear the other flags in the collection.

Sets the variable that controls the number of digits inserted by the floating-point inserter to be x. This variable is a data member of the ios class; however, setting it with this function affects only output streams.

In the stream (ios or a stream derived from ios), sets the field width of the stream to w.

Synchronizing Access to User-Defined Stream Objects

The following parameterized manipulators are 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 you, the programmer. Refer to Chapter 6, "Mutex Package" for information on the Mutex class.

Locks the recursive Mutex represented by m.

Unlocks the recursive Mutex represented by m.

Examples

See Also

IMANIP(TYPE) class

IOMANIP(TYPE) class

OMANIP(TYPE) class

SMANIP(TYPE) class

Header

#include <fstream.hxx>

Alternative Header

#include <fstream.h>

Declaration

class filebuf: public streambuf
{
public:
    static const int    openprot;

                        filebuf();
                        filebuf(int fd);
                        filebuf(int fd, char *p, int len);
                        ~filebuf();

    filebuf             *attach(int fd);
    filebuf             *close();
    int                 fd();
    int                 is_open();
    filebuf             *open(const char *name, int mode,
                        int prot = openprot);

    virtual int         overflow(int = EOF);
    virtual streampos   seekoff(streamoff, seek_dir, int mode);
    virtual streampos   seekpos(streampos, int mode);
    virtual streambuf   *setbuf(char *p, int len);
    virtual int         sync();
    virtual int         underflow();
};

Description

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.

Warning; a null pointer to streambuf was passed to ios::init()

Data Member

Provides default protection for the open() function.

Constructors and Destructors

Constructs a filebuf object that is initially closed.

Constructs a filebuf object connected to file descriptor fd.

Constructs a filebuf object connected to file descriptor fd, which is initialized to use the reserve area (buffer) starting at p and containing len bytes.

Deletes a filebuf object.

Member Functions

Connects the filebuf object to an open file whose descriptor is passed through the fd argument. It normally returns a reference to the filebuf object, but returns 0 if the filebuf object is connected to an open file.

Flushes any waiting output, closes the file descriptor, and disconnects a filebuf object. Unless an error occurs, the filebuf object's error state will be cleared. The close() function returns the address of the filebuf object unless errors occur, in which case this function returns 0. Even if errors occur, close() leaves the file descriptor and filebuf object closed.

Returns the file descriptor associated with a filebuf object. If the filebuf object is closed, fd returns EOF.

Returns a nonzero value when a filebuf object is connected to a file descriptor; otherwise, it returns 0.

Opens a file with the name specified by name and connects a filebuf object to it. If the file does not exist, the function tries to create it with the protection mode prot unless ios::nocreate is specified in mode. By default, prot is filebuf::openprot.

The function fails if the filebuf object is open. The open() function normally returns the address of the filebuf object, but returns 0 if an error occurs. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

Called to consume characters in classes derived from streambuf. If c is not EOF, this function must also either save c or consume it. Although it can be called at other times, this function usually is called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != EOF) store c using sputc(). A call to overflow(c) should return EOF to indicate an error; otherwise, it should return something else.

Moves the get pointer, put pointer, or both as designated by the off and dir arguments. It may fail if the file does not support seeking, or if the attempted motion is otherwise invalid (for example, attempting to seek a position before the beginning of the file). The off argument is interpreted as a count relative to the place in the file specified by dir. The mode argument is ignored. A call to seekoff() returns the new position or EOF if a failure occurs. After a failure, the position of the file is undefined.

Moves the file to a position pos. The mode argument is ignored. The function normally returns pos but it returns EOF on failure.

Sets up the reserve area as the number of bytes specified in the second argument, beginning at the pointer specified in the first argument. If the pointer is null, or the number of bytes is less than 1, the filebuf object is unbuffered. This function normally returns a pointer to the filebuf object; however, if the filebuf object is open and a buffer is allocated, then no changes are made to the reserve area and to the buffering status, and setbuf() returns 0.

Tries to get the state of the get pointer, the put pointer, or both, to agree (synchronize) with the state of the file to which the filebuf object is connected. This means that the function may write characters to the file if some of the characters have been buffered for output, or the function may try to reposition (seek) the file if characters have been read and buffered for input. Normally sync() returns 0, but it returns EOF if synchronization is not possible.

When certain characters must be written together, the program should use setbuf() (or a constructor) to ensure that the reserve area is at least as large as the number of characters to be written together. Your program can then call sync(), store the characters, and then call sync() once again.

Called in classes derived from streambuf to supply characters for fetching; that is, to create a condition in which the get area is not empty. If the function is called when characters occupy the get area, it should create a nonempty area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

See Also

ios class

streambuf class

Header File

#include <fstream.hxx>

Alternative Header

#include <fstream.h>

Declaration

class fstream: public iostream
{
public:
                 fstream();
                 fstream(const char *name, int mode,
                     int prot = filebuf::openprot);
                 fstream(int fd);
                 fstream(int fd, char *p, int len);
                 ~fstream();

    void         attach(int fd);
    void         close();
    void         open(const char *name, int mode,
                     int prot = filebuf::openprot) ;
    filebuf      *rdbuf();
    void         setbuf(char *p, int len);
};

Description

This class specializes the iostream class to files by 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.

Constructors and Destructors

Constructs an unopened fstream object.

Constructs an fstream object connected to the file whose descriptor is passed through the fd argument. The file must be open.

Constructs an fstream object connected to a file whose descriptor is passed through the fd argument, and also initializes the associated filebuf object to use the len bytes starting at p as the reserve area. If p is null or len is 0, the filebuf object is unbuffered.

Constructs an fstream object and opens the file specified by the name argument. The mode and prot arguments specify the file open mode and protection. By default, prot is filebuf::openprot. If the open action fails, the error state (io_state) of the constructed fstream object indicates failure.

Deletes an fstream object.

Member Functions

Connects an fstream object to a file whose descriptor is passed through the fd argument. A failure occurs when the fstream object is connected to a file, in which case ios::failbit is set in the filebuf object's error state.

Closes any associated filebuf object and consequently breaks the connection of the fstream object to the file. The error state of the fstream object is cleared except on failure. A failure occurs when the call to the filebuf object's close() function fails.

Opens a file with the file name specified by name and connects the fstream object to it. If the file does not exist, the function tries to create it with the protection specified by the prot argument unless ios::nocreate is set. By default, prot is filebuf::openprot.

Failure occurs if the fstream object is open or when the call to the filebuf object's open() function fails, in which case ios::failbit is set in the filebuf object error state. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

Returns a pointer to the filebuf object associated with the fstream object. This function has the same meaning as ios::rdbuf(), but has a different type.

Calls the associated filebuf object setbuf() function to request space for a reserve area. A failure occurs if the filebuf object is open or if the call to rdbuf()->setbuf fails for any other reason.

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the istream object. It must be an identifier.

Description

class IAPP(TYPE)
{
public:
    IAPP(TYPE)(istream &(*f)(istream &, TYPE));
    IMANIP(TYPE) operator()(TYPE a);
}; 

Constructor

Creates an applicator; *f is the left operand of the insertion operator.

Operator

Casts an object of type a into a manipulator function for an istream object.

See Also

IMANIP(TYPE) class

Header File

#include <fstream.hxx>

Alternative Header

#include <fstream.h>

Declaration

class ifstream: public istream
{
public:
                ifstream();
                ifstream(const char *name, int mode = ios::in,
                     int prot = filebuf::openprot);
                ifstream(int fd);
                ifstream(int fd, char *p, int len);
                ~ifstream();

    void        attach(int fd);
    void        close();
    void        open(const char *name, int mode = ios::in,
                     int prot = filebuf::openprot);
    filebuf     *rdbuf();
    void        setbuf(char *p, int len);
};

Description

This class specializes the istream class to files by 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.

Constructors and Destructors

Constructs an unopened ifstream object.

Constructs an ifstream object connected to a file whose descriptor is passed through the fd argument. The file must already be open.

Constructs an ifstream object connected to a file whose descriptor is passed through the fd argument, and also initializes the associated filebuf object to use the len bytes starting at p as the reserve area. If p is null or len is 0, the filebuf object is unbuffered.

Constructs an ifstream object and opens the file with the file name specified by name. The mode and prot arguments specify the file open mode and protection. By default, prot is filebuf::openprot. If the open fails, the error state (io_state) of the constructed ifstream object indicates failure.

Deletes an ifstream object.

Member Functions

Connects an ifstream object to a file whose descriptor is passed through the fd argument. A failure occurs when the ifstream object is connected to a file, in which case ios::failbit is set in the ifstream object error state.

Closes any associated filebuf object and consequently breaks the connection of the ifstream object to the file. The error state of the fstream object is cleared except on failure. A failure occurs when the call to the filebuf object's close() function fails.

Opens a file specified by the name argument and connects the ifstream object to it. If the file does not exist, the function tries to create it with the protection specified by the prot argument unless ios::nocreate is set. By default, prot is filebuf::openprot.

Failure occurs if the ifstream object is open or when the call to the filebuf object open() function fails, in which case ios::failbit is set in the filebuf object error state. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

Returns a pointer to the filebuf object associated with the ifstream object. This function has the same meaning as ios::rdbuf() but has a different type.

Calls the associated filebuf object setbuf() function to request space for a reserve area. A failure occurs if the filebuf object is open or if the call to rdbuf()->setbuf fails for any other reason.

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the istream object. It must be an identifier.

Declaration

class IMANIP(TYPE)
{
public:
    IMANIP(TYPE)(istream &(*f)(istream &, TYPE), TYPE a);
    friend istream &operator>>(istream &s, IMANIP(TYPE) &m);
};

Description

These manipulators serve the istream class by producing some useful effect, such as embedding a function call in an expression containing a series of insertions and extractions. You also can use manipulators to shorten the long names and sequences of operations required by the iostream class.

In its simplest form, a manipulator takes an istream& argument, operates on it in some way, and returns it.

Constructor

Creates a manipulator; *f is the left operand of the extractor operator.

Operator

Takes data from an istream object.

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the iostream object. It must be an identifier.

Declaration

class IOAPP(TYPE)
{
public:
    IOAPP(TYPE)(iostream &(*f)(iostream &, TYPE));
    IOMANIP(TYPE) operator()(TYPE a);
};

Constructor

Creates an applicator.

Operator

Casts an object of type a into a manipulator function for an iostream object.

See Also

IOMANIP(TYPE) class

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the iostream object. It must be an identifier.

Declaration

class IOMANIP(TYPE)
{
public:
    IOMANIP(TYPE)(iostream &(*f)(iostream &, TYPE), TYPE a);
    friend istream &operator>>(iostream &s, IOMANIP(TYPE) &m);
    friend ostream &operator<<(iostream &s, IOMANIP(TYPE) &m);
};

IOMANIPdeclare(int);
IOMANIPdeclare(long);

Description

These manipulators serve the iostream class by producing some useful effect, such as embedding a function call in an expression containing a series of insertions and extractions. You can also use manipulators to shorten the long names and sequences of operations required by the iostream class.

In its simplest form, a manipulator takes an iostream& argument, operates on it in some way, and returns it.

Two ios manipulators for using Mutex objects, lock and unlock, come in both parameterized and unparameterized forms. The parameterized manipulators let users synchronize iostream objects, the parameter being a user-defined Mutex object. To use parameterized manipulators, you must include iomanip.hxx. Unparameterized manipulators let users synchronize the predefined stream objects: cerr, cin, clog, and cout.

For examples of using the lock and unlock manipulators, see Chapter 6, "Mutex Package" and the section on Global Declarations in this chapter.

Constructor

Creates a manipulator.

Macro

Declares the manipulators (and the manipulator classes) that have an operator() member function for type TYPE.

Operators

Sends data to an iostream object.

Takes data from an iostream object.

Header

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class ios
{
public:
    enum io_state       { goodbit = 0, eofbit = 01,
                          failbit = 02, badbit = 04 };
    enum open_mode      { in = 01, out = 02, ate = 04,
                          app = 010, trunc = 020,
                          nocreate = 040, noreplace = 0100 };
    enum seek_dir       { beg = 0, cur = 01, end = 02 };

    enum                { skipws = 01,
                          left = 02, right = 04, internal = 010,
                          dec = 020, oct = 040, hex = 0100,
                          showbase = 0200, showpoint = 0400,
                          uppercase = 01000,
                          showpos = 02000,
                          scientific = 04000, fixed = 010000,
                          unitbuf = 020000, stdio = 040000 };

    static const long   basefield;
    static const long   adjustfield;
    static const long   floatfield;

                        ios(streambuf *);
    virtual             ~ios();

    inline int          bad() const;
    static long         bitalloc();
    inline void         clear(int state = 0);
    inline int          eof() const;
    inline int          fail() const;
    inline char         fill() const;
    char                fill(char);
    inline long         flags() const;
    long                flags(long);
    inline int          good() const;
    long                &iword(int);
    inline int          operator!();
    inline              operator void *();
    inline int          precision() const;
    int                 precision(int);

    void                *&pword(int);
    inline streambuf    *rdbuf();
    inline int          rdstate() const;
    long                setf(long setbits, long field);
    long                setf(long);
    static void         sync_with_stdio();
    inline ostream      *tie() const;
    ostream             *tie(ostream *);
    long                unsetf(long);
    inline int          width() const;
    int                 width(int n);
    static int          xalloc();

protected:
                        ios();
    void                init(streambuf *);
    inline void         setstate(int state);

};

Description

Classes derived from the ios class provide an interface for transferring formatted and unformatted information into and out of streambuf objects.

Enumerated Types

Data Members

Collectively specifies the flags (bits) that control padding (left, right, and internal).

Collectively specifies the flags that control base conversion (dec, hex, and oct).

Constructors and Destructors

Constructs an ios object, associating the constructed ios object with the streambuf object pointed to by b. The object is initialized with the same default values as the ios() constructor.

Deletes an ios object.

Overloaded Operators

When defined, the following operators allow convenient checking of the error state of an ios.

Returns nonzero if failbit or badbit is set in the error state, which allows the use of such expressions as if (!cin) ...

Other Member Functions

Returns a nonzero value if badbit is set in the error state; otherwise, it returns 0.This usually indicates that some operation on rdbuf() has failed, and that continued operations on the associated streambuf object may not be possible.

Returns a long integer with a single, previously unallocated bit set. This gives you an additional flag should you need one (to pass to ios::set(), for example).

Stores an integer value as the error state. A 0 value clears all bits.

Returns a nonzero value if eofbit is set in the error state; otherwise, it returns 0.This bit is usually set during an extraction and when an end-of-file has been encountered.

Returns a nonzero value if either badbit or failbit is set in the error state; otherwise, it returns 0. This usually indicates that some extraction or conversion operation has failed, but that the stream remains usable; once failbit clears, operations on the stream can usually continue.

Returns the variable currently used as the fill (padding) character.

Sets c as the fill (padding) character if one is needed (see width ()) and returns the previous value. The default fill character is a space. The right, left, and internal flags determine positioning of the fill character. A parameterized manipulator, setfill, is also available for setting the fill character.

Returns the current format flags.

Returns a nonzero value if the error state has no bits set; otherwise, it returns 0.

Initializes the ios object; intended for use by classes derived from ios.

Returns a reference to the ith user-defined word, where i is an index into an array of words allocated by ios::xalloc.

Returns the precision format state variable.

Sets the precision format state variable to i and returns the previous value. The variable controls the number of significant digits inserted by the floating-point inserter. The default is 6. A parameterized manipulator, setprecision, is also available for setting the precision.

Returns a reference to the ith user-defined word, where i is an index into an array of words allocated by ios::xalloc. This function differs from iword() only in type.

Returns a pointer to the streambuf object that was associated with an ios object when the ios object was constructed.

Returns the current error state.

Makes available to the streambuf object associated with an ios object the format flags marked in setbits and returns the previous settings. A parameterized manipulator, setiosflags, performs the same function. If you are setting a flag that is part of a collection (for example, basefield), note that this manipulator does not clear the other flags in the collection.

Clears, in the streambuf object associated with an ios object, the format flags specified by field, then resets these flags to the settings marked in setbits. It returns the previous settings. Specifying 0 in setbits clears all the bits specified in field, as does the parameterized manipulator, resetioflags.

Changes only the bits specified in the state argument.

Solves problems that arise with mixing stdio and iostream objects. When first called, the sync_with_stdio() function resets the standard iostream functions (cin, cout, cerr, and clog) to be streams using stdiobuf objects. Subsequently, input and output using these streams may be mixed with input and output using the corresponding FILE parameters (stdin, stdout, and stderr), and properly synchronized. The sync_with_stdio() function makes cout and cerr unit buffered (see ios::unitbuf and ios::stdio). Invoking sync_with_stdio() degrades performance variably; the shorter the strings being inserted, the greater the degradation.

Returns the tie variable (see the following member function description).

Sets the tie variable to osp and returns its previous value. The tie variable supports automatic flushing of ios objects. The ios object that the tie variable points at is flushed if the variable is not null, and an ios object either needs more characters or has characters to be consumed. By default, cin is initially tied to cout so that attempts to get more characters from standard input result in flushing standard output. Additionally, cerr and clog are tied to cout by default. By default, the tie variable is set to 0 for other ios objects.

Unsets, in the streambuf object associated with an ios object, the bits set in setbits; it returns the previous settings.

Returns the field-width format variable (see the following member function description). The field width setting within the ios class is ignored during single character output: operator<<(char) and operator<<(unsigned char).

Sets the field-width format variable to n and returns the previous value. The field width specifies a minimum number of characters for inserters. When the variable is 0 (the default), inserters insert only as many characters as needed to represent the value being inserted. When the variable is nonzero, and the value being inserted needs fewer than field-width characters to be represented, inserters insert at least that many characters using the fill character to pad the value. Numeric inserters do not truncate values even if the value being inserted is more than field-width characters. After each insertion or extraction, the field-width format variable resets to 0. A parameterized manipulator, setw, is also available for setting the field width.

Returns a previously unused index into an array of words available for use by derived classes as format state variables.

Examples

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class iostream: public istream, public ostream
{
public:
               iostream(streambuf *);
    virtual    ~iostream();

protected:
               iostream();
};

Description

This class combines the istream and ostream classes. You use it to carry out bidirectional operations (inserting into and extracting from a single sequence of characters).

Constructors and Destructors

Constructs an iostream object, in undefined form, to enable inheritance by derived classes.

Constructs an iostream object. It initializes ios state variables and associates the iostream object with the streambuf object pointed to by b.

Deletes an iostream object.

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class iostream_withassign: public iostream
{
public:
                   iostream_withassign();
    virtual       ~iostream_withassign();

    iostream_withassign &operator=(iostream &);
    iostream_withassign &operator=(streambuf *);
};

Description

This class adds an assignment operator and a constructor with no operands to the iostream class.

Constructors and Destructors

Constructs an iostream_withassign object; it does no initialization.

Deletes an iostream_withassign object; no user action is required.

Overloaded Operators

Associates iostream->rdbuf() with an iostream_withassign object and initializes the entire state of that object.

Associates streambuf* with an iostream_withassign object and initializes the entire state of that object.

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class istream : virtual public ios
{
public:
                       istream(streambuf *);
    virtual            ~istream();

    inline int         gcount();
    istream            &get(char *ptr, int len,
                             char delim = '\n');
    istream            &get(unsigned char *ptr, int len,
                             char delim = '\n');
    istream            &get(char &);
    inline istream     &get(unsigned char &);
    istream            &get(streambuf &sb, char delim = '\n');
    int                get();
    istream            &getline(char *ptr, int len,
                             char delim = '\n');
    istream            &getline(unsigned char *ptr, int len,
                              char delim = '\n');
    istream            &ignore(int len = 1,
                             int delim = EOF);
    int                ipfx(int need = 0);
    void               isfx();
    int                peek();
    istream            &putback(char);
    istream            &read(char *s, int n);
    inline istream     &read(unsigned char *s, int n);
    istream            &seekg(streampos);
    istream            &seekg(streamoff, seek_dir);
    void               skipwhite();
    int                sync();
    streampos          tellg();
    istream            &operator>>(char *);
    istream            &operator>>(char &);
    istream            &operator>>(short &);
    istream            &operator>>(int &);
    istream            &operator>>(long &);
    istream            &operator>>(float &);
    istream            &operator>>(double &);
    istream            &operator>>(unsigned char *);
    istream            &operator>>(unsigned char &);
    istream            &operator>>(unsigned short &);
    istream            &operator>>(unsigned int &);
    istream            &operator>>(unsigned long &);
    istream            &operator>>(streambuf *);
    inline istream     &operator>>(istream &(*f)(istream &));
    istream            &operator>>(ios &(*f)(ios &));

protected:
                       istream();

};

Description

This class provides facilities for formatted and unformatted extraction from streambuf objects.

Constructors and Destructors

Constructs an istream object. It initializes ios state variables and associates the istream object with the buffer pointed to by sb.

Deletes an istream object.

Overloaded Operators

The following operators are all formatted input extractors. Given the expression ins >> x, these operators extract characters from ins and convert them to the variable x. The argument to the operator determines the type of x. Extractions are performed only if a call to ipfx(0) returns a nonzero value. Errors are indicated by setting the error state of ins. ios::failbit means that characters in ins did not represent the required type. ios::badbit means that attempts to extract characters failed. ins is always returned. The details of conversion depend on the values of the ins object format state flags and variables, and the type of x. Extractions that use width reset it to 0; otherwise, the extraction operators do not change the value of the istream object format state.

Extracts a character and stores it in x.

Extracts characters and stores them in the array pointed at by x, until a white-space character is found in the iostream object. The action leaves the terminating white-space character in the iostream object. If the iostream object's width() is nonzero, it is taken to be the size of the array and no more than width()–1 characters are extracted. A terminating null character ('\0') is always stored, even if nothing else is done because of the iostream object's error state. The iostream object's width() is reset to 0.

Extracts characters and converts them to an integral value according to the conversion specified in the iostream object's format flags. Converted values are stored in x. The first character can be a sign (- or +). After that, the conversion is octal if ios::oct is set in the iostream object's flags, decimal if ios::dec is set, or hexadecimal if ios::hex is set.

The first nondigit that is left in the iostream object terminates the conversion. If no conversion base flag is set, the conversion proceeds according to the VSI C++ lexical conventions: if the first characters (after the optional sign) are 0x or 0X, the conversion is hexadecimal; if the first character is 0, the conversion is octal; otherwise, the conversion is decimal. If no digits are available (not counting the 0 in 0x or 0X during hex conversion), ios::failbit is set.

Extracts characters and converts them according to the VSI C++ syntax for a float value or a double value. Converted values are stored in x. If no digits are available in the iostream object, or if the iostream object does not begin with a well formed floating-point or double number, ios::failbit is set.

Keeps getting characters from ios and inserting them into the buffer b until EOF is reached, if ios::ipfx(0) returns nonzero. Always returns the iostream object.

Calls an ios object manipulator function f for an istream object.

Calls an istream object manipulator function f for an istream object.

Other Member Functions

The unformatted input extractors, get, getline, ignore, and read, are among these functions. Before performing any extractions, these extractors, plus the unformatted function peek (which returns the next character without extracting it), call ipfx(1) and proceed only if a nonzero value is returned.

Returns the number of characters extracted by the last unformatted input function (get, getline, ignore, and read). Note that formatted input functions can call unformatted input functions and also reset this number.

Extracts a character and returns it, or returns EOF if the extraction encounters the end-of-file. It never sets ios::failbit.

Extracts a single character and stores it in &ptr.

The function stores a terminating null, even if it does not extract any characters because of its error status. The extraction sets ios::failbit only if it reaches an end-of-file before storing any characters.

Extracts characters from an istream object rdbuf() function and stores them into sb. It stops if it encounters the end-of-file, if a store into sb fails, or if it encounters delim (which it leaves in the istream object). The function sets ios::failbit if the extraction stops because the store operation into sb fails.

Functions the same as get(char *, int, char) except that these extract a terminating delim character from an istream object. If delim occurs when exactly len characters have been extracted, a filled array is considered to be the cause of the termination and the extraction leaves this delim in the istream object.

Extracts and discards up to len characters. Extraction stops prematurely if delim is extracted or the end-of-file is reached. If delim is EOF, it can never cause termination.

Returns 0 if the error state of an istream object is nonzero. If necessary (and if it is not null), the function flushes any ios tied to the istream object (see the description of ios::tie()). Flushing is considered necessary if need is set to 0 or if fewer than need characters are immediately available. If ios::skipws is set in the istream object's flags() function, and need is 0, then the function extracts the leading white-space characters from the istream object. The function returns 0 if an error occurs while skipping white space; otherwise, it returns a nonzero value.

Performs input suffix operations (used for internal processing).

Begins by calling ipfx(1). If that call returns 0, or if the istream object is at the end-of-file, the function returns EOF. Otherwise, it returns the next character without extracting it.

Tries to back up an istream object rdbuf() function. c must be the character before the get pointer belonging to the istream object rdbuf(). (Unless some other activity is modifying the istream object rdbuf(), this is the last character extracted from the istream object.) If c is not the character before the get pointer, the effect of the function is undefined; the backup may fail and set the error state. The putback function is a member of the istream object, but it never extracts characters so it does not call ipfx. However, it returns without doing anything if the error state is nonzero.

Extracts n characters and stores them in the array begining at s. If it reaches the end-of-file before extracting n characters, the function stores whatever it can extract and sets ios::failbit. To determine the number of characters extracted, use the istream gcount() function.

Repositions the get pointer of an istream object rdbuf() function.

Establishes consistency between internal data structures and the external source of characters. Calls an istream object rdbuf()->sync(), which is a virtual function, so the details depend on the derived class. Returns EOF to indicate errors.

Skips extracted white-space characters.

Returns the current position of the get pointer of an istream object rdbuf() function.

Examples

See Also

ios class

istream_withassign class

istrstream class

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class istream_withassign: public istream
{
public:
                        istream_withassign();
    virtual             ~istream_withassign();

    istream_withassign  &operator=(istream &);
    istream_withassign  &operator=(streambuf *);
};

Description

This class adds an assignment operator and a constructor with no operands to the istream class.

Constructors and Destructors

Constructs an istream_withassign object; it does no initialization.

Deletes an istream_withassign object; no user action is required.

Overloaded Operators

Associates an istream object's rdbuf() function with an istream_withassign object and initializes the entire state of that object.

Associates sb with an istream_withassign object and initializes the entire state of that object.

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class istrstream: public istream
{
public:
                        istrstream(char *);
                        istrstream(char *, int);

    strstreambuf        *rdbuf();
};

Description

Objects of this class perform in-core extractions from arrays of bytes in memory.

Constructors and Destructors

Constructs an istrstream object and fetches characters from the (null terminated) string cp. The terminating null character does not become part of the sequence. Seeks (istream::seekg()) are permitted within the allocated space.

Constructs an istrstream object and fetches characters from the array beginning at cp and extending for len bytes. Seeks (istream::seekg()) are permitted anywhere within that array.

Member Function

Returns the strstreambuf object associated with the istrstream object.

Header File

(#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the ostream object. It must be an identifier.

Declaration

class OAPP(TYPE)
{
public:
    OAPP(TYPE)(ostream &(*f)(ostream &, TYPE));
    OMANIP(TYPE) operator()(TYPE a);
}; 

Constructor

Creates an applicator.

Operator

Casts an object of type a into a manipulator function for an ostream object.

See Also

OMANIP(TYPE) class

Header File

#include <fstream.hxx>

Alternative Header

#include <fstream.h>

Declaration

class ofstream: public ostream
{
public:
                 ofstream();
                 ofstream(const char *name, int mode = ios::out,
                         int prot = filebuf::openprot);
                 ofstream(int fd);
                 ofstream(int fd, char *p, int len);
                 ~ofstream();

    void         attach(int fd);
    void         close();
    void         open(const char *name, int mode = ios::out,
                         int prot = filebuf::openprot);
    filebuf      *rdbuf();
    void         setbuf(char *p, int len);
};

Description

This class specializes the ostream class 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.

Constructors and Destructors

Constructs an unopened ofstream object.

Constructs an ofstream object connected to a file whose descriptor is passed through the fd argument. The file must already be open.

Constructs an ofstream object connected to a file whose descriptor is passed through the fd argument, and also initializes the associated filebuf object to use the len bytes starting at p as the reserve area. If p is null or len is 0, the filebuf object is unbuffered.

Constructs an ofstream object and opens the file specified by the name argument. The mode and prot arguments specify the file open mode and protection. By default, prot is filebuf::openprot. If the open fails, the error state (io_state) of the constructed ofstream object indicates failure.

Deletes an ofstream object.

Member Functions

Connects an ofstream object to a file whose descriptor is passed through the fd argument. A failure occurs when the ifstream object is connected to a file, in which case ios::failbit is set in the ofstream object error state.

Closes any associated filebuf object and consequently breaks the connection of the ofstream object to the file. The error state of the ofstream object is cleared except on failure. A failure occurs when the call to the filebuf object close() function fails.

Opens a file specified by the name argument and connects the ofstream object to it. If the file does not exist, the function tries to create it with the protection specified by the prot argument unless ios::nocreate is set. By default, prot is filebuf::openprot.

Failure occurs if the ofstream object is open or when the call to the filebuf object open() function fails, in which case ios::failbit is set in the filebuf object's error state. The members of open_mode are bits that may be joined together by or (and because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

Returns a pointer to the filebuf object associated with the ofstream object. This function has the same meaning as ios::rdbuf(), but has a different type.

Calls the associated filebuf object setbuf() function to request space for a reserve area. A failure occurs if the filebuf object is open or if the call to rdbuf()->setbuf fails for any other reason.

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the ostream object. It must be an identifier.

Declaration

class OMANIP(TYPE)
{
public:
    OMANIP(TYPE)(ostream &(*f)(ostream &, TYPE), T a );
    friend ostream &operator<<(ostream & s, OMANIP(TYPE) &m);
}; 

Description

These manipulators serve the ostream class by producing some useful effect, such as embedding a function call in an expression containing a series of insertions and extractions. You also can use manipulators to shorten the long names and sequences of operations required by the ostream class.

In its simplest form, a manipulator takes an ostream& argument, operates on it in some way, and returns it.

Constructor

Creates a manipulator.

Operator

Sends data to an ostream object.

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class ostream : virtual public ios
{
public:
                        ostream(streambuf *);
    virtual             ~ostream();

    ostream             &flush();
    int                 opfx();
    void                osfx();
    ostream             &put(char c);
    ostream             &seekp(streampos);
    ostream             &seekp(streamoff, seek_dir);
    streampos           tellp();
    ostream             &write(const char *ptr, int n);
    inline ostream      &write(const unsigned char *ptr, int n);
    ostream             &operator<<(const char *);
    ostream             &operator<<(char);
    inline ostream      &operator<<(short);
    ostream             &operator<<(int);
    ostream             &operator<<(long);
    ostream             &operator<<(float);
    ostream             &operator<<(double);
    ostream             &operator<<(const unsigned char *);
    inline ostream      &operator<<(unsigned char);
    inline ostream      &operator<<(unsigned short);
    ostream             &operator<<(unsigned int);
    ostream             &operator<<(unsigned long);
    ostream             &operator<<(void *);
    ostream             &operator<<(streambuf *);
    inline ostream      &operator<<(ostream &(*f)(ostream &));
    ostream             &operator<<(ios &(*f)(ios &));

protected:
                        ostream();
};

Description

Objects of this class perform formatted and unformatted insertions into streambuf objects.

Constructors and Destructors

Constructs an istream object. It initializes ios state variables and associates the buffer b with the ostream object.

Deletes an ostream object.

Overloaded Operators

The following operators are all formatted output inserters. Given the expression outs << x, these operators insert into outs.rdbuf() a sequence of characters representing x. The argument to the operator determines the type of x. Insertions are performed after a call to outs.opfx() only if that call returns nonzero. Errors are indicated by setting the error state of the ostream object. The ostream object is always returned.

Conversion of x to a sequence of characters depends on the type of x and on the values of the ostream object's format state flags and variables. Padding occurs after this representation is determined. If width() is greater than 0, and the representation contains fewer than width() characters, then the function adds enough fill() characters to bring the total number of characters to ios::width(). If ios::left() is set, the sequence is left-adjusted; that is, the function puts the padding after the sequence of characters. If ios::right() is set, the padding is added before the character sequence. If ios::internal() is set, the padding is added after any leading sign or base indication and before the characters that represent the value. ios::width() is reset to 0 but all other format variables are unchanged. The full sequence (padding plus representation) is inserted into the ostream object rdbuf() function.

Inserts a character x. No special conversion is needed.

Inserts a sequence of characters up to (but not including) the terminating null of the string that x points at.

Converts the arguments according to the current values of the ostream object's precision() function, the ostream object's width() function, and the ostream object's format flags: ios::scientific, ios::fixed, and ios::uppercase. The default value for the ostream object's precision() function is 6. If neither ios::scientific nor ios::fixed is set, the value of x determines whether the representation uses scientific or fixed notation.

Converts pointers to integral values and then converts them to hexadecimal numbers as if ios::showbase was set.

Given the expression outs << sb, inserts into sb.rdbuf() the sequence of characters that can be fetched from sb. When no more characters can be fetched from sb, insertion stops. This function does no padding. It always returns the ostream object.

Calls an ios object manipulator function f for an ostream object.

Calls an ostream object manipulator function f for an ostream object.

Other Member Functions

Calls the ostream object's rdbuf()->sync() function to consume (that is, write to the external file) any characters that may have been stored into a streambuf object but are not yet consumed.

Performs output prefix actions. If the error state of the ostream object is nonzero, it returns immediately. If the value of the ostream object's tie() function is not null, it is flushed. The function returns nonzero except when the error state of the ostream object is nonzero.

Performs output suffix actions before returning from inserters. If ios::unitbuf is set, this function flushes the ostream object. If ios::stdio is set, the function flushes stdout and stderr. It is called by all predefined inserters, and should also be called by user-defined inserters after any direct manipulation of the streambuf object. It is not called by the binary output functions.

Inserts c into the ostream object's rdbuf() function. It sets the error state if the insertion fails.

Repositions the put pointer of the ostream object's rdbuf() function.

Returns the current position of the put pointer belonging to the ostream object's rdbuf() function.

Inserts the n characters starting at ptr into the ostream object's rdbuf() function. These characters may include zeros; that is, ptr need not be a null-terminated string.

Example

char c = 'Z';
cout.put(c);

Inserts a single character (Z) into cout.

See Also

ostream_withassign class

ostrstream class

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class ostream_withassign: public ostream
{
public:
                        ostream_withassign();
    virtual             ~ostream_withassign();

    ostream_withassign  &operator=(ostream &);
    ostream_withassign  &operator=(streambuf *);
};

Description

This class adds an assignment operator and a constructor with no operands to the ostream class.

Constructors and Destructors

Constructs an ostream_withassign object; it does no initialization.

Deletes an ostream_withassign object; no user action is required.

Overloaded Operators

Associates s.rdbuf() with the ostream_withassign object and initializes the entire state of that object.

Associates sb with an ostream_withassign object and initializes the entire state of that object.

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class ostrstream: public ostream
{

public:
                      ostrstream();
                      ostrstream(char *, int, int = ios::out);
                      ~ostrstream();

     int              pcount();
     strstreambuf     *rdbuf();
     char             *str();
};

Description

This class specializes the ostream class for in-core operations by providing members that insert characters into arrays of bytes in memory.

Constructors and Destructors

Constructs an ostrstream object and dynamically allocates space to hold stored characters.

Constructs an ostrstream object and stores characters into the array starting at cp and continuing for n bytes. If ios::ate or ios::app is set in mode, the function takes cp to be a null-terminated string and it begins storing at the null character; otherwise, it begins storing at cp. Seeks are allowed anywhere in the array.

Deletes an ostrstream object.

Member Functions

Returns the number of bytes that have been stored into the buffer. This function is useful when binary data has been stored and the ostrstream object str() function does not point to a null-terminated string.

Returns the strstreambuf associated with the ostrstream object.

Returns a pointer to the array being used and freezes the array. After str() has been called, the effect of storing more characters into the strstream object is undefined. If the strstream object was constructed with an explicit array, the function returns a pointer to the array; otherwise, it returns a pointer to a dynamically allocated area. Until str() is called, deleting the dynamically allocated area is the responsibility of the strstream object. After str() returns, dynamic allocation becomes the responsibility of the user program.

Example

char *bptr = bf.str()

Initializes the variable bptr with the address of the array associated with the ostrstream object bf. This lets you manipulate the array through bptr just as you would any character array.

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the ios object. It must be an identifier.

Declaration

class SAPP(TYPE)

{
public:
    SAPP(TYPE)(ios &(*f)(ios &, TYPE));
    SMANIP(TYPE) operator()(TYPE a);
}; 

Constructor

Creates an applicator.

Operator

Casts an object of type a into a manipulator function for an istream or ostream object.

See Also

SMANIP(TYPE) class

Header File

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>

Compile-Time Parameter

TYPE — The type of the ios object. It must be an identifier.

Declaration

class SMANIP(TYPE)
{
public:
    SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a);
    friend istream &operator>>(istream &i, SMANIP(TYPE) &m);
    friend ostream &operator<<(ostream &o, SMANIP(TYPE) &m);
}; 

Description

These manipulators serve the ios class by producing some useful effect, such as embedding a function call in an expression containing a series of insertions and extractions. You also can use manipulators to shorten the long names and sequences of operations required by the ios class.

In its simplest form, a manipulator takes an ios& argument, operates on it in some way, and returns it.

Constructor

Creates a manipulator.

Operators

Sends data to an ostream object.

Takes data from an istream object.

Header File

#include <stdiostream.hxx>

Alternative Header

#include <stdiostream.h>

Declaration

class stdiobuf: public streambuf
{
public:
                        stdiobuf(FILE *f);

    virtual int         overflow(int = EOF);
    virtual streampos   seekoff(streamoff, seek_dir, int mode);
    FILE                *stdiofile();
    virtual int         sync();
    virtual int         underflow();
};

Description

This class specializes the streambuf class for stdio FILE. It uses unbuffered mode causing all operations to be reflected immediately in the stdio FILE.

Constructor

Constructs an empty stdiobuf object and connects it to the stdio FILE that the argument f points to.

Member Functions

Called to consume characters. If c is not EOF, this function must also either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != EOF) store c using sputc(). The overflow(c) function should return EOF to indicate an error; otherwise, it should return something else.

Repositions the abstract get and put pointers (not pptr() and gptr()). mode specifies whether to modify the put pointer (ios::out bit set), the get pointer, or both (ios::in bit set). off is interpreted as a byte offset. For the meanings of dir, see the explanation of the enumerated type seek_dir in class ios.

A class derived from streambuf is not required to support repositioning. If the derived class does not, then seekoff() should return EOF. If the derived class does support repositioning, seekoff() should return the new position or EOF on error.

Returns a pointer to the stdio FILE associated with the stdiobuf object.

Should consume any characters stored into the put area and, if possible, give back to the source any characters in the get area that have not been fetched. When sync() returns, there should be no unconsumed characters and the get area should be empty. If some kind of failure occurs, the function should return EOF.

Called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

Header File

#include <stdiostream.hxx>

Alternative Header

#include <stdiostream.h>

Declaration

class stdiostream: public iostream
{
public:
                stdiostream(FILE *f);
                ~stdiostream();

    stdiobuf    *rdbuf();
};

Description

This class specializes the iostream class for stdio FILE, and causes that class to use a stdiobuf object as its associated streambuf object.

In most other existing implementations, the stdiostream class is derived directly from the ios class rather than from the iostream class. Deriving the stdiostream class from the ios class limits its usefulness and, therefore, can be considered a historical mistake. Nevertheless, for maximum portability, you should use only those stdiostream features that originate from the ios class and avoid the features supplied by the iostream class.

Constructors and Destructors

Constructs a stdiostream object whose stdiobuf object is associated with the FILE parameter that the f argument points to.

Deletes a stdiostream object and closes the associated stdiobuf object.

Member Function

Returns a pointer to the stdiobuf object associated with the stdiostream object.

Header File

#include <iostream.hxx>

Alternative Header

#include <iostream.h>

Declaration

class streambuf
{
public:
                        streambuf();
                        streambuf(char *p, int len);
    virtual             ~streambuf();
    void                dbp();

protected:
    int                 allocate();
    char                *base();
    int                 blen();

    virtual int  doallocate();

    char                *eback();
    char                *ebuf();
    char                *egptr();
    char                *epptr();
    void                gbump(int n);
    char                *gptr();
    char                *pbase();
    void                pbump(int n);
    char                *pptr();
    void                setb(char *b, char *eb, int a = 0);
    void                setg(char *eb, char *g, char *eg);
    void                setp(char *p, char *ep);
    int                 unbuffered();
    void                unbuffered(int n);

public:
    int                 fd();
    void                fd(int);
    FILE                *fp();
    void                fp(FILE *);
    int                 in_avail();
    int                 out_waiting();

    virtual int         overflow(int c = EOF);
    virtual int         pbackfail(int c);

    int                 sbumpc();

    virtual streampos   seekpos(streampos, int = ios::in
                        | ios::out);
    virtual streampos   seekoff(streamoff, seek_dir,
                        int = ios::in | ios::out);
    virtual streambuf   *setbuf(char *ptr, int len);

    streambuf           *setbuf(unsigned char *ptr, int len);
    streambuf           *setbuf(char *ptr, int len, int i);
    int                 sgetc();
    int                 sgetn(char *ptr, int n);
    int                 snextc();
    int                 sputbackc(char c);
    int                 sputc(int c = EOF);
    int                 sputn(const char *s, int n);
    void                stossc();

    virtual int         sync();
    virtual int         underflow();
};

Description

This class supports buffers into which you can insert (put) or extract (get) characters. It contains only the basic members for manipulating the characters. Also, several of its member functions are virtual; to implement virtual functions, you typically use a class derived from the streambuf class.

The protected members of the streambuf class present an interface to 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, even though they point directly 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.

You can call virtual functions to manage the collections of characters in the get and put areas. Services supplied by virtual functions include fetching more characters from an ultimate producer and flushing a collection of characters to an ultimate consumer.

If your program expects a buffer to be allocated when none was allocated, then the iostream package allocates a default buffer.

Data Member

Writes directly on file descriptor 1 information in ASCII about the state of the buffer. It is intended for debugging and nothing is specified about the form of the output. What it prints out can be understood only in relation to the protected interface, but dbp() is a public domain function so that it can be called anywhere during debugging.

Constructors and Destructors

Constructs an empty buffer corresponding to an empty sequence.

Constructs an empty buffer and then sets up the reserve area to be length bytes long starting at base.

Deletes the reserve area if one is allocated.

Member Functions

Tries to set up a reserve area. If a reserve area already exists or is unbuffered, it returns 0 without doing anything. If the attempt to allocate space succeeds, allocate() returns 1; otherwise, it returns EOF. No nonvirtual member functions of streambuf call allocate().

Returns a pointer to the first byte of the reserve area. The space between base() and ebuf() is the reserve area.

Returns the size, in type char, of the current reserve area.

In streambuf, it tries to allocate a reserve area using the new operator.

In classes derived from streambuf, this function is called when allocate() determines that space is needed. doallocate() is required to call setb(), to provide a reserve area, or to return EOF if it cannot. It is called only if both unbuffered() and base() are 0.

Returns a pointer to a lower bound on gptr(). The space between eback() and gptr() is available for putback operations.

Returns a pointer to the byte after the last byte of the reserve area.

Returns a pointer to the byte after the last byte of the get area.

Returns a pointer to the byte after the last byte of the put area.

Returns the file descriptor associated with the streambuf object, if any; otherwise, it returns –1.

Sets the file descriptor associated with the streambuf object to f.

Returns the file pointer associated with the streambuf object, if any; otherwise, it returns 0.

Sets the file pointer associated with the streambuf object to f.

Increments gptr() by n, which can be a positive or a negative number. No checks are made on whether the new value of gptr()is in bounds.

Returns a pointer to the first byte of the get area. The characters available are those between gptr() and egptr(). The next character fetched will be *gptr() unless egptr() is less than or equal to gptr().

Returns the number of characters immediately available in the get area for fetching. This number is the number of characters that can be fetched with confidence that an error will not be reported.

Returns the number of characters in the put area that have not been consumed (by the ultimate consumer).

In streambuf, this function should be treated as if its behavior is undefined; classes derived from streambuf should always define it.

In classes derived from streambuf, it is called to consume characters. If c is not EOF, overflow(c) also must either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != EOF) store c using sputc(). overflow(c) should return EOF to indicate an error; otherwise, it should return something else.

In streambuf, this function always returns EOF.

In classes derived from streambuf, this function is called when eback() equals gptr() and an attempt has been made to put c back. If this situation can be managed (for example, by repositioning an external file), pbackfail(c) should return c; otherwise, it should return EOF.

Returns a pointer to the put area base. Characters between pbase() and pptr() are stored into the buffer but are not yet consumed.

Increments pptr() by n, which can be positive or negative. No checks are made on whether the new value of pptr() is in bounds.

Returns a pointer to the first byte of the put area. The space between pptr() and epptr() is the put area.

Moves the get pointer forward one character and returns the character it moved past. The function returns EOF if the get pointer is currently at the end of the sequence.

In streambuf, this function returns EOF.

In classes derived from streambuf, it repositions the abstract get and put pointers (not pptr() and gptr()). mode specifies whether to modify the put pointer (ios::out bit set) or the get pointer (ios::in bit set) or both pointers. off is interpreted as a byte offset (it is a signed value). For the meanings of dir, see the explanation of the enumerated type seek_dir in class ios.

A class derived from streambuf is not required to support repositioning. If the derived class does not, then seekoff() should return EOF. If the derived class does support repositioning, seekoff() should return the new position or EOF on error.

In streambuf, this function returns seekoff(streamoff(pos), ios::beg, mode). To define seeking in a derived class, you can often define seekoff() and use the inherited streambuf::seekpos.

In classes derived from streambuf, this function repositions the streambuf get pointer, put pointer, or both, to pos. mode specifies the affected pointers. seekpos() returns the argument pos or EOF if the class does not support repositioning or if an error occurs. streampos(0) signifies the beginning of the file; streampos(EOF) indicates an error.

Sets base() to b and ebuf() to eb. The a argument controls whether the reserve area will be subject to automatic deletion. If a is nonzero, then b will be deleted when base() is changed by another call to setb(), or when the destructor is called for the streambuf object. If b and eb are both null, then the reserve area effectively does not exist. If b is nonnull, a reserve area exists even if eb is less than b (in which case the reserve area has 0 length).

In streambuf, this function honors the request for a reserve area if there is none.

In classes derived from streambuf, this function offers for use as a reserve area the array at ptr with len bytes. Normally, if ptr or len is 0, the action is interpreted as a request to make the streambuf object unbuffered. The derived class has the choice of using or not using this area by accepting or ignoring the request. setbuf() should return a reference to the streambuf object if the derived class honors the request; otherwise, it should return 0.

Offers the len bytes starting at ptr as the reserve area. If ptr is null, or len is 0 or negative, then the function requests an unbuffered state. Whether the offered area is used or a request for an unbuffered state is honored depends on details of the derived class. setbuf() normally returns a reference to the streambuf object, but if the derived class does not accept the offer or honor the request, setbuf() returns 0.

Sets eback() to eb, gptr() to g, and egptr() to eg.

Sets base() and pptr() to p and epptr() to ep.

Returns the character after the get pointer; it does not move the get pointer. It returns EOF if no character is available.

Fetches n characters following the get pointer and copies them to the area starting at ptr. If fewer than n characters occur before the end of the sequence, sgetn() fetches the characters that remain. It repositions the get pointer after the fetched characters and returns the number of characters fetched.

Moves the get pointer forward one character and returns the character after the new position. If the pointer is at the end of the sequence, either before or after moving forward, the function returns EOF.

Moves the get pointer back one character. c must be the current content of the sequence just before the get pointer. The underlying mechanism may back up the get pointer or may rearrange its internal data structures so that c is saved. The effect is undefined if c is not the character before the get pointer. The function returns EOF, by calling pbackfail(), when it fails. The conditions under which it can fail depend on the details of the derived class.

Stores c after the put pointer and moves the put pointer past the stored character (usually this extends the sequence). The function returns EOF when an error occurs. Conditions that can cause errors depend on the derived class.

Stores after the put pointer the n characters starting at s, and moves the put pointer past them. It returns the number of characters successfully stored. Normally n characters are successfully stored, but fewer characters may be stored when errors occur.

Moves the get pointer ahead one character. If the pointer started at the end of the sequence, stossc() has no effect.

In streambuf this function returns 0 if the get area is empty and no unconsumed characters are present; otherwise, it returns EOF.

In classes derived from streambuf, this function is called to let derived classes examine the state of the put, get, and reserve areas, and to synchronize these areas with any external representation. Normally sync() should consume any characters stored into the put area and, if possible, give back to the source any characters in the get area that have not been fetched. When sync() returns, no unconsumed characters should remain and the get area should be empty. If some kind of failure occurs, sync() should return EOF.

Returns the current buffering state flag, which is independent of the actual allocation of a reserve area. This function's primary purpose is to find out if a reserve area is being allocated automatically by allocate().

Sets the value of the current buffering state flag. If n equals 0, then the streambuf object is buffered; otherwise it is unbuffered. This function's primary purpose is to control whether a reserve area is allocated automatically by allocate().

In streambuf, this function should be treated as if its behavior is undefined; classes derived from streambuf must define it.

In classes derived from streambuf, it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

Example

static const int bufsize = 1024;
char buf[bufsize] ;
int p, g ;
do {
        in->sgetc() ; 
        g = in->in_avail() ;  
        if (g > bufsize) g = bufsize ;  
        g = in->sgetn(buf,g) ;
        p = out->sput(buf,g) ;
        out->sync() ;  
        if (p!=g) error("output error");
        } while (g > 0)

Provides a way to pass characters into the in and out arrays as soon as the characters become available (as when someone types them from a terminal) as follows:

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class strstream: public iostream
{
public:
                     strstream();
                     strstream(char *, int, int);

    strstreambuf     *rdbuf();
    char             *str();
};

Description

This class specializes the iostream class 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.

Constructors and Destructors

Constructs an strstream object and dynamically allocates space to hold stored characters.

Constructs an strstream object. It stores characters into the array starting at cp and continuing for n bytes. If ios::ate or ios::app is set in mode, cp is presumed to be a null-terminated string and storing begins at the null character; otherwise, storing begins at cp. Seeks are permitted anywhere in the array.

Member Functions

Returns a pointer to the strstreambuf object associated with a strstream object.

Returns a pointer to an explicit array, to be used as the associated strstreambuf object, if the strstream object was constructed with such an array; otherwise, it returns a pointer to a dynamically allocated area. Until str() is called, deleting the dynamically allocated area is the responsibility of the strstream object. After str() returns, dynamic allocation becomes the responsibility of the user program. After str() has been called, the effect of storing more characters into the strstream object is undefined.

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class strstreambuf: public streambuf
{
public:
                        strstreambuf();
                        strstreambuf(char *, int, char *);
                        strstreambuf(int);
                        strstreambuf(unsigned char *, int,
                        unsigned char *);
                        strstreambuf(void *(*a)(long),
                        void (*f)(void *));

    void                freeze(int n = 1);
    virtual int         overflow(int);
    virtual streambuf   *setbuf(char *, int);
    char                *str();
    virtual int         underflow();
};

Description

Objects of this class let you use an array of bytes (a string of characters) in memory as a streambuf object 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 logically pointing immediately ahead of the char it actually 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.

Warning; a null pointer to streambuf was passed to ios::init()

Constructors and Destructors

Constructs an empty strstreambuf object in dynamic mode. This means that space is automatically allocated to accommodate characters put into the strstreambuf object (using the new and delete operators). Because this may require copying the original characters, programs that have many characters to insert should use setbuf() to inform the strstreambuf object about the needed allocation of space, or to use one of the constructors that follow.

Constructs an empty strstreambuf object in dynamic mode. The initial allocation of space is at least n bytes.

Constructs a strstreambuf object to use the bytes starting at ptr. The strstreambuf object is in static mode; it does not grow dynamically. If n is positive, then the n bytes starting at ptr are used as the strstreambuf object. If n is 0, ptr is presumed to point to the beginning of a null-terminated string and the bytes of that string (not including the terminating null character) constitute the strstreambuf object. If n is negative, then the strstreambuf object is presumed to continue indefinitely.

The get pointer is initialized to ptr. The put pointer is initialized to pstart. If pstart is not null, then the initial sequence for fetching (the get area) consists of the bytes between ptr and pstart. If pstart is null, then storing operations are treated as errors and the initial get area consists of the entire array.

Constructs an empty strstreambuf object in dynamic mode. a is used as the allocator function in dynamic mode. The argument passed to a is a long denoting the number of bytes to be allocated. If the a argument is null, the new operator is used. f is used to free (or delete) get, put, or reserve areas returned by a. The argument to f becomes a pointer to the array allocated by a. If f is null, the delete operator is used.

Member Functions

Inhibits (freezes) automatic deletion of the current array if n is nonzero, or permits (unfreezes) automatic deletion if n is 0. Deletion normally occurs when more space is needed, or when the strstreambuf object is being destroyed. Only space obtained through dynamic allocation is free. Storing characters into a strstreambuf that was dynamically allocated and is now frozen causes an error (the effect is undefined). If you want to resume storing characters in such a strstreambuf object you can thaw (unfreeze) it.

In classes derived from streambuf, it is called to consume characters. If c is not EOF, overflow(c) also must either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != OF) store c using sputc(). overflow(c) should return EOF to indicate an error; otherwise, it should return something else.

Causes the strstreambuf object to remember n (if ptr is 0); this ensures that at least n bytes are allocated during the next dynamic mode allocation.

Returns a pointer to the first character in the current array and freezes the strstreambuf object. If the strstreambuf object was constructed with an explicit array, the function returns a pointer to that array. If the strstreambuf object is in dynamic allocation mode but nothing has been restored yet, the returned pointer is null.

In classes derived from streambuf, it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

Header File

#include <messages.hxx>

Alternative Header

None.

Declaration

class Messages
{
public:
   Messages(const char *filename_arg, int set_arg = 0,
        const char *default_file_location_arg = (const char *)(NULL));
   ~Messages();

   const char *text(int msg_arg, const char *fallback_text_arg,
         int set_arg = 0);
};

Constructors and Destructors

Constructs a Messages object.

Deletes a Messages object.

Member Function

Returns the text of the message specified by the msg_arg argument. The fallback_text_arg argument indicates the text to return if the message cannot be found. The set_arg argument specifies the message set number; a value of 0 causes the system to use the set number provided to the constructor.

Example

.TITLE MESSAGES_EXAMPLE_MSG Example messages -- VMS message catalog
.IDENT ’1.0’
.FACILITY EXAMPLE, 1 /PREFIX=EXAMPLE_
.BASE 0
.SEVERITY WARNING ! we just want a 0 in the severity field
SET <> ! message set number
.SEVERITY ERROR
EXAMPLE_ERROR <This is an example error message>
.END
Entering the following OpenVMS Message Utility commands set the
appropriate options and compile this file:
$ set message/nofac/nosev/noid
$ message/lis MESSAGES_EXAMPLE_MSG

$ set message/nofac/nosev/noid
$ message/lis MESSAGES_EXAMPLE_MSG

#include <iostream.hxx>
#include <messages.hxx>
const char *message_file_name = (const char *)(NULL);
const char *message_file_location = (const char *)(NULL);
#pragma __extern_model __save
#pragma __extern_model __globalvalue
extern int EXAMPLE_SET;
#pragma __extern_model __restore
int message_set_example = EXAMPLE_SET;
Messages m_example (message_file_name, message_set_example,
message_file_location);
int main()
{
cout <<
"text of example message 1: " <<
m_example.text(1, "fallback message 1") <<
"\n";
cout <<
"text of example message 2: " <<
m_example.text(2, "fallback message 2") <<
"\n";
return 0;
}

$ cxx/lis MESSAGES_EXAMPLE

$ link MESSAGES_EXAMPLE,MESSAGES_EXAMPLE_MSG
$ run/nodeb messages_example
text of example message 1: This is an example error message
text of example message 2: fallback message 2

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. VSI 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, "iostream Package").

Constructors and Destructors

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

Deletes a Mutex object.

Member Functions

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

Unlocks a recursive mutex.

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.

Header

#include <objection.hxx>

Alternative Header

#include <Objection.h>

Declaration

typedef int Objection_action(const char*);

Type

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

Header

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

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

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

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.

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

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.

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.

#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);
}

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

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

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

Member Functions

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

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

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

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.

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

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.

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

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.

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 VSI 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

Constructs a String object initialized to an empty string.

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

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

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

Deletes a String object; no user action is required.

Overloaded Operators

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

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

Concatenates a String object with another String object.

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

Assigns a String object to another String object.

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

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

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

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

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

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

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

Concatenates a String object to another String object.

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

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.

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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.

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

Examples

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

typedef int(*PFIO)(int, object*);
typedef void(*PFV)();

enum
{
    VERBOSE = 1 << 0,
    CHAIN = 1 << 1,
    STACK = 1 << 2,
};

enum qmodetype
{
    EMODE,
    WMODE,
    ZMODE
};

enum
{
    E_OLINK = 1,
    E_ONEXT = 2,
    E_GETEMPTY = 3,
    E_PUTOBJ = 4,
    E_PUTFULL = 5,
    E_BACKOBJ = 6,
    E_BACKFULL = 7,
    E_SETCLOCK = 8,
    E_CLOCKIDLE = 9,
    E_RESTERM = 10,
    E_RESRUN = 11,
    E_NEGTIME = 12,
    E_RESOBJ = 13,
    E_HISTO = 14,
    E_STACK = 15,
    E_STORE = 16,
    E_TASKMODE = 17,
    E_TASKDEL = 18,
    E_TASKPRE = 19,
    E_TIMERDEL = 20,
    E_SCHTIME = 21,
    E_SCHOBJ = 22,
    E_QDEL = 23,
    E_RESULT = 24,
    E_WAIT = 25,
    E_FUNCS = 26,
    E_FRAMES = 27,
    E_REGMASK = 28,
    E_FUDGE_SIZE = 29,
    E_NO_HNDLR = 30,
    E_BADSIG = 31,
    E_LOSTHNDLR = 32,
    E_TASKNAMEOVERRUN = 33
};

extern int _hwm;

Types

enum Print Function Arguments

p->print(VERBOSE|CHAIN);

enum qmodetype

enum Exception Codes

Descriptions of the E_ codes are given in the Exception Handling sections of the appropriate classes.

Is a pointer to a function returning int, which takes arguments of the types int and object *.

Is a pointer to a function returning void, which takes no arguments.

Other Data

Can be set to a nonzero value before creation of the first task to keep track of the maximum stack size ("high water mark"). The maximum stack size can be printed by the task::print() function.

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class erand: public randint
{
public:
    int mean;

        erand(int m);

    int draw();
};

Member Data

Is the mean of the generated random numbers.

Constructor

Constructs an erand object with m as the mean for the generated random numbers.

Member Function

Returns the next random integer generated by the object.

See Also

randint class

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class histogram
{
public:
    int   l;
    int   r;
    int   binsize;
    int   nbin;
    int   *h;
    long  sum;
    long  sqsum;

          histogram(int n_bins = 16, int left = 0, int right = 16);
          ~histogram();

    void  add(int sample);
    void  print();
};

Description

Objects of this class generate histograms. Each such object has nbin bins, spanning a range from l to r.

Exception Handling

Member Data

Is the size of the range covered by an individual bin.

Is a pointer to a vector of nbin integers. Each element of the vector is the number of samples placed into that bin by the add() function.

Is the lower (left) end of the range of samples.

Is the total number of bins.

Is the higher (right) end of the range of samples.

Is the sum of the squares of the integers added to a bin by the add() function.

Is the sum of the integers added to a bin by the add() function.

Constructors and Destructors

Deletes a histogram object.

Member Functions

Adds one to the bin specified by sample. If sample is outside the range of l to r, the range expands by either decreasing l or increasing r; however, nbin remains constant. Thus, the range covered by one bin doubles if the total histogram doubles.

Prints on cout the number of entries for each nonempty bin.

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class Interrupt_handler: public object
{
public:
                     Interrupt_handler(int);
                     ~Interrupt_handler();

    virtual void     print(int verbosity, int internal_use = 0);
    virtual int      pending();
    virtual objtype  o_type();

private:
    virtual void interrupt();
};

Description

Interrupt handlers allow tasks to wait for signals. You can use classes derived from the Interrupt_handler class to overload the interrupt() function. When the signal is raised, the task package immediately calls the interrupt() function. The task package then schedules its own internal interrupt alerter task 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 (see the sched class) 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.

If an interrupt() function is not needed, you can use the Interrupt_handler class without deriving another class from it.

Exception Handling

Constructors and Destructors

Constructs a new Interrupt_handler object that waits for a specified signal.

Deletes an Interrupt_handler object.

Member Functions

Does nothing but lets classes derived from the Interrupt_handler class overload this function to specify actions. Because it is private, you cannot call it directly.

Returns object::INTHANDLER.

Returns 0 on the first call after the signal is raised; otherwise, it returns a nonzero value.

Prints information about the interrupt handler. The verbosity argument specifies the information to be printed. Do not supply a value for the internal_use parameter.

System Environment

The thread system exception handling uses OpenVMS conditions and does not interact directly with signals.

Example

extern "C" {
#include <stdlib.h>
}
#include <signal.h>
#include <task.hxx>
#include <iostream.hxx>

class floating_exception: public Interrupt_handler
{
    virtual void interrupt();
public:
    floating_exception(): Interrupt_handler(SIGFPE) {};
};

void floating_exception::interrupt()
{
    cout << "In floating_exception::interrupt –
    Floating exception caught!\n";
    cout.flush();
}

int main()
{
    floating_exception sigfpe_handler;
    raise(SIGFPE);
    return EXIT_SUCCESS;
}

In floating_exception::interrupt – Floating exception caught!

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class object
{
public:
    enum objtype
    {
        OBJECT,         // class object
        TIMER,          // class timer
        TASK,           // class task
        QHEAD,          // class qhead
        QTAIL,          // class qtail
        INTHANDLER      // class Interrupt_handler
    };

    object  *o_next;

    static  PFIO error_fct;

            object();
            ~object();

    void    alert();
    void    forget(task *p_task_to_forget);
    void    remember(task *p_task);
    int     task_error(int error_code);

    virtual objtype o_type();
    virtual int pending();
    virtual void print(int verbosity, int internal_use = 0);

    static  int task_error(int error_code, object *object_with_problem);
    static  task *this_task();
};

Description

This class is a base class for many other classes within the task package. You also can 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 ready. 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.

Exception Handling

Member Data

Points to a function to be called by the task_error function. For more information, see the task_error function.

Points to the next object in the queue or run chain.

Constructors and Destructors

Constructs an object object.

Deletes an object object.

Member Functions

Changes the state of all task objects remembered by the object from IDLE to RUNNING, puts the task objects on the scheduler's run chain, and removes the task objects from the remembering object's remember chain. You must call the object::alert function for the object when the state of an object changes from pending to ready.

Removes, from the remembering object object's remember chain, all occurrences of the task, denoted by the p_task_to_forget argument.

Returns object::OBJECT.

Always returns a nonzero value.

In classes derived from object, pending() returns the ready status of an object: 0 if an object object is ready and a nonzero value if the object object is pending. Classes derived from the object class must define pending() if waiting is instituted. By default, object::pending returns a nonzero value.

Prints an object on cout. The verbosity argument specifies the information to be printed. Do not supply a value for the internal_use parameter.

Puts a task for a pending object on the remember chain and suspends the task, when that task attempts an operation on the pending object. Remembered task objects are alerted when an object of the object class becomes ready.

Is obsolete. Calling p->task_error(e) is equivalent to calling object::task_error(e,p).

Called when a run-time error occurs. The error_code argument represents the error number and the object_with_problem argument represents a pointer to the object that called task_error(). The object::task_error() function examines the variable error_fct and calls this function if it is not NULL. If the function returns 0, task_error() returns to its caller, which may retry the operation. (An infinite loop may result if no appropriate recovery is made.) If the function returns a nonzero value, task_error() calls exit(error_code). Otherwise, task_error() gives the error number as an argument to print_error(), which prints an error message on cout and task_error() calls exit(error_code).

The object_with_problem argument may be NULL if no particular object can be associated with the error.

Returns a pointer to the task object currently running.

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class qhead: public object
{
public:
              qhead(qmodetype modetype = WMODE, int size = 10000);
              ~qhead();

    qhead     *cut();
    object    *get();
    int       putback(object *new_queue_element);
    int       rdcount();
    int       rdmax();
    qmodetype rdmode();
    void      setmode(qmodetype modetype);
    void      setmax(int size);
    void      splice(qtail *delete_tail);
    qtail     *tail();

    int       pending();
    void      print(int verbosity, int internal_use = 0);
    objtype   o_type();
};

Description

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 attached qtail object. You create a queue by creating either a qhead or a qtail object. 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 for 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.

Exception Handling

Constructors and Destructors

Constructs a qhead object. The modetype argument determines what happens when an object of the qhead class is pending. The choices are WMODE (wait mode), EMODE (error mode), or ZMODE (0 mode); the default is WMODE (see the get() function for more information). The size argument sets the maximum length of the queue attached to a qhead object; the default is 10,000.

The maximum size of the queue does not affect the amount of memory occupied by the queue when the queue is empty.

Deletes a qhead object.

Member Functions

Splits a queue into two queues. One queue has a new qhead object, which the return value points to, and the original qtail object; it contains the objects from the original queue. The other queue has the original qhead object and a new qtail object; this queue is empty. You can use this function to insert a filter into an existing queue without changing the queue's appearance to functions that access the ends of the queue, and without halting the flow through the queue of objects.

Returns a pointer to the object at the head of the queue when the queue is not empty. The object is removed from the queue. If the queue is empty, behavior depends on the mode of the qhead object. In WMODE, a task that executes qhead::get() on an empty queue suspends until that queue is not empty. In EMODE, executing qhead::get() on an empty queue causes a run-time error. In WMODE, executing qhead::get() on an empty queue returns the NULL pointer instead of a pointer to an object.

Returns object::QHEAD.

Specifies that get operations on a queue must wait until an object is put in the queue. It returns a nonzero value if the queue attached to a qhead object is empty; otherwise, it returns 0.

Prints a qhead object on cout. The verbosity argument specifies the information to be printed. Do not supply a value for the internal_use parameter.

Inserts at the head of the queue the object that the new_queue_element argument points to, and returns a value of 1 on success. This lets the qhead object operate as a stack (hence, the name putback). Space must be available in the queue for it to succeed. Calling qhead::putback() for a full queue causes a run-time error in both EMODE and WMODE and returns NULL in ZMODE.

Returns the current number of objects in the queue attached to a qhead object.

Returns the maximum length of the queue.

Returns the current mode of a qhead object, which can be EMODE, WMODE, or ZMODE.

Sets the mode of a qhead object to modetype, which can be EMODE, WMODE, or ZMODE.

Sets size as the maximum length of the queue attached to a qhead object. You can set size to a number less than the current number of objects of the object class, but that means you cannot put any more objects of the object class on the queue until the length of the queue has been reduced below the limit you set.

Forms a single queue by appending a queue attached to a qhead object onto the queue referenced in the argument. Typically, this reverses the action of a previous qhead::cut() function. The extra qhead and qtail objects are deleted. Waiting tasks resume execution if merging the two creates a nonempty queue (if the task was trying to get) or an empty queue (if the task was trying to put).

Creates a qtail object for the queue attached to a qhead object (if none exists) and returns a pointer to the new qtail object.

Header

#include <task.hxx>

Alternative Header

#include <task.h>

Declaration

class qtail: public object
{
    friend class qhead;

public:
              qtail(qmodetype modetype = WMODE, int size = 10000);
              ~qtail();

    qtail     *cut();
    qhead     *head();
    int       put(object *new_queue_element);
    int       rdspace();
    int       rdmax();
    qmodetype rdmode();
    void      setmode(qmodetype modetype);
    void      setmax(int size);
    void      splice(qhead *delete_head);

    int       pending();
    void      print(int verbosity, int internal_use = 0);
    objtype   o_type();
};

Description

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 qtail object. You create a queue by creating either a qhead or a qtail object. 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 for 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.

Exception Handling

Constructors and Destructors

Constructs a qtail object. The modetype argument specifies the mode (set by the constructor) that controls what happens when an object of the qtail class is pending. The choices are WMODE (wait mode), EMODE (error mode), or ZMODE (0 mode); WMODE is the default. (See the put() function for more information.) The size argument specifies the maximum length of the queue attached to a qhead object; the default is 10,000.