16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.1 General [requirements.general]

Subclause [requirements] specifies requirements that apply to the entire C++ standard library.

[support] through [exec] and [depr] specify the requirements of individual entities within the library.

Requirements specified in terms of interactions between threads do not apply to programs having only a single thread of execution.

[organization] describes the library's contents and organization, [using] describes how well-formed C++ programs gain access to library entities, [utility.requirements] describes constraints on types and functions used with the C++ standard library, [constraints] describes constraints on well-formed C++ programs, and [conforming] describes constraints on conforming implementations.

16.4.2 Library contents and organization [organization]

16.4.2.1 General [organization.general]

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

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.

All library entities except operator new and operator delete are defined within the namespace std or namespaces nested within namespace std.144

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

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 [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 names make_error_code, make_error_condition, and submdspan_mapping are established as-if by performing argument-dependent lookup ([basic.lookup.argdep]).

144)144)

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.

145)145)

This gives implementers freedom to use inline namespaces to support multiple configurations of the library.

16.4.2.3 Headers [headers]

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

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

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

🔗 <algorithm>	<forward_list>	<mutex>	<stacktrace>
🔗 <any>	<fstream>	<new>	<stdexcept>
🔗 <array>	<functional>	<numbers>	<stdfloat>
🔗 <atomic>	<future>	<numeric>	<stop_token>
🔗 <barrier>	<generator>	<optional>	<streambuf>
🔗 <bit>	<hazard_pointer>	<ostream>	<string>
🔗 <bitset>	<initializer_list>	<print>	<string_view>
🔗 <charconv>	<inplace_vector>	<queue>	<syncstream>
🔗 <chrono>	<iomanip>	<random>	<system_error>
🔗 <compare>	<ios>	<ranges>	<text_encoding>
🔗 <complex>	<iosfwd>	<ratio>	<thread>
🔗 <concepts>	<iostream>	<rcu>	<tuple>
🔗 <condition_variable>	<istream>	<regex>	<type_traits>
🔗 <coroutine>	<iterator>	<scoped_allocator>	<typeindex>
🔗 <debugging>	<latch>	<semaphore>	<typeinfo>
🔗 <deque>	<limits>	<set>	<unordered_map>
🔗 <exception>	<linalg>	<shared_mutex>	<unordered_set>
🔗 <execution>	<list>	<simd>	<utility>
🔗 <expected>	<locale>	<source_location>	<valarray>
🔗 <filesystem>	<map>	<span>	<variant>
🔗 <flat_map>	<mdspan>	<spanstream>	<vector>
🔗 <flat_set>	<memory>	<sstream>	<version>
🔗 <format>	<memory_resource>	<stack>

The facilities of the C standard library are provided in the additional headers shown in Table 25 .147

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>

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]

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 within namespace 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 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 2:

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.148

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

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

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

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

146)146)

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

147)147)

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

148)148)

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.

149)149)

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

150)150)

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]

The C++ standard library provides the following C++ library modules.

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

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

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.

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.

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]

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.

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
🔗 [support.types]	Common definitions	<cstddef>
🔗 [cstdlib.syn]	C standard library	<cstdlib>
🔗 [support.limits]	Implementation properties	<cfloat>, <climits>, <limits>,
🔗		<version>
🔗 [cstdint.syn]	Integer types	<cstdint>
🔗 [support.dynamic]	Dynamic memory management	<new>
🔗 [support.rtti]	Type identification	<typeinfo>
🔗 [support.srcloc]	Source location	<source_location>
🔗 [support.exception]	Exception handling	<exception>
🔗 [support.initlist]	Initializer lists	<initializer_list>
🔗 [cmp]	Comparisons	<compare>
🔗 [support.coroutine]	Coroutines support	<coroutine>
🔗 [support.runtime]	Other runtime support	<cstdarg>
🔗 [concepts]	Concepts library	<concepts>
🔗 [errno]	Error numbers	<cerrno>
🔗 [syserr]	System error support	<system_error>
🔗 [debugging]	Debugging	<debugging>
🔗 [memory]	Memory	<memory>
🔗 [type.traits]	Type traits	<type_traits>
🔗 [ratio]	Compile-time rational arithmetic	<ratio>
🔗 [utility]	Utility components	<utility>
🔗 [tuple]	Tuples	<tuple>
🔗 [optional]	Optional objects	<optional>
🔗 [variant]	Variants	<variant>
🔗 [expected]	Expected objects	<expected>
🔗 [function.objects]	Function objects	<functional>
🔗 [bit]	Bit manipulation	<bit>
🔗 [array]	Class template array	<array>
🔗 [inplace.vector]	Class template inplace_vector	<inplace_vector>
🔗 [views.contiguous]	Contiguous access	<span>
🔗 [views.multidim]	Multidimensional access	<mdspan>
🔗 [iterators]	Iterators library	<iterator>
🔗 [ranges]	Ranges library	<ranges>
🔗 [algorithms]	Algorithms library	<algorithm>, <numeric>
🔗 [string.view]	String view classes	<string_view>
🔗 [string.classes]	String classes	<string>
🔗 [c.strings]	Null-terminated sequence utilities	<cstring>, <cwchar>
🔗 [charconv]	Primitive numeric conversions	<charconv>
🔗 [c.math]	Mathematical functions for floating-point types	<cmath>
🔗 [atomics]	Atomics	<atomic>
🔗

For each of the headers listed in Table 27, a freestanding implementation provides at least the freestanding items ([freestanding.item]) declared in the header.

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.

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]

16.4.3 Using the library [using]

16.4.3.1 Overview [using.overview]

Subclause [using] describes how a C++ program gains access to the facilities of the C++ standard library.

[using.headers] describes effects during translation phase 4, while [using.linkage] describes effects during phase 8 .

16.4.3.2 Headers [using.headers]

The entities in the C++ standard library are defined in headers, whose contents are made available to a translation unit when it contains the appropriate #include preprocessing directive ([cpp.include]) or the appropriate import declaration ([module.import]).

A translation unit may include library headers in any order ([lex.separate]).

Each may be included more than once, with no effect different from being included exactly once, except that the effect of including either <cassert> or <assert.h> depends each time on the lexically current definition of NDEBUG.151

A translation unit shall include a header only outside of any declaration or definition and, in the case of a module unit, only in its global-module-fragment, and shall include the header or import the corresponding header unit lexically before the first reference in that translation unit to any of the entities declared in that header.

No diagnostic is required.

151)151)

This is the same as the C standard library.

16.4.3.3 Linkage [using.linkage]

