Overview

This chapter gives an overview of the C++ Class Library, and includes the following sections:

Header Files

The header files described below are supplied with the C++ class library. When an object from the library is to be manipulated with a function, the related header file should be included in the source file. The related header file is shown in the synopsis for the function. The header files provide the proper declarations for the functions and for the number and types of arguments used with them. Constant values and enumerations used in conjunction with the functions are also declared. The files can be included in any order.

The following files are provided with the software. The header files are all located in the /usr/include directory.

complex.h
This header file defines the Complex class, which is used to perform complex arithmetic. The Complex member functions, as well as related functions that manipulate Complex objects are declared. Inline member functions for the Complex class are defined.
except.h
This header file provides declarations to be used with the exception handling mechanism.
fstream.h
This header file defines the filebuf, fstreambase, ifstream, ofstream and fstream classes. These classes are used to perform C++ file input and output operations. The various class members are declared, and inline member functions for the classes are defined.
generic.h
This header file is part of the macro support required prior to the implementation of templates in the C++ language. It's retained for backwards compatibility.
iomanip.h
This header file contains the macro definitions required to implement the parameterized manipulators in the absence of templates. It's retained for backwards compatibility.
iostream.h
This header file defines the ios, istream, ostream and iostream classes. These classes form the basis of the C++ formatted input and output support. The various class members are declared, and inline member functions for the classes are defined. The cin, cout, cerr, and clog predefined objects are declared along with the non-parameterized manipulators.
new.h
This header file provides declarations to be used with the intrinsic operator new() and operator delete() memory management functions.
stdiobuf.h
This header file defines the stdiobuf class, which provides the support for the C++ input and output operations to standard input, standard output, and standard error streams. The various class members are declared, and inline member functions for the classes are defined.
streambu.h
This header file defines the streambuf class, which provides the support for buffering of input and output operations. The various class members are declared, and inline member functions for the classes are defined. This header file is automatically included by the iostream.h header file.
string.hpp
This header file defines the String class. The String class is used to manipulate character strings. The String member functions are declared. The related functions that manipulate String objects are declared. Inline member functions for the String class are defined.
Note: The .hpp extension is used to avoid colliding with the ANSI C string.h header file.
strstrea.h
This header files defines the strstreambuf, strstreambase, istrstream, ostrstream and strstream classes. These classes are used to perform C++ in-memory formatting. The various class members are declared, and inline member functions for the classes are defined.
wcdefs.h
This header file contains definitions used by the container libraries. If a container class needs any of these definitions, the file is automatically included.
wclbase.h
This header file defines the base classes that are used by the list containers.
wclcom.h
This header file defines the classes that are common to the list containers.
wclibase.h
This header file defines the base classes that are used by the list iterators.
wclist.h
This header file defines the list container classes. The available list container classes are singly and doubly linked versions of intrusive, value and pointer lists.
wclistit.h
This header file defines the iterator classes that correspond to the list containers.
wcqueue.h
This header file defines the queue class. Entries in a queue class are accessed first in, first out.
wcstack.h
This header file defines the stack class. Entries in a stack class are accessed last in, first out.

Common Types

The set of classes that make up the C++ class library use several common typedefs and macros. They are declared in iostream.h and fstream.h. 

typedef long streampos;
typedef long streamoff;
typedef int filedesc;
#define __NOT_EOF 0
#define EOF -1

The streampos type represents an absolute position within the file. For Watcom C++, the file position can be represented by an integral type. For some file systems, or at a lower level within the file system, the stream position might be represented by an aggregate (structure) containing information such as cylinder, track, sector and offset.

The streamoff type represents a relative position within the file. The offset can always be represented as a signed integer quantity since it's a number of characters before or after an absolute position within the file.

The filedesc type represents the type of a C library file handle. It's used in places where the I/O stream library takes a C library file handle as an argument.

The __NOT_EOF macro is defined for cases where a function needs to return something other than EOF to indicate success.

The EOF macro is defined to be identical to the value provided by the stdio.h header file.

Predefined Objects

Most programs interact in some manner with the keyboard and screen. The C programming language provides three values, stdin, stdout and stderr, that are used for communicating with these standard devices, and are opened before the user program starts execution at main(). These three values are FILE pointers, and can be used in virtually any file operation supported by the C library.

In a similar manner, C++ provides seven objects for communicating with the same standard devices. C++ provides the three C FILE pointers stdin, stdout and stderr, but they can't be used with the extractors and inserters provided as part of the C++ library. C++ provides four new objects, called cin, cout, cerr and clog, which correspond to stdin, stdout, stderr, and buffered stderr, respectively.

cin
cin is an istream object that is connected to standard input (usually the keyboard) prior to program execution. Values extracted using the istream operator >>() class extractor operators are read from standard input, and interpreted according to the type of the object being extracted.

Extractions from standard input via cin skip whitespace characters by default because the ios::skipws bit is on. The default behavior can be changed with the ios::setf() public member function, or with the setiosflags() manipulator.

cout
cout is an ostream object that is connected to standard output (usually the screen) prior to program execution. Values inserted using the ostream operator <<() class inserter operators are converted to characters, and written to standard output according to the type of the object being inserted.

