cppdraft_translate/cppdraft/organization.md

[organization]

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 exceptoperator new andoperator delete are defined within the namespacestd or namespaces nested within namespacestd.142

It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace.143

3

#

Whenever an unqualified name other thanswap, make_error_code, make_error_condition,from_stream, orsubmdspan_mapping is used in the specification of a declaration D in [support] through [exec] 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 namesmake_error_code, make_error_condition,from_stream, andsubmdspan_mapping are established as-if by performing argument-dependent lookup ([basic.lookup.argdep]).

142)142)

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.

143)143)

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 aheader.144

2

#

The C++ standard library provides theC++ library headers, shown in Table 24.

Table 24 — C++ library headers [tab:headers.cpp]

🔗	<forward_list>
🔗
🔗
🔗
🔗			<stop_token>
🔗	<hazard_pointer>
🔗
🔗	<initializer_list>		<string_view>
🔗	<inplace_vector>
🔗			<system_error>
🔗			<text_encoding>
🔗
🔗 <condition_variable>
🔗			<type_traits>
🔗		<scoped_allocator>
🔗
🔗			<unordered_map>
🔗		<shared_mutex>	<unordered_set>
🔗
🔗		<source_location>
🔗
🔗 <flat_map>
🔗 <flat_set>
🔗	<memory_resource>

3

#

The facilities of the C standard library are provided in theadditional headers shown in Table 25.145

Table 25 — C++ headers for C library facilities [tab:headers.cpp.c]

🔗
🔗
🔗

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 ; // imports the header unit std::vector vi; // OK — end example]

5

#

Except as noted in [library] through [exec] 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.

In the C++ standard library, however, the declarations (except for names which are defined as macros in C) are withinnamespace scope of the namespace std.

It is unspecified whether these names (including any overloads added in[support] through [exec] and [depr]) are first declared within the global namespace scope and are then injected into namespace std by explicitusing-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.146

8

#

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

9

#

Subclause [support.c.headers] describes the effects of using the name.h (C header) form in a C++ program.148

10

#

ISO/IEC 9899:2024, 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:2024, 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

144)144)

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]).

145)145)

It is intentional that there is no C++ header for any of these C headers:<stdnoreturn.h>,<threads.h>.

146)146)

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.

147)147)

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

148)148)

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 .

3

#

The named module std.compat exports the same declarations as the named module std, and additionally exports

• (3.1)

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] and

• (3.2)

declarations provided by the headers <stdbit.h> and <stdckdint.h>.

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 asassert ([cassert.syn]),errno ([cerrno.syn]),offsetof ([cstddef.syn]), andva_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 isimplementation-defined.

For a hosted implementation, this document describes the set of available headers.

2

#

A freestanding implementation has animplementation-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
🔗 [support.types]	Common definitions
🔗 [cstdlib.syn]	C standard library
🔗 [support.limits]	Implementation properties	, , ,
🔗
🔗 [cstdint.syn]	Integer types
🔗 [support.dynamic]	Dynamic memory management
🔗 [support.rtti]	Type identification
🔗 [support.srcloc]	Source location	<source_location>
🔗 [support.exception]	Exception handling
🔗 [support.initlist]	Initializer lists	<initializer_list>
🔗 [cmp]	Comparisons
🔗 [support.contract]	Contract-violation handling
🔗 [support.coroutine]	Coroutines support
🔗 [support.runtime]	Other runtime support
🔗 [concepts]	Concepts library
🔗 [errno]	Error numbers
🔗 [syserr]	System error support	<system_error>
🔗 [debugging]	Debugging
🔗 [memory]	Memory
🔗 [type.traits]	Type traits	<type_traits>
🔗 [ratio]	Compile-time rational arithmetic
🔗 [utility]	Utility components
🔗 [tuple]	Tuples
🔗 [optional]	Optional objects
🔗 [variant]	Variants
🔗 [expected]	Expected objects
🔗 [function.objects]	Function objects
🔗 [bit]	Bit manipulation
🔗 [stdbit.h.syn]	C-compatible bit manipulation	<stdbit.h>
🔗 [array]	Class template array
🔗 [inplace.vector]	Class template inplace_vector	<inplace_vector>
🔗 [views.contiguous]	Contiguous access
🔗 [views.multidim]	Multidimensional access
🔗 [iterators]	Iterators library
🔗 [ranges]	Ranges library
🔗 [algorithms]	Algorithms library	,
🔗 [execpol]	Execution policies
🔗 [string.view]	String view classes	<string_view>
🔗 [string.classes]	String classes
🔗 [c.strings]	Null-terminated sequence utilities	,
🔗 [charconv]	Primitive numeric conversions
🔗 [rand]	Random number generation
🔗 [c.math]	Mathematical functions for floating-point types
🔗 [atomics]	Atomics
🔗

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]