Entities in the C++ standard library have external linkage .

Unless otherwise specified, objects and functions have the default extern "C++" linkage ([dcl.link]).

Whether a name from the C standard library declared with external linkage has extern "C" or extern "C++" linkage is implementation-defined.

It is recommended that an implementation use extern "C++" linkage for this purpose.152

Objects and functions defined in the library and required by a C++ program are included in the program prior to program startup.

152)152)

The only reliable way to declare an object or function signature from the C standard library is by including the header that declares it, notwithstanding the latitude granted in ISO/IEC 9899:2018, 7.1.4.

16.4.4 Requirements on types and expressions [utility.requirements]

16.4.4.1 General [utility.requirements.general]

[utility.arg.requirements] describes requirements on types and expressions used to instantiate templates defined in the C++ standard library.

[swappable.requirements] describes the requirements on swappable types and swappable expressions.

[nullablepointer.requirements] describes the requirements on pointer-like types that support null values.

[hash.requirements] describes the requirements on hash function objects.

[allocator.requirements] describes the requirements on storage allocators.

16.4.4.2 Template argument requirements [utility.arg.requirements]

The template definitions in the C++ standard library refer to various named requirements whose details are set out in Tables 28–35 .

In these tables,

(1.1)
T denotes an object or reference type to be supplied by a C++ program instantiating a template,
(1.2)
a, b, and c denote values of type (possibly const) T,
(1.3)
s and t denote modifiable lvalues of type T,
(1.4)
u denotes an identifier,
(1.5)
rv denotes an rvalue of type T, and
(1.6)
v denotes an lvalue of type (possibly const) T or an rvalue of type const T.

In general, a default constructor is not required.

Certain container class member function signatures specify T() as a default argument.

T() shall be a well-defined expression ([dcl.init]) if one of those signatures is called using the default argument .

Table 28 — Cpp17EqualityComparable requirements [tab:cpp17.equalitycomparable]

🔗 Expression	Return type	Requirement
🔗 a == b	decltype(a == b) models boolean-testable	== is an equivalence relation, that is, it has the following properties: For all a, a == a. If a == b, then b == a. If a == b and b == c, then a == c.

Table 29 — Cpp17LessThanComparable requirements [tab:cpp17.lessthancomparable]

🔗 Expression	Return type	Requirement
🔗 a < b	decltype(a < b) models boolean-testable	< is a strict weak ordering relation ([alg.sorting])

Table 30 — Cpp17DefaultConstructible requirements [tab:cpp17.defaultconstructible]

🔗 Expression	Post-condition
🔗 T t;	object t is default-initialized
🔗 T u{};	object u is value-initialized or aggregate-initialized
🔗 T() T{}	an object of type T is value-initialized or aggregate-initialized

Table 31 — Cpp17MoveConstructible requirements [tab:cpp17.moveconstructible]

🔗 Expression	Post-condition
🔗 T u = rv;	u is equivalent to the value of rv before the construction
🔗 T(rv)	T(rv) is equivalent to the value of rv before the construction
🔗 rv's state is unspecified [Note 1: rv must still meet the requirements of the library component that is using it. The operations listed in those requirements must work as specified whether rv has been moved from or not. — end note]

Table 32 — Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible) [tab:cpp17.copyconstructible]

🔗 Expression	Post-condition
🔗 T u = v;	the value of v is unchanged and is equivalent to u
🔗 T(v)	the value of v is unchanged and is equivalent to T(v)

Table 33 — Cpp17MoveAssignable requirements [tab:cpp17.moveassignable]

🔗 Expression	Return type	Return value	Post-condition
🔗 t = rv	T&	t	If t and rv do not refer to the same object, t is equivalent to the value of rv before the assignment
🔗 rv's state is unspecified. [Note 2: rv must still meet the requirements of the library component that is using it, whether or not t and rv refer to the same object. The operations listed in those requirements must work as specified whether rv has been moved from or not. — end note]

Table 34 — Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable) [tab:cpp17.copyassignable]

🔗 Expression	Return type	Return value	Post-condition
🔗 t = v	T&	t	t is equivalent to v, the value of v is unchanged

Table 35 — Cpp17Destructible requirements [tab:cpp17.destructible]

🔗 Expression	Post-condition
🔗 u.~T()	All resources owned by u are reclaimed, no exception is propagated.
🔗 [Note 3: Array types and non-object types are not Cpp17Destructible. — end note]

16.4.4.3 Swappable requirements [swappable.requirements]

This subclause provides definitions for swappable types and expressions.

In these definitions, let t denote an expression of type T, and let u denote an expression of type U.

An object t is swappable with an object u if and only if

(2.1)
the expressions swap(t, u) and swap(u, t) are valid when evaluated in the context described below, and
(2.2)
these expressions have the following effects:
- (2.2.1)
  the object referred to by t has the value originally held by u and
- (2.2.2)
  the object referred to by u has the value originally held by t.

The context in which swap(t, u) and swap(u, t) are evaluated shall ensure that a binary non-member function named “swap” is selected via overload resolution on a candidate set that includes:

(3.1)
the two swap function templates defined in <utility> and
(3.2)
the lookup set produced by argument-dependent lookup .

[Note 1:

If T and U are both fundamental types or arrays of fundamental types and the declarations from the header <utility> are in scope, the overall lookup set described above is equivalent to that of the qualified name lookup applied to the expression std::swap(t, u) or std::swap(u, t) as appropriate.

— end note]

[Note 2:

It is unspecified whether a library component that has a swappable requirement includes the header <utility> to ensure an appropriate evaluation context.

— end note]

An rvalue or lvalue t is swappable if and only if t is swappable with any rvalue or lvalue, respectively, of type T.

A type X meets the Cpp17Swappable requirements if lvalues of type X are swappable.

A type X meeting any of the iterator requirements ([iterator.requirements]) meets the Cpp17ValueSwappable requirements if, for any dereferenceable object x of type X, *x is swappable.

[Example 1:

User code can ensure that the evaluation of swap calls is performed in an appropriate context under the various conditions as follows: #include <cassert> #include <utility> // Preconditions: std::forward<T>(t) is swappable with std::forward(u). template<class T, class U> void value_swap(T&& t, U&& u) { using std::swap; swap(std::forward<T>(t), std::forward(u)); // OK, uses “swappable with'' conditions // for rvalues and lvalues } // Preconditions: T meets the Cpp17Swappable requirements. template<class T> void lv_swap(T& t1, T& t2) { using std::swap; swap(t1, t2); // OK, uses swappable conditions for lvalues of type T } namespace N { struct A { int m; }; struct Proxy { A* a; }; Proxy proxy(A& a) { return Proxy{ &a }; } void swap(A& x, Proxy p) { std::swap(x.m, p.a->m); // OK, uses context equivalent to swappable // conditions for fundamental types } void swap(Proxy p, A& x) { swap(x, p); } // satisfy symmetry constraint } int main() { int i = 1, j = 2; lv_swap(i, j); assert(i == 2 && j == 1); N::A a1 = { 5 }, a2 = { -5 }; value_swap(a1, proxy(a2)); assert(a1.m == -5 && a2.m == 5); }

— end example]