Insertions to standard output via cout are buffered by default because the ios::unitbuf bit is not on. The default behavior can be changed with the ios::setf() public member function, or with the setiosflags() manipulator.

cerr
cerr is an ostream object that is connected to standard error (the screen) prior to program execution. Values inserted using the ostream operator <<() class inserter operators are converted to characters, and written to standard error according to the type of the object being inserted.

Insertions to standard error via cerr are not buffered by default because the ios::unitbuf bit is on. The default behavior can be changed with the ios::setf() public member function, or with the setiosflags() manipulator.

clog
clog is an ostream object that is connected to standard error (the screen) prior to program execution. Values inserted using the ostream operator <<() class inserter operators are converted to characters, and written to standard error according to the type of the object being inserted.

Insertions to standard error via clog are buffered by default because the ios::unitbuf bit is not on. The default behavior can be changed with the ios::setf() public member function, or with the setiosflags() manipulator.

istream Input

istream input can be either formatted or unformatted.

Formatted Input: Extractors

The istream operator >>() function is used to read formatted values from a stream. It's called an extractor. Characters are read and interpreted according to the type of object being extracted.

All operator >>() functions perform the same basic sequence of operations:

  • First, the input prefix function ipfx() is called with a parameter of zero, causing leading whitespace characters to be discarded if ios::skipws is set in ios::fmtflags.
  • If the input prefix function fails and returns zero, the operator >>() function also fails, and returns immediately.
  • If the input prefix function succeeds, characters are read from the stream, and are interpreted in terms of the type of object being extracted and ios::fmtflags.
  • Finally, the input suffix function isfx() is called.

The operator >>() functions return a reference to the specified stream, so that multiple extractions can be done in one statement.

Errors are indicated via ios::iostate. The ios::failbit bit is set if the characters read from the stream could not be interpreted for the required type. The ios::badbit bit is set if the extraction of characters from the stream failed in such a way as to make subsequent extractions impossible. The ios::eofbit bit is set if the stream was located at the end when the extraction was attempted.

Unformatted Input

The unformatted input functions are used to read characters from the stream, without interpretation.

Like the extractors, the unformatted input functions follow a pattern:

  • First, they call ipfx(), the input prefix function, with a parameter of one, causing no leading whitespace characters to be discarded.
  • If the input prefix function fails and returns zero, the unformatted input function also fails and returns immediately.
  • If the input prefix function succeeds, characters are read from the stream without interpretation.
  • Finally, isfx(), the input suffix function, is called.

Errors are indicated via the ios::iostate bits. The ios::failbit bit is set if the extraction of characters from the stream failed. The ios::eofbit bit is set if the stream was located at the end of input when the operation was attempted.

ostream Output

Output can also be formatted or unformatted.

Formatted Output: Inserters

The ostream operator <<() function is used to write formatted values to a stream. It's called an inserter. Values are formatted and written according to the type of object being inserted and ios::fmtflags.

All operator << functions perform the same basic sequence of operations:

  • First, the output prefix function opfx() is called.
  • If it fails and returns zero, the operator << function also fails and returns immediately.
  • If the output prefix function succeeds, the object is formatted according to its type and ios::fmtflags.
  • The formatted sequence of characters is then written to the specified stream.
  • Finally, the output suffix function osfx() is called.

The operator << functions return a reference to the specified stream, so that multiple insertions can be done in one statement.

Errors are indicated via ios::iostate. The ios::failbit bit is set if the operator << function fails while writing the characters to the stream.

Unformatted Output

The unformatted output functions are used to write characters to the stream without conversion.

Like the inserters, the unformatted output functions follow a pattern:

  • First, they call the output prefix function opfx(), and fail if it fails.
  • Then the characters are written without conversion.
  • Finally, the output suffix function osfx() is called.

Errors are indicated via ios::iostate. The ios::failbit bit is set if the function fails while writing the characters to the stream.

What you'll find in a Class Description

Each of the classes and functions in the C++ Class Library is described in this reference. Each description consists of a number of subsections:

Declared:
This optional subsection specifies which header file contains the declaration for a class. It's only found in sections describing class declarations.
Derived From:
This optional subsection shows the inheritance for a class. It's only found in sections describing class declarations.
Derived By:
This optional subsection shows which classes inherit from this class. It's only found in sections describing class declarations.
Synopsis:
This subsection gives the name of the header file that contains the declaration of the function. This header file must be included in order to reference the function.

For class member functions, the protection associated with the function is indicated via the presence of one of the private, protected or public keywords.

The full function prototype is specified. Virtual class member functions are indicated via the presence of the virtual keyword in the function prototype.

Semantics:
This subsection is a description of the function.
Derived Implementation Protocol:
This optional subsection is present for virtual member functions. It describes how derived implementations of the virtual member function should behave.
Default Implementation:
This optional subsection is present for virtual member functions. It describes how the default implementation provided with the base class definition behaves.
Results:
This optional subsection describes the function's return value, if any, and the impact of a member function on its object's state.
See Also:
This optional subsection provides a list of related functions or classes.