C++ Library Overview


Using C++ Library Headers
C++ Library Conventions
Iostreams Conventions
Program Startup and Termination
Exceptions

All C++ library entities are declared or defined in one or more standard headers. To make use of a library entity in a program, write an include directive that names the relevant standard header. The full set of 28 C++ library headers (along with the additional 15 Standard C headers) constitutes a hosted implementation of Embedded C++: <cassert>, <cctype>, <cerrno>, <cfloat>, <climits>, <clocale>, <cmath>, <complex>, <csetjmp>, <csignal>, <cstdarg>, <cstddef>, <cstdio>, <cstdlib>, <cstring>, <ctime>, <fstream>, <iomanip>, <ios>, <iosfwd>, <iostream>, <istream>, <new>, <ostream>, <sstream>, <streambuf>, <string>, and <strstream>

A freestanding implementation of the C++ library provides only a subset of these headers: <cstddef>, <cstdlib> (declaring at least the functions abort, atexit, and exit), <new>, and <cstdarg>.

The C++ library headers also have a broader subdivision -- iostreams headers.

Using C++ Library Headers

You include the contents of a standard header by naming it in an include directive, as in:

#include <iostream>  /* include I/O facilities */

You can include the standard headers in any order, a standard header more than once, or two or more standard headers that define the same macro or the same type. Do not include a standard header within a declaration. Do not define macros that have the same names as keywords before you include a standard header.

A C++ library header includes any other C++ library headers it needs to define needed types. (Always include explicitly any C++ library headers needed in a translation unit, however, lest you guess wrong about its actual dependencies.) A Standard C header never includes another standard header. A standard header declares or defines only the entities described for it in this document.

Every function in the library is declared in a standard header. Unlike in Standard C, the standard header never provides a masking macro, with the same name as the function, that masks the function declaration and achieves the same effect.

If an implementation supports namespaces, all names other than operator delete and operator new in the C++ library headers are defined in the std namespace, or in a namespace nested within the std namespace. You refer to the name cin, for example, as std::cin. Alternatively, you can write the declaration:

using namespace std;

which promotes all library names into the current namespace. If you write this declaration immediately after all include directives, you can otherwise ignore namespace considerations in the remainder of the translation unit. Note that macro names are not subject to the rules for nesting namespaces.

All names in the C standard headers, such as <stdio.h> are defined in the global namespace. Despite what the draft C++ Standard says, however, in common practice the C headers do not always define the same names in namespace std as well. Use the corresponding C++ headers -- <cctype> instead of <ctype.h>, for example -- to be certain that names from the Standard C library also appear in namespace std.

Unless specifically indicated otherwise, you may not define names in the std namespace, or in a namespace nested within the std namespace.

C++ Library Conventions

The C++ library obeys much the same conventions as the Standard C library, plus a few more outlined here.

Except for macro names, which obey no scoping rules, all names in the C++ library are declared in the std namespace. Including a C++ library header does not introduce any library names into the current namespace. You must, for example, refer to the standard input stream cin as std::cin, even after including the header <iostream> that declares it. Alternatively, you can incorporate all members of the std namespace into the current namespace by writing:

using namespace std;

immediately after all include directives that name the standard headers. Note that the Standard C headers behave mostly as if they include no namespace declarations. If you include, for example, <cstdlib>, you call std::abort() to cause abnormal termination, but if you include <stdlib.h>, you call abort().

An implementation has certain latitude in how it declares types and functions in the C++ library:

On the other hand, there are some restrictions you can count on:

Iostreams Conventions

The iostreams headers support conversions between text and encoded forms, and input and output to external files: <fstream>, <iomanip>, <ios>, <iosfwd>, <iostream>, <istream>, <ostream>, <sstream>, <streambuf>, and <strstream>.

The simplest use of iostreams requires only that you include the header <iostream>. You can then extract values from cin, to read the standard input. The rules for doing so are outlined in the description of the class istream. You can also insert values to cout, to write the standard output. The rules for doing so are outlined in the description of the class ostream. Format control common to both extractors and insertors is managed by the class ios. Manipulating this format information in the guise of extracting and inserting objects is the province of several manipulators.

You can perform the same iostreams operations on files that you open by name, using the classes declared in <fstream>. To convert between iostreams and objects of class string, use the classes declared in <sstream>. And to do the same with C strings, use the classes declared in <strstream>.

The remaining headers provide support services, typically of direct interest to only the most advanced users of the iostreams classes.

C++ Program Startup and Termination

A C++ program performs the same operations as does a C program program startup and at program termination, plus a few more outlined here.

Before the target environment calls the function main, and after it stores any constant initial values you specify in all objects that have static duration, the program executes any remaining constructors for such static objects. The order of execution is not specified between translation units, but you can nevertheless assume that some iostreams objects are properly initialized for use by these static constructors. These control text streams:

You can also use these objects within the destructors called for static objects, during program termination.

As with C, returning from main or calling exit calls all functions registered with atexit in reverse order of registry.

Exceptions

In this implementation, exception handling can be either enabled or disabled. This document describes all behavior as if exception handling is enabled. If exception handling is disabled, however:

Here, void _Raise() is a member function of class exception, the base class for all exceptions thrown by the library. It performs the following operations, in order:

  1. If a raise handler has been registered by an earlier call to the static member function exception:: _Set_raise_handler(void (*)(const exception&), then _Raise calls the raise handler.
  2. _Raise then calls the protected virtual member function void _Doraise(), which typically calls _Throw(*this) in any class derived from exception. (This ensures that the most derived version of the virtual public member function what gets called by _Throw, as outlined below.)
  3. _Raise then calls _Throw(*this).

The replaceable global function void _Throw(const exception& ex) never returns to its caller. If the pointer returned by ex.what() is not a null pointer, the function writes to the standard error output stream a diagnostic message that includes the null-terminated string designated by the pointer. In any event, the function then calls abort.

The net effect of all this machinery is to supply several levels of control, in lieu of the normal exception-handling machinery:


See also the Table of Contents and the Index.

Copyright © 1992-1996 by P.J. Plauger. All rights reserved.