16.4.4.4 Cpp17NullablePointer requirements [nullablepointer.requirements]

A Cpp17NullablePointer type is a pointer-like type that supports null values.

A type P meets the Cpp17NullablePointer requirements if

(1.1)
P meets the Cpp17EqualityComparable, Cpp17DefaultConstructible, Cpp17CopyConstructible, Cpp17CopyAssignable, Cpp17Swappable, and Cpp17Destructible requirements,
(1.2)
the expressions shown in Table 36 are valid and have the indicated semantics, and
(1.3)
P meets all the other requirements of this subclause.

A value-initialized object of type P produces the null value of the type.

The null value shall be equivalent only to itself.

A default-initialized object of type P may have an indeterminate or erroneous value.

[Note 1:

Operations involving indeterminate values can cause undefined behavior, and operations involving erroneous values can cause erroneous behavior ([basic.indet]).

— end note]

An object p of type P can be contextually converted to bool .

The effect shall be as if p != nullptr had been evaluated in place of p.

No operation which is part of the Cpp17NullablePointer requirements shall exit via an exception.

In Table 36, u denotes an identifier, t denotes a non-const lvalue of type P, a and b denote values of type (possibly const) P, and np denotes a value of type (possibly const) std::nullptr_t.

Table 36 — Cpp17NullablePointer requirements [tab:cpp17.nullablepointer]

🔗 Expression	Return type	Operational semantics
🔗 P u(np);		Postconditions: u == nullptr
🔗 P u = np;
🔗 P(np)		Postconditions: P(np) == nullptr
🔗 t = np	P&	Postconditions: t == nullptr
🔗 a != b	decltype(a != b) models boolean-testable	!(a == b)
🔗 a == np	decltype(a == np) and decltype(np == a) each model boolean-testable	a == P()
🔗 np == a
🔗 a != np	decltype(a != np) and decltype(np != a) each model boolean-testable	!(a == np)
🔗 np != a

16.4.4.5 Cpp17Hash requirements [hash.requirements]

A type H meets the Cpp17Hash requirements if

(1.1)
it is a function object type ([function.objects]),
(1.2)
it meets the Cpp17CopyConstructible (Table 32) and Cpp17Destructible (Table 35) requirements, and
(1.3)
the expressions shown in Table 37 are valid and have the indicated semantics.

Given Key is an argument type for function objects of type H, in Table 37 h is a value of type (possibly const) H, u is an lvalue of type Key, and k is a value of a type convertible to (possibly const) Key.

Table 37 — Cpp17Hash requirements [tab:cpp17.hash]

🔗 Expression	Return type	Requirement
🔗 h(k)	size_t	The value returned shall depend only on the argument k for the duration of the program. [Note 1: Thus all evaluations of the expression h(k) with the same value for k yield the same result for a given execution of the program. — end note] For two different values t1 and t2, the probability that h(t1) and h(t2) compare equal should be very small, approaching 1.0 / numeric_limits<size_t>::max().
🔗 h(u)	size_t	Shall not modify u.

16.4.4.6 Cpp17Allocator requirements [allocator.requirements]

16.4.4.6.1 General [allocator.requirements.general]

The library describes a standard set of requirements for allocators, which are class-type objects that encapsulate the information about an allocation model.

This information includes the knowledge of pointer types, the type of their difference, the type of the size of objects in this allocation model, as well as the memory allocation and deallocation primitives for it.

All of the string types ([strings]), containers ([containers]) (except array and inplace_vector), string buffers and string streams ([input.output]), and match_results are parameterized in terms of allocators.

In [allocator.requirements],

(2.1)
T, U, C denote any cv-unqualified object type ([basic.types.general]),
(2.2)
X denotes an allocator class for type T,
(2.3)
Y denotes the corresponding allocator class for type U,
(2.4)
XX denotes the type allocator_traits<X>,
(2.5)
YY denotes the type allocator_traits<Y>,
(2.6)
a, a1, a2 denote lvalues of type X,
(2.7)
u denotes the name of a variable being declared,
(2.8)
b denotes a value of type Y,
(2.9)
c denotes a pointer of type C* through which indirection is valid,
(2.10)
p denotes a value of type XX::pointer obtained by calling a1.allocate, where a1 == a,
(2.11)
q denotes a value of type XX::const_pointer obtained by conversion from a value p,
(2.12)
r denotes a value of type T& obtained by the expression *p,
(2.13)
w denotes a value of type XX::void_pointer obtained by conversion from a value p,
(2.14)
x denotes a value of type XX::const_void_pointer obtained by conversion from a value q or a value w,
(2.15)
y denotes a value of type XX::const_void_pointer obtained by conversion from a result value of YY::allocate, or else a value of type (possibly const) std::nullptr_t,
(2.16)
n denotes a value of type XX::size_type,
(2.17)
Args denotes a template parameter pack, and
(2.18)
args denotes a function parameter pack with the pattern Args&&.

The class template allocator_traits ([allocator.traits]) supplies a uniform interface to all allocator types.

This subclause describes the requirements on allocator types and thus on types used to instantiate allocator_traits.

A requirement is optional if a default for a given type or expression is specified.

Within the standard library allocator_traits template, an optional requirement that is not supplied by an allocator is replaced by the specified default type or expression.

[Note 1:

There are no program-defined specializations of allocator_traits.

— end note]

🔗

typename X::pointer

Remarks: Default: T*

🔗

typename X::const_pointer

Mandates: XX::pointer is convertible to XX::const_pointer.

Remarks: Default: pointer_traits<XX::pointer>::rebind<const T>

🔗

typename X::void_pointer
typename Y::void_pointer

Mandates: XX::pointer is convertible to XX::void_pointer.

XX::void_pointer and YY::void_pointer are the same type.

Remarks: Default: pointer_traits<XX::pointer>::rebind<void>

🔗

typename X::const_void_pointer
typename Y::const_void_pointer

Mandates: XX::pointer, XX::const_pointer, and XX::void_pointer are convertible to XX::const_void_pointer.

