Chapter 13. Library Reference

This chapter is a reference for the entire runtime library. As you can see, it is a big one. To help you find what you need, each header in this chapter is organized in alphabetical order. If you are not sure which header declares a particular type, macro, or other identifier, check the index. Once you find the right page, you can quickly see which header you must #include to define the identifier you need.

The subsections in each header's section describe the functions, macros, classes, and other entities declared and defined in the header. The name of the subsection tells you what kind of entity is described in the subsection—e.g., "terminate function," "basic_string class template," and so on. Cross references in each "See Also" heading list intrasection references first, followed by references to other headers (in this chapter) and references to keywords (in Chapter 12).

The subsection for each class or class template contains descriptions of all important members. A few obvious or do-nothing members are omitted (such as most destructors) for the sake of brevity.

The entire standard library resides in the std namespace, except that macros reside outside any namespace. Be sure to check the subsection name closely so you know whether an identifier is a macro or something else. To avoid cluttering the reference material, the std:: prefix is omitted from the descriptions. Examples, however, are complete and show how each namespace prefix is properly used.

Some C++ headers are taken from the C standard. For example, the C standard <stdio.h> has its C++ equivalent in <cstdio>. The C++ version declares all the C names (other than macros) in the std:: namespace but reserves the same names in the global namespace, so you must not declare your own names that conflict with those of the C headers.

Each C header can be used with its C name, in which case the declarations in the header are explicitly introduced into the global namespace. For example, <cstdio> declares std::printf (and many other names), and <stdio.h> does the same, but adds "using std::printf" to bring the name printf into the global namespace. This use of the C headers is deprecated.

The syntax description for most macros shows the macro name as an object or function declaration. These descriptions tell you the macro's type or expected arguments. They do not reflect the macro's implementation. For macros that expand to values, read the textual description to learn whether the value is a compile-time constant.

For an overview of the standard library, see Chapter 8. Chapter 9 presents the I/O portions of the library, and Chapter 10 discusses containers, iterators, and algorithms.

C++ permits two kinds of library implementations: freestanding and hosted. The traditional desktop computer is a hosted environment. A hosted implementation must implement the entire standard.

Library Reference

A freestanding implementation is free to implement a subset of the standard library. The subset must provide at least the following headers, and can optionally provide more:

<cstdarg>
<cstddef>
<cstdlib>
<exception>
<limits>
<new>
<typeinfo>

The <algorithm> header declares the generic algorithm function templates for operating on iterators and other objects. Refer to Chapter 10 for more information about using and writing generic algorithms and about the iterators they use. See Chapter 8 for a discussion of iterator traits.

This section uses a number of abbreviations and conventions. First, each algorithm is described using plain English. Then, a more mathematical description of the algorithm, which tends to be harder to read, is given in a "Technical Notes" section.

The names of the template parameters tell you which category of iterator is expected. The iterator category is the minimal functionality needed, so you can, for example, use a random access iterator where at least a forward iterator is needed. (See Chapter 10 for more information on iterators and iterator categories.) To keep the syntax summaries short and readable, the iterator categories are abbreviated, as shown in Table 13-1.

Other template parameter names are chosen to be self-explanatory. For example, any name that ends in Predicate is a function that returns a Boolean result (which can be type bool or any other type that is convertible to bool) or a Boolean functional object (an object that has a function call operator that returns a Boolean result).

A number of algorithms require sorted ranges or otherwise use a comparison function to test the less-than relationship. The library overloads each algorithm: the first function uses operator<, and the second accepts a function pointer or function object to perform the comparison. The comparison function takes two arguments and returns a Boolean result. In the "Technical Notes" sections, the < relationship signifies operator< or the caller-supplied function, depending on the version of the algorithm you are using. If you overload operator< or provide your own comparison function, make sure it correctly implements a less-than relationship. In particular, a < a must be false for any a.

In this section, the following conventions are used:

In each "Technical Notes" section, conventional mathematical notation is used with some aspects of C++ notation, such as *, which dereferences an iterator. Also, a single equal sign (=) means assignment, and a double equal sign (==) means comparison for equality. The following conventions are used for names:

i, j, k

Denote iterators, and *i, *j, and *k denote the values that the iterators point to.

n, m

Denote integers.

a, b, c

Denote values, which are usually of types that can be assigned to or from a dereferenced iterator (e.g., *i = a).