17 Library introduction [library]

17.6 Library-wide requirements [requirements]

17.6.1 Library contents and organization [organization] Headers [headers]

Each element of the C++ standard library is declared or defined (as appropriate) in a header.175

The C++ standard library provides 53 C++ library headers, as shown in Table [tab:cpp.library.headers].

Table 14 — C++ library headers
<algorithm> <fstream> <list> <regex> <tuple>
<array> <functional> <locale> <scoped_allocator> <type_traits>
<atomic> <future> <map> <set> <typeindex>
<bitset> <initializer_list> <memory> <sstream> <typeinfo>
<chrono> <iomanip> <mutex> <stack> <unordered_map>
<codecvt> <ios> <new> <stdexcept> <unordered_set>
<complex> <iosfwd> <numeric> <streambuf> <utility>
<condition_variable> <iostream> <ostream> <string> <valarray>
<deque> <istream> <queue> <strstream> <vector>
<exception> <iterator> <random> <system_error>
<forward_list> <limits> <ratio> <thread>

The facilities of the C standard Library are provided in 26 additional headers, as shown in Table [tab:cpp.c.headers].

Table 15 — C++ headers for C library facilities
<cassert> <cinttypes> <csignal> <cstdio> <cwchar>
<ccomplex> <ciso646> <cstdalign> <cstdlib> <cwctype>
<cctype> <climits> <cstdarg> <cstring>
<cerrno> <clocale> <cstdbool> <ctgmath>
<cfenv> <cmath> <cstddef> <ctime>
<cfloat> <csetjmp> <cstdint> <cuchar>

Except as noted in Clauses [language.support] through [thread] and Annex [depr], the contents of each header cname shall be the same as that of the corresponding header name.h, as specified in the C standard library ([intro.refs]) or the C Unicode TR, as appropriate, as if by inclusion. In the C++ standard library, however, the declarations (except for names which are defined as macros in C) are within namespace scope ([basic.scope.namespace]) of the namespace std. It is unspecified whether these names are first declared within the global namespace scope and are then injected into namespace std by explicit using-declarations ([namespace.udecl]).

Names which are defined as macros in C shall be defined as macros in the C++ standard library, even if C grants license for implementation as functions. [ Note: The names defined as macros in C include the following: assert, offsetof, setjmp, va_arg, va_end, and va_start.  — end note ]

Names that are defined as functions in C shall be defined as functions in the C++ standard library.176

Identifiers that are keywords or operators in C++ shall not be defined as macros in C++ standard library headers.177

[depr.c.headers], C standard library headers, describes the effects of using the name.h (C header) form in a C++ program.178

A header is not necessarily a source file, nor are the sequences delimited by < and > in header names necessarily valid source file names ([cpp.include]).

This disallows the practice, allowed in C, of providing a masking macro in addition to the function prototype. The only way to achieve equivalent inline behavior in C++ is to provide a definition as an extern inline function.

In particular, including the standard header <iso646.h> or <ciso646> has no effect.

The ".h" headers dump all their names into the global namespace, whereas the newer forms keep their names in namespace std. Therefore, the newer forms are the preferred forms for all uses except for C++ programs which are intended to be strictly compatible with C.