XX::const_void_pointer and YY::const_void_pointer are the same type.

Remarks: Default: pointer_traits<XX::pointer>::rebind<const void>

🔗

typename X::value_type

Result: Identical to T.

🔗

typename X::size_type

Result: An unsigned integer type that can represent the size of the largest object in the allocation model.

Remarks: Default: make_unsigned_t<XX::difference_type>

🔗

typename X::difference_type

Result: A signed integer type that can represent the difference between any two pointers in the allocation model.

Remarks: Default: pointer_traits<XX::pointer>::difference_type

🔗

typename X::rebind<U>::other

Result: Y

Postconditions: For all U (including T), YY::rebind_alloc<T> is X.

Remarks: If Allocator is a class template instantiation of the form SomeAllocator<T, Args>, where Args is zero or more type arguments, and Allocator does not supply a rebind member template, the standard allocator_traits template uses SomeAllocator<U, Args> in place of Allocator::rebind::other by default.

For allocator types that are not template instantiations of the above form, no default is provided.

[Note 2:

The member class template rebind of X is effectively a typedef template.

In general, if the name Allocator is bound to SomeAllocator<T>, then Allocator::rebind::other is the same type as SomeAllocator, where SomeAllocator<T>::value_type is T and SomeAllocator::value_type is U.

— end note]

🔗

*p

Result: T&

🔗

*q

Result: const T&

Postconditions: *q refers to the same object as *p.

🔗

p->m

Result: Type of T::m.

Preconditions: (*p).m is well-defined.

Effects: Equivalent to (*p).m.

🔗

q->m

Result: Type of T::m.

Preconditions: (*q).m is well-defined.

Effects: Equivalent to (*q).m.

🔗

static_cast<XX::pointer>(w)

Result: XX::pointer

Postconditions: static_cast<XX::pointer>(w) == p.

🔗

static_cast<XX::const_pointer>(x)

Result: XX::const_pointer

Postconditions: static_cast<XX::const_pointer>(x) == q.

🔗

pointer_traits<XX::pointer>::pointer_to(r)

Result: XX::pointer

Postconditions: Same as p.

🔗

a.allocate(n)

Result: XX::pointer

Effects: Memory is allocated for an array of n T and such an object is created but array elements are not constructed.

[Example 1:

When reusing storage denoted by some pointer value p, launder(reinterpret_cast<T*>(new (p) byte[n * sizeof(T)])) can be used to implicitly create a suitable array object and obtain a pointer to it.

— end example]

Throws: allocate may throw an appropriate exception.

[Note 3:

It is intended that a.allocate be an efficient means of allocating a single object of type T, even when sizeof(T) is small.

That is, there is no need for a container to maintain its own free list.

— end note]

Remarks: If n == 0, the return value is unspecified.

🔗

a.allocate(n, y)

Result: XX::pointer

Effects: Same as a.allocate(n).

The use of y is unspecified, but it is intended as an aid to locality.

Remarks: Default: a.allocate(n)

🔗

a.allocate_at_least(n)

Result: allocation_result<XX::pointer, XX::size_type>

Returns: allocation_result<XX::pointer, XX::size_type>{ptr, count} where ptr is memory allocated for an array of count T and such an object is created but array elements are not constructed, such that count ≥ n.

If n == 0, the return value is unspecified.

Throws: allocate_at_least may throw an appropriate exception.

Remarks: Default: {a.allocate(n), n}.

🔗

a.deallocate(p, n)

Result: (not used)

Preconditions:

(48.1)
If p is memory that was obtained by a call to a.allocate_at_least, let ret be the value returned and req be the value passed as the first argument of that call.

p is equal to ret.ptr and n is a value such that req ≤ n ≤ ret.count.
(48.2)
Otherwise, p is a pointer value obtained from allocate.

n equals the value passed as the first argument to the invocation of allocate which returned p.

p has not been invalidated by an intervening call to deallocate.

Throws: Nothing.

🔗

a.max_size()

Result: XX::size_type

Returns: The largest value n that can meaningfully be passed to a.allocate(n).

Remarks: Default: numeric_limits<size_type>::max() / sizeof(value_type)

🔗

a1 == a2

Result: bool

Returns: true only if storage allocated from each can be deallocated via the other.

Throws: Nothing.

Remarks: operator== shall be reflexive, symmetric, and transitive.

🔗

a1 != a2

Result: bool

Returns: !(a1 == a2).

🔗

a == b

Result: bool

Returns: a == YY::rebind_alloc<T>(b).

🔗

a != b

Result: bool

Returns: !(a == b).

🔗

X u(a);
X u = a;

Postconditions: u == a

Throws: Nothing.

🔗

X u(b);

Postconditions: Y(u) == b and u == X(b).

Throws: Nothing.

🔗

X u(std::move(a));
X u = std::move(a);

Postconditions: The value of a is unchanged and is equal to u.

Throws: Nothing.

🔗

X u(std::move(b));

Postconditions: u is equal to the prior value of X(b).

Throws: Nothing.

🔗

a.construct(c, args...)

Result: (not used)

Effects: Constructs an object of type C at c.

Remarks: Default: construct_at(c, std::forward<Args>(args)...)

🔗

a.destroy(c)

Result: (not used)

Effects: Destroys the object at c.

Remarks: Default: destroy_at(c)

🔗

a.select_on_container_copy_construction()

Result: X

Returns: Typically returns either a or X().

Remarks: Default: return a;

🔗

typename X::propagate_on_container_copy_assignment

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be copied when the client container is copy-assigned; if so, X shall meet the Cpp17CopyAssignable requirements (Table 34) and the copy operation shall not throw exceptions.

Remarks: Default: false_type

🔗

typename X::propagate_on_container_move_assignment

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be moved when the client container is move-assigned; if so, X shall meet the Cpp17MoveAssignable requirements (Table 33) and the move operation shall not throw exceptions.

Remarks: Default: false_type

🔗

typename X::propagate_on_container_swap

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be swapped when the client container is swapped; if so, X shall meet the Cpp17Swappable requirements ([swappable.requirements]) and the swap operation shall not throw exceptions.

Remarks: Default: false_type

🔗

typename X::is_always_equal

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if the expression a1 == a2 is guaranteed to be true for any two (possibly const) values a1, a2 of type X.

Remarks: Default: is_empty<X>::type

An allocator type X shall meet the Cpp17CopyConstructible requirements (Table 32).

The XX::pointer, XX::const_pointer, XX::void_pointer, and XX::const_void_pointer types shall meet the Cpp17NullablePointer requirements (Table 36).

