16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.2 Library contents and organization [organization]

16.4.2.1 General [organization.general]

1
#
[contents] describes the entities and macros defined in the C++ standard library.
[headers] lists the standard library headers and some constraints on those headers.
[compliance] lists requirements for a freestanding implementation of the C++ standard library.

16.4.2.2 Library contents [contents]

1
#
The C++ standard library provides definitions for the entities and macros described in the synopses of the C++ standard library headers ([headers]), unless otherwise specified.
2
#
All library entities except operator new and operator delete are defined within the namespace std or namespaces nested within namespace std.150
It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace.151
3
#
Whenever an unqualified name other than swap, make_error_code, make_error_condition, or submdspan_mapping is used in the specification of a declaration D in [support] through [thread] or [depr], its meaning is established as-if by performing unqualified name lookup ([basic.lookup.unqual]) in the context of D.
[Note 1: 
Argument-dependent lookup is not performed.
— end note]
Similarly, the meaning of a qualified-id is established as-if by performing qualified name lookup ([basic.lookup.qual]) in the context of D.
[Example 1: 
The reference to is_array_v in the specification of std​::​to_array ([array.creation]) refers to ​::​std​::​is_array_v.
— end example]
[Note 2: 
Operators in expressions ([over.match.oper]) are not so constrained; see [global.functions].
— end note]
The meaning of the unqualified name swap is established in an overload resolution context for swappable values ([swappable.requirements]).
The meanings of the unqualified names make_error_code, make_error_condition, and submdspan_mapping are established as-if by performing argument-dependent lookup ([basic.lookup.argdep]).
150)150)
The C standard library headers ([support.c.headers]) also define names within the global namespace, while the C++ headers for C library facilities ([headers]) can also define names within the global namespace.
151)151)
This gives implementers freedom to use inline namespaces to support multiple configurations of the library.

16.4.2.3 Headers [headers]

1
#
Each element of the C++ standard library is declared or defined (as appropriate) in a header.152
2
#
The C++ standard library provides the C++ library headers, shown in Table 24.
Table 24: C++ library headers [tab:headers.cpp]
<algorithm>
<format>
<new>
<stdexcept>
<any>
<forward_list>
<numbers>
<stdfloat>
<array>
<fstream>
<numeric>
<stop_token>
<atomic>
<functional>
<optional>
<streambuf>
<barrier>
<future>
<ostream>
<string>
<bit>
<generator>
<print>
<string_view>
<bitset>
<hazard_pointer>
<queue>
<strstream>
<charconv>
<initializer_list>
<random>
<syncstream>
<chrono>
<iomanip>
<ranges>
<system_error>
<compare>
<ios>
<ratio>
<text_encoding>
<complex>
<iosfwd>
<rcu>
<thread>
<concepts>
<iostream>
<regex>
<tuple>
<condition_variable>
<istream>
<scoped_allocator>
<type_traits>
<coroutine>
<iterator>
<semaphore>
<typeindex>
<debugging>
<latch>
<set>
<typeinfo>
<deque>
<limits>
<shared_mutex>
<unordered_map>
<exception>
<linalg>
<source_location>
<unordered_set>
<execution>
<list>
<span>
<utility>
<expected>
<locale>
<spanstream>
<valarray>
<filesystem>
<map>
<sstream>
<variant>
<flat_map>
<mdspan>
<stack>
<vector>
<flat_set>
<memory>
<stacktrace>
<version>
<memory_resource>
<mutex>
3
#
The facilities of the C standard library are provided in the additional headers shown in Table 25.153
Table 25: C++ headers for C library facilities [tab:headers.cpp.c]
<cassert>
<cfenv>
<climits>
<csetjmp>
<cstddef>
<cstdlib>
<cuchar>
<cctype>
<cfloat>
<clocale>
<csignal>
<cstdint>
<cstring>
<cwchar>
<cerrno>
<cinttypes>
<cmath>
<cstdarg>
<cstdio>
<ctime>
<cwctype>
4
#
The headers listed in Table 24, or, for a freestanding implementation, the subset of such headers that are provided by the implementation, are collectively known as the importable C++ library headers.
[Note 1: 
Importable C++ library headers can be imported ([module.import]).
— end note]
[Example 1: import <vector>; // imports the <vector> header unit std::vector<int> vi; // OK — end example]
5
#
Except as noted in [library] through [thread] and [depr], the contents of each header cname is the same as that of the corresponding header name.h as specified in the C standard library ([intro.refs]).
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 (including any overloads added in [support] through [thread] and [depr]) are first declared within the global namespace scope and are then injected into namespace std by explicit using-declarations ([namespace.udecl]).
6
#
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 2: 
The names defined as macros in C include the following: assert, offsetof, setjmp, va_arg, va_end, and va_start.
— end note]
7
#
Names that are defined as functions in C shall be defined as functions in the C++ standard library.154
8
#
Identifiers that are keywords or operators in C++ shall not be defined as macros in C++ standard library headers.155
9
#
[support.c.headers], C standard library headers, describes the effects of using the name.h (C header) form in a C++ program.156
10
#
ISO/IEC 9899:2018, Annex K describes a large number of functions, with associated types and macros, which “promote safer, more secure programming” than many of the traditional C library functions.
The names of the functions have a suffix of _s; most of them provide the same service as the C library function with the unsuffixed name, but generally take an additional argument whose value is the size of the result array.
If any C++ header is included, it is implementation-defined whether any of these names is declared in the global namespace.
(None of them is declared in namespace std.)
11
#
Table 26 lists the Annex K names that may be declared in some header.
These names are also subject to the restrictions of [macro.names].
Table 26: Names from ISO/IEC 9899:2018, Annex K [tab:c.annex.k.names]
abort_handler_s
mbstowcs_s
strncat_s
vswscanf_s
asctime_s
memcpy_s
strncpy_s
vwprintf_s
bsearch_s
memmove_s
strtok_s
vwscanf_s
constraint_handler_t
memset_s
swprintf_s
wcrtomb_s
ctime_s
printf_s
swscanf_s
wcscat_s
errno_t
qsort_s
tmpfile_s
wcscpy_s
fopen_s
RSIZE_MAX
TMP_MAX_S
wcsncat_s
fprintf_s
rsize_t
tmpnam_s
wcsncpy_s
freopen_s
scanf_s
vfprintf_s
wcsnlen_s
fscanf_s
set_constraint_handler_s
vfscanf_s
wcsrtombs_s
fwprintf_s
snprintf_s
vfwprintf_s
wcstok_s
fwscanf_s
snwprintf_s
vfwscanf_s
wcstombs_s
getenv_s
sprintf_s
vprintf_s
wctomb_s
gets_s
sscanf_s
vscanf_s
wmemcpy_s
gmtime_s
strcat_s
vsnprintf_s
wmemmove_s
ignore_handler_s
strcpy_s
vsnwprintf_s
wprintf_s
localtime_s
strerrorlen_s
vsprintf_s
wscanf_s
L_tmpnam_s
strerror_s
vsscanf_s
mbsrtowcs_s
strlen_s
vswprintf_s
152)152)
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]).
153)153)
It is intentional that there is no C++ header for any of these C headers: <stdnoreturn.h>, <threads.h>.
154)154)
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.
155)155)
In particular, including the standard header <iso646.h> has no effect.
156)156)
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.

