C++ Library Overview

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

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 Standard C++ library consists of 51 required headers. This implementation also includes three additional headers, <hash_map>, <hash_set>, and <slist>, not required by the C++ Standard, for a total of 54 headers. These 54 C++ library headers (along with the additional 18 Standard C headers) constitute a hosted implementation of the C++ library: <algorithm>, <bitset>, <cassert>, <cctype>, <cerrno>, <cfloat>, <ciso646>, <climits>, <clocale>, <cmath>, <complex>, <csetjmp>, <csignal>, <cstdarg>, <cstddef>, <cstdio>, <cstdlib>, <cstring>, <ctime>, <cwchar>, <cwctype>, <deque>, <exception>, <fstream>, <functional>, <hash_map>, <hash_set>, <iomanip>, <ios>, <iosfwd>, <iostream>, <istream>, <iterator>, <limits>, <list>, <locale>, <map>, <memory>, <new>, <numeric>, <ostream>, <queue>, <set>, <slist>, <sstream>, <stack>, <stdexcept>, <streambuf>, <string>, <strstream>, <typeinfo>, <utility>, <valarray>, and <vector>.

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), <exception>, <limits>, <new>, <typeinfo>, and <cstdarg>.

The C++ library headers have two broader subdivisions, iostreams headers and STL 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.

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. Note, however, that macro names are not subject to namespace qualification, so you always write __STD_COMPLEX without a namespace qualifier.

In some translation environments, including a C++ library header may hoist external names declared in the std namespace into the global namespace as well, with individual using declarations for each of the names. Otherwise, the header does not introduce any library names into the current namespace.

The C++ Standard requires that the C Standard headers declare all external names in namespace std, then hoist them into the global namespace with individual using declarations for each of the names. But in some translation environments the C Standard headers include no namespace declarations, declaring all names directly in the global namespace. Thus, the most portable way to deal with namespaces is to follow two rules:

To assuredly declare in namespace std an external name that is traditionally declared in <stdlib.h>, for example, include the header <cstdlib>. Know that the name might also be declared in the global namespace.
To assuredly declare in the global namespace an external name declared in <stdlib.h>, include the header <stdlib.h> directly. Know that the name might also be declared in namespace std.

Thus, if you want to call std::abort() to cause abnormal termination, you should include <cstdlib>. And if you want to call abort(), you should include <stdlib.h>.

Alternatively, you can write the declaration:

using namespace std;

which assuredly hoists all library names into the current namespace. If you write this declaration immediately after all include directives, you hoist the names into the global namespace. You can subsequently ignore namespace considerations in the remainder of the translation unit. You also avoid most dialect differences across different translation environments.

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.

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

Names of functions in the Standard C library may have either extern "C++" or extern "C" linkage. Include the appropriate Standard C header rather than declare a library entity inline.
A member function name in a library class may have additional function signatures over those listed in this document. You can be sure that a function call described here behaves as expected, but you cannot reliably take the address of a library member function. (The type may not be what you expect.)
A library class may have undocumented (non-virtual) base classes. A class documented as derived from another class may, in fact, be derived from that class through other undocumented classes.
A type defined as a synonym for some integer type may be the same as one of several different integer types.
A bitmask type can be implemented as either an integer type or an enumeration. In either case, you can perform bitwise operations (such as AND and OR) on values of the same bitmask type. The elements A and B of a bitmask type are nonzero values such that A & B is zero.
A library function that has no exception specification can throw an arbitrary exception, unless its definition clearly restricts such a possibility.

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

The Standard C library uses no masking macros. Only specific function signatures are reserved, not the names of the functions themselves.
A library function name outside a class will not have additional, undocumented, function signatures. You can reliably take its address.
Base classes and member functions described as virtual are assuredly virtual, while those described as non-virtual are assuredly non-virtual.
Two types defined by the C++ library are always different unless this document explicitly suggests otherwise.
Functions supplied by the library, including the default versions of replaceable functions, can throw at most those exceptions listed in any exception specification. No destructors supplied by the library throw exceptions. Functions in the Standard C library may propagate an exception, as when qsort calls a comparison function that throws an exception, but they do not otherwise throw exceptions.

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 basic_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 basic_ostream. Format control common to both extractors and insertors is managed by the class basic_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 basic_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:

cin -- for standard input
cout -- for standard output
cerr -- for unbuffered standard error output
clog -- for buffered standard error output

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. An exception thrown from such a registered function calls terminate().

See also the Table of Contents and the Index.