No constructor, comparison operator function, copy operation, move operation, or swap operation on these pointer types shall exit via an exception.

XX::pointer and XX::const_pointer shall also meet the requirements for a Cpp17RandomAccessIterator ([random.access.iterators]) and the additional requirement that, when p and (p + n) are dereferenceable pointer values for some integral value n, addressof(*(p + n)) == addressof(*p) + n is true.

Let x1 and x2 denote objects of (possibly different) types XX::void_pointer, XX::const_void_pointer, XX::pointer, or XX::const_pointer.

Then, x1 and x2 are equivalently-valued pointer values, if and only if both x1 and x2 can be explicitly converted to the two corresponding objects px1 and px2 of type XX::const_pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2 evaluates to true.

Let w1 and w2 denote objects of type XX::void_pointer.

Then for the expressions w1 == w2 w1 != w2 either or both objects may be replaced by an equivalently-valued object of type XX::const_void_pointer with no change in semantics.

Let p1 and p2 denote objects of type XX::pointer.

Then for the expressions p1 == p2 p1 != p2 p1 < p2 p1 <= p2 p1 >= p2 p1 > p2 p1 - p2 either or both objects may be replaced by an equivalently-valued object of type XX::const_pointer with no change in semantics.

An allocator may constrain the types on which it can be instantiated and the arguments for which its construct or destroy members may be called.

If a type cannot be used with a particular allocator, the allocator class or the call to construct or destroy may fail to instantiate.

If the alignment associated with a specific over-aligned type is not supported by an allocator, instantiation of the allocator for that type may fail.

The allocator also may silently ignore the requested alignment.

[Note 4:

Additionally, the member function allocate for that type can fail by throwing an object of type bad_alloc.

— end note]

[Example 2:

The following is an allocator class template supporting the minimal interface that meets the requirements of [allocator.requirements.general]: template<class T> struct SimpleAllocator { using value_type = T; SimpleAllocator(ctor args); template<class U> SimpleAllocator(const SimpleAllocator& other); T* allocate(std::size_t n); void deallocate(T* p, std::size_t n); template<class U> bool operator==(const SimpleAllocator& rhs) const; };

— end example]

The following exposition-only concept defines the minimal requirements on an Allocator type.

template<class Alloc> concept simple-allocator = requires(Alloc alloc, size_t n) { { *alloc.allocate(n) } -> same_as<typename Alloc::value_type&>; { alloc.deallocate(alloc.allocate(n), n) }; } && copy_constructible<Alloc> && equality_comparable<Alloc>;

A type Alloc models simple-allocator if it meets the requirements of [allocator.requirements.general].

16.4.4.6.2 Allocator completeness requirements [allocator.requirements.completeness]

If X is an allocator class for type T, X additionally meets the allocator completeness requirements if, whether or not T is a complete type:

(1.1)
X is a complete type, and
(1.2)
all the member types of allocator_traits<X> other than value_type are complete types.

16.4.5 Constraints on programs [constraints]

16.4.5.1 Overview [constraints.overview]

Subclause [constraints] describes restrictions on C++ programs that use the facilities of the C++ standard library.

The following subclauses specify constraints on the program's use of namespaces, its use of various reserved names, its use of headers, its use of standard library classes as base classes ([derived.classes]), its definitions of replacement functions, and its installation of handler functions during execution.

16.4.5.2 Namespace use [namespace.constraints]

16.4.5.2.1 Namespace std [namespace.std]

Unless otherwise specified, the behavior of a C++ program is undefined if it adds declarations or definitions to namespace std or to a namespace within namespace std.

Unless explicitly prohibited, a program may add a template specialization for any standard library class template to namespace std provided that

(2.1)
the added declaration depends on at least one program-defined type, and
(2.2)
the specialization meets the standard library requirements for the original template.153

The behavior of a C++ program is undefined if it declares an explicit or partial specialization of any standard library variable template, except where explicitly permitted by the specification of that variable template.

[Note 1:

The requirements on an explicit or partial specialization are stated by each variable template that grants such permission.

— end note]

The behavior of a C++ program is undefined if it declares

(4.1)
an explicit specialization of any member function of a standard library class template, or
(4.2)
an explicit specialization of any member function template of a standard library class or class template, or
(4.3)
an explicit or partial specialization of any member class template of a standard library class or class template, or
(4.4)
a deduction guide for any standard library class template.

A program may explicitly instantiate a class template defined in the standard library only if the declaration

(5.1)
depends on the name of at least one program-defined type, and
(5.2)
the instantiation meets the standard library requirements for the original template.

Let F denote a standard library function ([global.functions]), a standard library static member function, or an instantiation of a standard library function template.

Unless F is designated an addressable function, the behavior of a C++ program is unspecified (possibly ill-formed) if it explicitly or implicitly attempts to form a pointer to F.

[Note 2:

Possible means of forming such pointers include application of the unary & operator ([expr.unary.op]), addressof ([specialized.addressof]), or a function-to-pointer standard conversion ([conv.func]).

— end note]

Moreover, the behavior of a C++ program is unspecified (possibly ill-formed) if it attempts to form a reference to F or if it attempts to form a pointer-to-member designating either a standard library non-static member function ([member.functions]) or an instantiation of a standard library member function template.

A translation unit shall not declare namespace std to be an inline namespace ([namespace.def]).

153)153)

Any library code that instantiates other library templates must be prepared to work adequately with any user-supplied specialization that meets the minimum requirements of this document.

16.4.5.2.2 Namespace posix [namespace.posix]

The behavior of a C++ program is undefined if it adds declarations or definitions to namespace posix or to a namespace within namespace posix unless otherwise specified.

The namespace posix is reserved for use by ISO/IEC/IEEE 9945 and other POSIX standards.

16.4.5.2.3 Namespaces for future standardization [namespace.future]

Top-level namespaces whose namespace-name consists of std followed by one or more digits ([lex.name]) are reserved for future standardization.

The behavior of a C++ program is undefined if it adds declarations or definitions to such a namespace.

[Example 1:

The top-level namespace std2 is reserved for use by future revisions of this International Standard.

— end example]

16.4.5.3 Reserved names [reserved.names]

16.4.5.3.1 General [reserved.names.general]

The C++ standard library reserves the following kinds of names:

(1.1)
macros
(1.2)
global names
(1.3)
names with external linkage

If a program declares or defines a name in a context where it is reserved, other than as explicitly allowed by [library], its behavior is undefined.

16.4.5.3.2 Zombie names [zombie.names]