16.4.2.4 Modules [std.modules]

1
#
The C++ standard library provides the following C++ library modules.
2
#
The named module std exports declarations in namespace std that are provided by the importable C++ library headers (Table 24 or the subset provided by a freestanding implementation) and the C++ headers for C library facilities (Table 25).
It additionally exports declarations in the global namespace for the storage allocation and deallocation functions that are provided by <new>.
3
#
The named module std.compat exports the same declarations as the named module std, and additionally exports declarations in the global namespace corresponding to the declarations in namespace std that are provided by the C++ headers for C library facilities (Table 25), except the explicitly excluded declarations described in [support.c.headers.other].
4
#
It is unspecified to which module a declaration in the standard library is attached.
[Note 1: 
Conforming implementations ensure that mixing #include and import does not result in conflicting attachments ([basic.link]).
— end note]
Recommended practice: Implementations should ensure such attachments do not preclude further evolution or decomposition of the standard library modules.
5
#
A declaration in the standard library denotes the same entity regardless of whether it was made reachable through including a header, importing a header unit, or importing a C++ library module.
6
#
Recommended practice: Implementations should avoid exporting any other declarations from the C++ library modules.
[Note 2: 
Like all named modules, the C++ library modules do not make macros visible ([module.import]), such as assert ([cassert.syn]), errno ([cerrno.syn]), offsetof ([cstddef.syn]), and va_arg ([cstdarg.syn]).
— end note]

16.4.2.5 Freestanding implementations [compliance]

1
#
Two kinds of implementations are defined: hosted and freestanding ([intro.compliance]); the kind of the implementation is implementation-defined.
For a hosted implementation, this document describes the set of available headers.
2
#
A freestanding implementation has an implementation-defined set of headers.
This set shall include at least the headers shown in Table 27.
Table 27: C++ headers for freestanding implementations [tab:headers.cpp.fs]
Subclause
Header
Common definitions
<cstddef>
C standard library
<cstdlib>
Implementation properties
<cfloat>, <climits>, <limits>,
<version>
Integer types
<cstdint>
Dynamic memory management
<new>
Type identification
<typeinfo>
Source location
<source_location>
Exception handling
<exception>
Initializer lists
<initializer_list>
Comparisons
<compare>
Coroutines support
<coroutine>
Other runtime support
<cstdarg>
Concepts library
<concepts>
Error numbers
<cerrno>
System error support
<system_error>
Memory
<memory>
Type traits
<type_traits>
Compile-time rational arithmetic
<ratio>
Utility components
<utility>
Tuples
<tuple>
Optional objects
<optional>
Variants
<variant>
Expected objects
<expected>
Function objects
<functional>
Primitive numeric conversions
<charconv>
Bit manipulation
<bit>
String view classes
<string_view>
String classes
<string>
Null-terminated sequence utilities
<cstring>, <cwchar>
Class template array
<array>
Contiguous access
<span>
Multidimensional access
<mdspan>
Iterators library
<iterator>
Ranges library
<ranges>
Algorithms library
<algorithm>, <numeric>
Mathematical functions for floating-point types
<cmath>
Atomics
<atomic>
Debugging
<debugging>
3
#
For each of the headers listed in Table 27, a freestanding implementation provides at least the freestanding items ([freestanding.item]) declared in the header.
4
#
The hosted library facilities are the set of facilities described in this document that are required for hosted implementations, but not required for freestanding implementations.
A freestanding implementation provides a (possibly empty) implementation-defined subset of the hosted library facilities.
Unless otherwise specified, the requirements on each declaration, entity, typedef-name, and macro provided in this way are the same as the corresponding requirements for a hosted implementation, except that not all of the members of the namespaces are required to be present.
5
#
A freestanding implementation provides deleted definitions ([dcl.fct.def.delete]) for a (possibly empty) implementation-defined subset of the namespace-scope functions and function templates from the hosted library facilities.
[Note 1: 
An implementation can provide a deleted definition so that the result of overload resolution does not silently change when migrating a program from a freestanding implementation to a hosted implementation.
— end note]