In namespace std, the names shown in Table 38 are reserved for previous standardization:

Table 38 — Zombie names in namespace std [tab:zombie.names.std]

🔗 auto_ptr	generate_header	pointer_to_binary_function
🔗 auto_ptr_ref	get_pointer_safety	pointer_to_unary_function
🔗 binary_function	get_temporary_buffer	ptr_fun
🔗 binary_negate	get_unexpected	random_shuffle
🔗 bind1st	gets	raw_storage_iterator
🔗 bind2nd	is_literal_type	result_of
🔗 binder1st	is_literal_type_v	result_of_t
🔗 binder2nd	istrstream	return_temporary_buffer
🔗 codecvt_mode	little_endian	set_unexpected
🔗 codecvt_utf16	mem_fun1_ref_t	strstream
🔗 codecvt_utf8	mem_fun1_t	strstreambuf
🔗 codecvt_utf8_utf16	mem_fun_ref_t	unary_function
🔗 const_mem_fun1_ref_t	mem_fun_ref	unary_negate
🔗 const_mem_fun1_t	mem_fun_t	uncaught_exception
🔗 const_mem_fun_ref_t	mem_fun	undeclare_no_pointers
🔗 const_mem_fun_t	not1	undeclare_reachable
🔗 consume_header	not2	unexpected_handler
🔗 declare_no_pointers	ostrstream	wbuffer_convert
🔗 declare_reachable	pointer_safety	wstring_convert

The names shown in Table 39 are reserved as members for previous standardization, and may not be used as a name for object-like macros in portable code:

Table 39 — Zombie object-like macros [tab:zombie.names.objmacro]

🔗 argument_type	op	second_argument_type
🔗 first_argument_type	open_mode	seek_dir
🔗 io_state	preferred	strict

The names shown in Table 40 are reserved as member functions for previous standardization, and may not be used as a name for function-like macros in portable code:

Table 40 — Zombie function-like macros [tab:zombie.names.fnmacro]

🔗

converted

freeze

from_bytes

pcount

stossc

to_bytes

The header names shown in Table 41 are reserved for previous standardization:

16.4.5.3.3 Macro names [macro.names]

A translation unit that includes a standard library header shall not #define or #undef names declared in any standard library header.

A translation unit shall not #define or #undef names lexically identical to keywords, to the identifiers listed in Table 4, or to the attribute-tokens described in [dcl.attr], except that the names likely and unlikely may be defined as function-like macros ([cpp.replace]).

16.4.5.3.4 External linkage [extern.names]

Each name declared as an object with external linkage in a header is reserved to the implementation to designate that library object with external linkage,154 both in namespace std and in the global namespace.

Each global function signature declared with external linkage in a header is reserved to the implementation to designate that function signature with external linkage.155

Each name from the C standard library declared with external linkage is reserved to the implementation for use as a name with extern "C" linkage, both in namespace std and in the global namespace.

Each function signature from the C standard library declared with external linkage is reserved to the implementation for use as a function signature with both extern "C" and extern "C++" linkage,156 or as a name of namespace scope in the global namespace.

154)154)

The list of such reserved names includes errno, declared or defined in <cerrno>.

155)155)

The list of such reserved function signatures with external linkage includes setjmp(jmp_buf), declared or defined in <csetjmp>, and va_end(va_list), declared or defined in <cstdarg>.

156)156)

The function signatures declared in <cuchar>, <cwchar>, and <cwctype> are always reserved, notwithstanding the restrictions imposed in subclause 4.5.1 of Amendment 1 to the C Standard for these headers.

16.4.5.3.5 Types [extern.types]

For each type T from the C standard library, the types ::T and std::T are reserved to the implementation and, when defined, ::T shall be identical to std::T.

16.4.5.3.6 User-defined literal suffixes [usrlit.suffix]

Literal suffix identifiers ([over.literal]) that do not start with an underscore are reserved for future standardization.

Literal suffix identifiers that contain a double underscore __ are reserved for use by C++ implementations.

16.4.5.4 Headers [alt.headers]

If a file with a name equivalent to the derived file name for one of the C++ standard library headers is not provided as part of the implementation, and a file with that name is placed in any of the standard places for a source file to be included, the behavior is undefined.

16.4.5.5 Derived classes [derived.classes]

Virtual member function signatures defined for a base class in the C++ standard library may be overridden in a derived class defined in the program ([class.virtual]).

16.4.5.6 Replacement functions [replacement.functions]

[support] through [exec] and [depr] describe the behavior of numerous functions defined by the C++ standard library.

Under some circumstances, however, certain of these function descriptions also apply to replacement functions defined in the program.

A C++ program may provide the definition for any of the following dynamic memory allocation function signatures declared in header <new> ([basic.stc.dynamic], [new.syn]):

🔗

operator new(std::size_t) operator new(std::size_t, std::align_val_t) operator new(std::size_t, const std::nothrow_t&) operator new(std::size_t, std::align_val_t, const std::nothrow_t&)

🔗

operator delete(void*) operator delete(void*, std::size_t) operator delete(void*, std::align_val_t) operator delete(void*, std::size_t, std::align_val_t) operator delete(void*, const std::nothrow_t&) operator delete(void*, std::align_val_t, const std::nothrow_t&)

🔗

operator new[](std::size_t) operator new[](std::size_t, std::align_val_t) operator new[](std::size_t, const std::nothrow_t&) operator new[](std::size_t, std::align_val_t, const std::nothrow_t&)

🔗

operator delete[](void*) operator delete[](void*, std::size_t) operator delete[](void*, std::align_val_t) operator delete[](void*, std::size_t, std::align_val_t) operator delete[](void*, const std::nothrow_t&) operator delete[](void*, std::align_val_t, const std::nothrow_t&)

A C++ program may provide the definition of the following function signature declared in header <debugging>: bool std::is_debugger_present() noexcept

The program's definitions are used instead of the default versions supplied by the implementation ([new.delete]).

Such replacement occurs prior to program startup ([basic.def.odr], [basic.start]).

The program's declarations shall not be specified as inline.

No diagnostic is required.

16.4.5.7 Handler functions [handler.functions]

The C++ standard library provides a default version of the following handler function ([support]):

(1.1)
terminate_handler

A C++ program may install different handler functions during execution, by supplying a pointer to a function defined in the program or the library as an argument to (respectively):

(2.1)
set_new_handler
(2.2)
set_terminate

See also subclauses [alloc.errors], Storage allocation errors, and [support.exception], Exception handling.

A C++ program can get a pointer to the current handler function by calling the following functions:

(3.1)
get_new_handler
(3.2)
get_terminate

Calling the set_* and get_* functions shall not incur a data race ([intro.races]).

A call to any of the set_* functions shall synchronize with subsequent calls to the same set_* function and to the corresponding get_* function.

16.4.5.8 Other functions [res.on.functions]

In certain cases (replacement functions, handler functions, operations on types used to instantiate standard library template components), the C++ standard library depends on components supplied by a C++ program.

If these components do not meet their requirements, this document places no requirements on the implementation.

In particular, the behavior is undefined in the following cases:

(2.1)
For replacement functions ([new.delete]), if the installed replacement function does not implement the semantics of the applicable Required behavior: paragraph.
(2.2)
For handler functions ([new.handler], [terminate.handler]), if the installed handler function does not implement the semantics of the applicable Required behavior: paragraph.
(2.3)
For types used as template arguments when instantiating a template component, if the operations on the type do not implement the semantics of the applicable Requirements subclause ([allocator.requirements], [container.requirements], [iterator.requirements], [algorithms.requirements], [numeric.requirements]).

Operations on such types can report a failure by throwing an exception unless otherwise specified.
(2.4)
If any replacement function or handler function or destructor operation exits via an exception, unless specifically allowed in the applicable Required behavior: paragraph.
(2.5)
If an incomplete type ([basic.types.general]) is used as a template argument when instantiating a template component or evaluating a concept, unless specifically allowed for that component.

16.4.5.9 Function arguments [res.on.arguments]

Each of the following applies to all arguments to functions defined in the C++ standard library, unless explicitly stated otherwise.

(1.1)
If an argument to a function has an invalid value (such as a value outside the domain of the function or a pointer invalid for its intended use), the behavior is undefined.
(1.2)
If a function argument is described as being an array, the pointer actually passed to the function shall have a value such that all address computations and accesses to objects (that would be valid if the pointer did point to the first element of such an array) are in fact valid.
(1.3)
If a function argument is bound to an rvalue reference parameter, the implementation may assume that this parameter is a unique reference to this argument, except that the argument passed to a move assignment operator may be a reference to *this ([lib.types.movedfrom]).

[Note 1:
If the type of a parameter is a forwarding reference ([temp.deduct.call]) that is deduced to an lvalue reference type, then the argument is not bound to an rvalue reference.
— end note]

[Note 2:
If a program casts an lvalue to an xvalue while passing that lvalue to a library function (e.g., by calling the function with the argument std::move(x)), the program is effectively asking that function to treat that lvalue as a temporary object.

The implementation is free to optimize away aliasing checks which would possibly be needed if the argument was an lvalue.
— end note]

16.4.5.10 Library object access [res.on.objects]

The behavior of a program is undefined if calls to standard library functions from different threads may introduce a data race.

The conditions under which this may occur are specified in [res.on.data.races].

[Note 1:

Modifying an object of a standard library type that is shared between threads risks undefined behavior unless objects of that type are explicitly specified as being shareable without data races or the user supplies a locking mechanism.

— end note]

If an object of a standard library type is accessed, and the beginning of the object's lifetime does not happen before the access, or the access does not happen before the end of the object's lifetime, the behavior is undefined unless otherwise specified.

[Note 2:

This applies even to objects such as mutexes intended for thread synchronization.

— end note]

16.4.5.11 Semantic requirements [res.on.requirements]

A sequence Args of template arguments is said to model a concept C if Args satisfies C ([temp.constr.decl]) and meets all semantic requirements (if any) given in the specification of C.

If the validity or meaning of a program depends on whether a sequence of template arguments models a concept, and the concept is satisfied but not modeled, the program is ill-formed, no diagnostic required.

If the semantic requirements of a declaration's constraints ([structure.requirements]) are not modeled at the point of use, the program is ill-formed, no diagnostic required.

16.4.6 Conforming implementations [conforming]

16.4.6.1 Overview [conforming.overview]

Subclause [conforming] describes the constraints upon, and latitude of, implementations of the C++ standard library.

An implementation's use of headers is discussed in [res.on.headers], its use of macros in [res.on.macro.definitions], non-member functions in [global.functions], member functions in [member.functions], data race avoidance in [res.on.data.races], access specifiers in [protection.within.classes], class derivation in [derivation], and exceptions in [res.on.exception.handling].

16.4.6.2 Headers [res.on.headers]

A C++ header may include other C++ headers.

A C++ header shall provide the declarations and definitions that appear in its synopsis.

A C++ header shown in its synopsis as including other C++ headers shall provide the declarations and definitions that appear in the synopses of those other headers.

Certain types and macros are defined in more than one header.

Every such entity shall be defined such that any header that defines it may be included after any other header that also defines it ([basic.def.odr]).

The C standard library headers shall include only their corresponding C++ standard library header, as described in [headers].

16.4.6.3 Restrictions on macro definitions [res.on.macro.definitions]

The names and global function signatures described in [contents] are reserved to the implementation.

All object-like macros defined by the C standard library and described in this Clause as expanding to integral constant expressions are also suitable for use in #if preprocessing directives, unless explicitly stated otherwise.

16.4.6.4 Non-member functions [global.functions]

It is unspecified whether any non-member functions in the C++ standard library are defined as inline .

A call to a non-member function signature described in [support] through [exec] and [depr] shall behave as if the implementation declared no additional non-member function signatures.157

An implementation shall not declare a non-member function signature with additional default arguments.

Unless otherwise specified, calls made by functions in the standard library to non-operator, non-member functions do not use functions from another namespace which are found through argument-dependent name lookup ([basic.lookup.argdep]).

[Note 1:

The phrase “unless otherwise specified” applies to cases such as the swappable with requirements ([swappable.requirements]).

The exception for overloaded operators allows argument-dependent lookup in cases like that of ostream_iterator::operator=:

Effects: *out_stream << value; if (delim != 0) *out_stream << delim; return *this;

— end note]

157)157)

A valid C++ program always calls the expected library non-member function.

An implementation can also define additional non-member functions that would otherwise not be called by a valid C++ program.

16.4.6.5 Member functions [member.functions]

It is unspecified whether any member functions in the C++ standard library are defined as inline .

For a non-virtual member function described in the C++ standard library, an implementation may declare a different set of member function signatures, provided that any call to the member function that would select an overload from the set of declarations described in this document behaves as if that overload were selected.

[Note 1:

For instance, an implementation can add parameters with default values, or replace a member function with default arguments with two or more member functions with equivalent behavior, or add additional signatures for a member function name.

— end note]

16.4.6.6 Friend functions [hidden.friends]

Whenever this document specifies a friend declaration of a function or function template within a class or class template definition, that declaration shall be the only declaration of that function or function template provided by an implementation.

[Note 1:

In particular, a conforming implementation does not provide any additional declarations of that function or function template at namespace scope.

— end note]

[Note 2:

Such a friend function or function template declaration is known as a hidden friend, as it is visible neither to ordinary unqualified lookup ([basic.lookup.unqual]) nor to qualified lookup ([basic.lookup.qual]).

— end note]

16.4.6.7 Constexpr functions and constructors [constexpr.functions]

This document explicitly requires that certain standard library functions are constexpr ([dcl.constexpr]).

An implementation shall not declare any standard library function signature as constexpr except for those where it is explicitly required.

Within any header that provides any non-defining declarations of constexpr functions or constructors an implementation shall provide corresponding definitions.

16.4.6.8 Requirements for stable algorithms [algorithm.stable]

When the requirements for an algorithm state that it is “stable” without further elaboration, it means:

(1.1)
For the sort algorithms the relative order of equivalent elements is preserved.
(1.2)
For the remove and copy algorithms the relative order of the elements that are not removed is preserved.
(1.3)
For the merge algorithms, for equivalent elements in the original two ranges, the elements from the first range (preserving their original order) precede the elements from the second range (preserving their original order).

16.4.6.9 Reentrancy [reentrancy]

Except where explicitly specified in this document, it is implementation-defined which functions in the C++ standard library may be recursively reentered.

16.4.6.10 Data race avoidance [res.on.data.races]

This subclause specifies requirements that implementations shall meet to prevent data races .

Every standard library function shall meet each requirement unless otherwise specified.

Implementations may prevent data races in cases other than those specified below.

A C++ standard library function shall not directly or indirectly access objects ([intro.multithread]) accessible by threads other than the current thread unless the objects are accessed directly or indirectly via the function's arguments, including this.

A C++ standard library function shall not directly or indirectly modify objects ([intro.multithread]) accessible by threads other than the current thread unless the objects are accessed directly or indirectly via the function's non-const arguments, including this.

[Note 1:

This means, for example, that implementations can't use an object with static storage duration for internal purposes without synchronization because doing so can cause a data race even in programs that do not explicitly share objects between threads.

— end note]

A C++ standard library function shall not access objects indirectly accessible via its arguments or via elements of its container arguments except by invoking functions required by its specification on those container elements.

Operations on iterators obtained by calling a standard library container or string member function may access the underlying container, but shall not modify it.

[Note 2:

In particular, container operations that invalidate iterators conflict with operations on iterators associated with that container.

— end note]

Implementations may share their own internal objects between threads if the objects are not visible to users and are protected against data races.

Unless otherwise specified, C++ standard library functions shall perform all operations solely within the current thread if those operations have effects that are visible to users.

[Note 3:

This allows implementations to parallelize operations if there are no visible side effects.

— end note]

16.4.6.11 Protection within classes [protection.within.classes]

It is unspecified whether any function signature or class described in [support] through [exec] and [depr] is a friend of another class in the C++ standard library.

16.4.6.12 Derived classes [derivation]

An implementation may derive any class in the C++ standard library from a class with a name reserved to the implementation.

Certain classes defined in the C++ standard library are required to be derived from other classes in the C++ standard library.

An implementation may derive such a class directly from the required base or indirectly through a hierarchy of base classes with names reserved to the implementation.

In any case:

(3.1)
Every base class described as virtual shall be virtual;
(3.2)
Every base class not specified as virtual shall not be virtual;
(3.3)
Unless explicitly stated otherwise, types with distinct names shall be distinct types.
[Note 1:
There is an implicit exception to this rule for types that are described as synonyms ([dcl.typedef], [namespace.udecl]), such as size_t ([support.types]) and streamoff ([stream.types]).
— end note]

All types specified in the C++ standard library shall be non-final types unless otherwise specified.

16.4.6.13 Restrictions on exception handling [res.on.exception.handling]

Any of the functions defined in the C++ standard library can report a failure by throwing an exception of a type described in its Throws: paragraph, or of a type derived from a type named in the Throws: paragraph that would be caught by a handler ([except.handle]) for the base type.

Functions from the C standard library shall not throw exceptions 158 except when such a function calls a program-supplied function that throws an exception.159

Destructor operations defined in the C++ standard library shall not throw exceptions.

Every destructor in the C++ standard library shall behave as if it had a non-throwing exception specification ([except.spec]).

Functions defined in the C++ standard library that do not have a Throws: paragraph but do have a potentially-throwing exception specification may throw implementation-defined exceptions.160

Implementations should report errors by throwing exceptions of or derived from the standard exception classes ([bad.alloc], [support.exception], [std.exceptions]).

An implementation may strengthen the exception specification for a non-virtual function by adding a non-throwing exception specification.

158)158)

That is, the C standard library functions can all be treated as if they are marked noexcept.

This allows implementations to make performance optimizations based on the absence of exceptions at runtime.

159)159)

The functions qsort() and bsearch() ([alg.c.library]) meet this condition.

160)160)

In particular, they can report a failure to allocate storage by throwing an exception of type bad_alloc, or a class derived from bad_alloc ([bad.alloc]).

16.4.6.14 Value of error codes [value.error.codes]

Certain functions in the C++ standard library report errors via a std::error_code object.

That object's category() member shall return std::system_category() for errors originating from the operating system, or a reference to an implementation-defined error_category object for errors originating elsewhere.

The implementation shall define the possible values of value() for each of these error categories.

[Example 1:

For operating systems that are based on POSIX, implementations should define the std::system_category() values as identical to the POSIX errno values, with additional values as defined by the operating system's documentation.

Implementations for operating systems that are not based on POSIX should define values identical to the operating system's values.

For errors that do not originate from the operating system, the implementation may provide enums for the associated values.

— end example]

16.4.6.15 Moved-from state of library types [lib.types.movedfrom]

Objects of types defined in the C++ standard library may be moved from ([class.copy.ctor]).

Move operations may be explicitly specified or implicitly generated.

Unless otherwise specified, such moved-from objects shall be placed in a valid but unspecified state ([defns.valid]).

An object of a type defined in the C++ standard library may be move-assigned ([class.copy.assign]) to itself.

Unless otherwise specified, such an assignment places the object in a valid but unspecified state.

🔗 <ccomplex>	<codecvt>	<cstdbool>	<ctgmath>	<strstream>
🔗 <ciso646>	<cstdalign>