[library] (original) (raw)
16.1 General [library.general]
This Clause describes the contents of theC++ standard library, how a well-formed C++ program makes use of the library, and how a conforming implementation may provide the entities in the library.
The following subclauses describe the method of description ([description]) and organization ([organization]) of the library.
[requirements], [support]through [exec], and [depr] specify the contents of the library, as well as library requirements and constraints on both well-formed C++ programs and conforming implementations.
Detailed specifications for each of the components in the library are in[support]–[exec], as shown in Table 23.
The operating system interface described in ISO/IEC/IEEE 9945:2009 is hereinafter called POSIX.
The language support library ([support]) provides components that are required by certain parts of the C++ language, such as memory allocation ([expr.new], [expr.delete]) and exception processing ([except]).
The concepts library ([concepts]) describes library components that C++ programs may use to perform compile-time validation of template arguments and perform function dispatch based on properties of types.
The diagnostics library ([diagnostics]) provides a consistent framework for reporting errors in a C++ program, including predefined exception classes.
The memory management library ([mem]) provides components for memory management, including smart pointers and scoped allocators.
The metaprogramming library ([meta]) describes facilities for use in templates and during constant evaluation, including type traits, integer sequences, and rational arithmetic.
The general utilities library ([utilities]) includes components used by other library elements, such as a predefined storage allocator for dynamic storage management ([basic.stc.dynamic]), and components used as infrastructure in C++ programs, such as tuples and function wrappers.
The strings library ([strings]) provides support for manipulating sequences of type char, sequences of type char8_t, sequences of type char16_t, sequences of type char32_t, sequences of type wchar_t, and sequences of any other character-like type.
The text processing library ([text]) provides support for text processing, including formatting, internationalization support and regular expression matching and searching.
The numerics library provides numeric algorithms and complex number components that extend support for numeric processing.
Thevalarraycomponent provides support for_n_-at-a-time processing, potentially implemented as parallel operations on platforms that support such processing.
The random number component provides facilities for generating pseudo-random numbers.
The time library ([time]) provides generally useful time utilities.
The input/output library ([input.output]) provides theiostreamcomponents that are the primary mechanism for C++ program input and output.
They can be used with other elements of the library, particularly strings, locales, and iterators.
The concurrency support library ([thread]) provides components to create and manage threads, including atomic operations, mutual exclusion, and interthread communication.
The execution control library ([exec]) provides components supporting execution of function objects.
16.2 The C standard library [library.c]
The C++ standard library also makes available the facilities of the C standard library,suitably adjusted to ensure static type safety.
The descriptions of many library functions rely on the C standard library for the semantics of those functions.
In some cases, the signatures specified in this document may be different from the signatures in the C standard library, and additional overloads may be declared in this document, but the behavior and the preconditions (including any preconditions implied by the use of a C restrict qualifier) are the same unless otherwise stated.
A call to a C standard library function is a non-constant library call ([defns.nonconst.libcall]) if it raises a floating-point exception other than FE_INEXACT.
The semantics of a call to a C standard library function evaluated as a core constant expression are those specified in ISO/IEC 9899:2018, Annex F131to the extent applicable to the floating-point types ([basic.fundamental]) that are parameter types of the called function.
[Note 1:
ISO/IEC 9899:2018, Annex F specifies the conditions under which floating-point exceptions are raised and the behavior when NaNs and/or infinities are passed as arguments.
— _end note_]
[Note 2:
Equivalently, a call to a C standard library function is a non-constant library call if errno is set when math_errhandling & MATH_ERRNO is true.
— _end note_]
16.3 Method of description [description]
16.3.1 General [description.general]
Subclause [description] describes the conventions used to specify the C++ standard library.
[conventions] describes other editorial conventions.
16.3.2 Structure of each clause [structure]
16.3.2.1 Elements [structure.elements]
Each library clause contains the following elements, as applicable:132
- Summary
- Requirements
- Detailed specifications
- References to the C standard library
16.3.2.2 Summary [structure.summary]
The Summary provides a synopsis of the category, and introduces the first-level subclauses.
Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.
The contents of the summary and the detailed specifications include:
- macros
- values
- types and alias templates
- classes and class templates
- functions and function templates
- objects and variable templates
- concepts
16.3.2.3 Requirements [structure.requirements]
Requirements describe constraints that shall be met by a C++ program that extends the standard library.
Such extensions are generally one of the following:
- Template arguments
- Derived classes
- Containers, iterators, and algorithms that meet an interface convention or model a concept
The string and iostream components use an explicit representation of operations required of template arguments.
They use a class template char_traits to define these constraints.
Interface convention requirements are stated as generally as possible.
Instead of stating “class X has to define a member function operator++()”, the interface requires “for any object x of class X, ++x is defined”.
That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions that define valid terms of the types that meet the requirements.
For every set of well-defined expression requirements there is either a named concept or a table that specifies an initial set of the valid expressions and their semantics.
Any generic algorithm ([algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its template type parameters.
The library specification uses a typographical convention for naming requirements.
Names in italic type that begin with the prefix_Cpp17_ refer to sets of well-defined expression requirements typically presented in tabular form, possibly with additional prose semantic requirements.
For example, Cpp17Destructible (Table 35) is such a named requirement.
Names in constant width type refer to library concepts which are presented as a concept definition ([temp]), possibly with additional prose semantic requirements.
Template argument requirements are sometimes referenced by name.
In some cases the semantic requirements are presented as C++ code.
Such code is intended as a specification of equivalence of a construct to another construct, not necessarily as the way the construct must be implemented.133
Required operations of any concept defined in this document need not be total functions; that is, some arguments to a required operation may result in the required semantics failing to be met.
This does not affect whether a type models the concept.
A declaration may explicitly impose requirements through its associated constraints ([temp.constr.decl]).
When the associated constraints refer to a concept ([temp.concept]), the semantic constraints specified for that concept are additionally imposed on the use of the declaration.
16.3.2.4 Detailed specifications [structure.specifications]
The detailed specifications each contain the following elements:
- name and brief description
- synopsis (class definition or function declaration, as appropriate)
- restrictions on template arguments, if any
- description of class invariants
- description of function semantics
Descriptions of class member functions follow the order (as appropriate):134
- constructor(s) and destructor
- copying, moving & assignment functions
- comparison operator functions
- modifier functions
- observer functions
- operators and other non-member functions
Descriptions of function semantics contain the following elements (as appropriate):135
- Constraints: the conditions for the function's participation in overload resolution ([over.match]).
[Note 1:
Failure to meet such a condition results in the function's silent non-viability.
— end note_]
[_Example 1:
— _end example_] - Mandates: the conditions that, if not met, render the program ill-formed.
[Example 2:
If the diagnostic is to be emitted only after the function has been selected by overload resolution, an implementation can express such a condition via a constraint-expression ([temp.constr.decl]) and also define the function as deleted.
— _end example_] - Preconditions: conditions that the function assumes to hold whenever it is called; violation of any preconditions results in undefined behavior.
[Example 3:
An implementation can express some such conditions via the use of a contract assertion, such as a precondition assertion ([dcl.contract.func]).
— _end example_] - Hardened preconditions: conditions that the function assumes to hold whenever it is called.
- When invoking the function in a hardened implementation, prior to any other observable side effects of the function, one or more contract assertions whose predicates are as described in the hardened precondition are evaluated with a checking semantic ([basic.contract.eval]).
If any of these assertions is evaluated with a non-terminating semantic and the contract-violation handler returns, the program has undefined behavior. - When invoking the function in a non-hardened implementation, if any hardened precondition is violated, the program has undefined behavior.
- When invoking the function in a hardened implementation, prior to any other observable side effects of the function, one or more contract assertions whose predicates are as described in the hardened precondition are evaluated with a checking semantic ([basic.contract.eval]).
- Effects: the actions performed by the function.
- Synchronization: the synchronization operations ([intro.multithread]) applicable to the function.
- Postconditions: the conditions (sometimes termed observable results) established by the function.
[Example 4:
An implementation can express some such conditions via the use of a contract assertion, such as a postcondition assertion ([dcl.contract.func]).
— _end example_] - Result: for a typename-specifier, a description of the named type; for an expression, a description of the type and value category of the expression; the expression is an lvalue if the type is an lvalue reference type, an xvalue if the type is an rvalue reference type, and a prvalue otherwise.
- Returns: a description of the value(s) returned by the function.
- Throws: any exceptions thrown by the function, and the conditions that would cause the exception.
- Complexity: the time and/or space complexity of the function.
- Remarks: additional semantic constraints on the function.
- Error conditions: the error conditions for error codes reported by the function.
Whenever the Effects element specifies that the semantics of some functionF are Equivalent to some code sequence, then the various elements are interpreted as follows.
If F's semantics specifies any Constraints or Mandates elements, then those requirements are logically imposed prior to the equivalent-to semantics.
Next, the semantics of the code sequence are determined by the_Constraints_,Mandates,Preconditions,Hardened preconditions,Effects,Synchronization,Postconditions,Returns,Throws,Complexity,Remarks, and_Error conditions_specified for the function invocations contained in the code sequence.
The value returned from F is specified by F's Returns element, or if F has no Returns element, a non-void return from F is specified by thereturn statements ([stmt.return]) in the code sequence.
If F's semantics contains a Throws,Postconditions, or Complexity element, then that supersedes any occurrences of that element in the code sequence.
For non-reserved replacement and handler functions,[support] specifies two behaviors for the functions in question: their required and default behavior.
The default behaviordescribes a function definition provided by the implementation.
The required behaviordescribes the semantics of a function definition provided by either the implementation or a C++ program.
Where no distinction is explicitly made in the description, the behavior described is the required behavior.
If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations.136
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees meet the requirements.
Error conditions specify conditions where a function may fail.
The conditions are listed, together with a suitable explanation, as the enum class errcconstants ([syserr]).
16.3.3 Other conventions [conventions]
16.3.3.1 General [conventions.general]
Subclause [conventions] describes several editorial conventions used to describe the contents of the C++ standard library.
These conventions are for describingimplementation-defined types, and member functions.
16.3.3.2 Exposition-only entities, etc. [expos.only.entity]
The declaration of such an entity or typedef-nameis followed by a comment ending in exposition only.
The following are defined for exposition only to aid in the specification of the library:namespace std { template<class T> requires convertible_to<T, decay_t<T>> constexpr decay_t<T> decay-copy(T&& v) noexcept(is_nothrow_convertible_v<T, decay_t<T>>) { return std::forward<T>(v); } constexpr auto synth-three-way = []<class T, class U>(const T& t, const U& u) requires requires { { t < u } -> boolean-testable;{ u < t } -> boolean-testable;} { if constexpr (three_way_comparable_with<T, U>) { return t <=> u;} else { if (t < u) return weak_ordering::less;if (u < t) return weak_ordering::greater;return weak_ordering::equivalent;} };template<class T, class U=T> using synth-three-way-result = decltype(synth-three-way(declval<T&>(), declval<U&>()));}
An object dst is said to be decay-copied froma subexpression srcif the type of dst isdecay_t<decltype((src))>
16.3.3.3 Type descriptions [type.descriptions]
16.3.3.3.1 General [type.descriptions.general]
The Requirements subclauses may describe names that are used to specify constraints on template arguments.137
These names are used in library Clauses to describe the types that may be supplied as arguments by a C++ program when instantiating template components from the library.
Certain types defined in [input.output] are used to describe implementation-defined types.
They are based on other types, but with added constraints.
16.3.3.3.2 Enumerated types [enumerated.types]
Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.138
The enumerated type enumerated can be written:enum enumerated { , , , , … };inline const ();inline const ();inline const ();inline const (); ⋮
Here, the names ,, etc. representenumerated elementsfor this particular enumerated type.
All such elements have distinct values.
16.3.3.3.3 Bitmask types [bitmask.types]
Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as abitset.
The bitmask type bitmask can be written: enum bitmask : int_type { = 1 << 0, = 1 << 1, = 1 << 2, = 1 << 3, … };inline constexpr ();inline constexpr ();inline constexpr ();inline constexpr (); ⋮constexpr _bitmask_ operator&(_bitmask_ X, _bitmask_ Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) & static_cast<int_type>(Y));} constexpr bitmask operator|(bitmask X, bitmask Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) | static_cast<int_type>(Y));} constexpr bitmask operator^(bitmask X, bitmask Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) ^ static_cast<int_type>(Y));} constexpr bitmask operator~(bitmask X) { return static_cast<_bitmask_>(~static_cast<int_type>(X));} bitmask& operator&=(bitmask& X, bitmask Y) { X = X & Y; return X;} bitmask& operator|=(bitmask& X, bitmask Y) { X = X | Y; return X;} bitmask& operator^=(bitmask& X, bitmask Y) { X = X ^ Y; return X;}
Here, the names ,, etc. representbitmask elementsfor this particular bitmask type.
All such elements have distinct, nonzero values such that, for any pair and where i ≠ j, & is nonzero and & is zero.
Additionally, the value 0 is used to represent an empty bitmask, in which no bitmask elements are set.
The following terms apply to objects and values of bitmask types:
- To seta value Y in an object _X_is to evaluate the expression X |= Y.
- To cleara value Y in an object_X_ is to evaluate the expression X &= ~Y.
- The value Y is set in the object_X_ if the expression X & Y is nonzero.
16.3.3.3.4 Character sequences [character.seq]
16.3.3.3.4.1 General [character.seq.general]
The C standard library makes widespread useof characters and character sequences that follow a few uniform conventions:
- Properties specified as locale-specificmay change during program execution by a call to setlocale(int, const char*) ([clocale.syn]), or by a change to a locale object, as described in [locales] and [input.output].
- The execution character set and the execution wide-character setare supersets of the basic literal character set ([lex.charset]).
The encodings of the execution character sets and the sets of additional elements (if any) are locale-specific.
Each element of the execution wide-character set is encoded as a single code unit representable by a value of type wchar_t.
[Note 1:
The encodings of the execution character sets can be unrelated to any literal encoding.
— _end note_] - A letter is any of the 26 lowercase or 26uppercase letters in the basic character set.
- Thedecimal-point characteris the locale-specific (single-byte) character used by functions that convert between a (single-byte) character sequence and a value of one of the floating-point types.
It is used in the character sequence to denote the beginning of a fractional part.
It is represented in [support] through [exec]and [depr] by a period,'.', which is also its value in the "C"locale. - Acharacter sequenceis an array object A that can be declared as_T A_[N_], where T is any of the typeschar,unsigned char, orsigned char ([basic.fundamental]), optionally qualified by any combination ofconstorvolatile.
The initial elements of the array have defined contents up to and including an element determined by some predicate.
A character sequence can be designated by a pointer value_S that points to its first element.
16.3.3.3.4.2 Byte strings [byte.strings]
A null-terminated byte string, or ntbs, is a character sequence whose highest-addressed element with defined content has the value zero (the terminating null character); no other element in the sequence has the value zero.139
The length of an ntbsis the number of elements that precede the terminating null character.
An empty ntbshas a length of zero.
The value of an ntbsis the sequence of values of the elements up to and including the terminating null character.
A static ntbsis an ntbs with static storage duration.[140](#footnote-140 "A string-literal, such as "abc", is a static ntbs.")
16.3.3.3.4.3 Multibyte strings [multibyte.strings]
A multibyte character is a sequence of one or more bytes representing the code unit sequence for an encoded character of the execution character set.
A null-terminated multibyte string, or ntmbs, is an ntbs that constitutes a sequence of valid multibyte characters, beginning and ending in the initial shift state.141
A static ntmbsis an ntmbs with static storage duration.
16.3.3.3.5 Customization Point Object types [customization.point.object]
A customization point object is a function object ([function.objects]) with a literal class type that interacts with program-defined types while enforcing semantic requirements on that interaction.
All instances of a specific customization point object type shall be equal ([concepts.equality]).
The effects of invoking different instances of a specific customization point object type on the same arguments are equivalent.
The type T of a customization point object, ignoring cv-qualifiers, shall modelinvocable<T&, Args...>,invocable<const T&, Args...>,invocable<T, Args...>, andinvocable<const T, Args...> ([concept.invocable]) when the types in Args... meet the requirements specified in that customization point object's definition.
When the types of Args... do not meet the customization point object's requirements, T shall not have a function call operator that participates in overload resolution.
For a given customization point object o, let p be a variable initialized as if by auto p = o;.
Then for any sequence of arguments args..., the following expressions have effects equivalent to o(args...):
- p(args...)
- as_const(p)(args...)
- std::move(p)(args...)
- std::move(as_const(p))(args...)
16.3.3.4 Algorithm function objects [alg.func.obj]
An algorithm function object is a customization point object ([customization.point.object]) that is specified as one or more overloaded function templates.
The name of these function templates designates the corresponding algorithm function object.
For an algorithm function object o, let S be the corresponding set of function templates.
Then for any sequence of arguments args …,o(args …) is expression-equivalent tos(args …), where the result of name lookup for s is the overload set S.
[Note 1:
Algorithm function objects are not found by argument-dependent name lookup ([basic.lookup.argdep]).
[Example 1: void foo() { using namespace std::ranges; std::vector<int> vec{1,2,3}; find(begin(vec), end(vec), 2); }
The function call expression at #1 invokes std::ranges::find, not std::find.
— _end example_]
— _end note_]
16.3.3.5 Functions within classes [functions.within.classes]
For the sake of exposition, [support] through [exec]and [depr] do not describe copy/move constructors, assignment operators, or (non-virtual) destructors with the same apparent semantics as those that can be generated by default ([class.copy.ctor], [class.copy.assign], [class.dtor]).
It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default.
16.3.3.6 Private members [objects.within.classes]
An implementation may define static or non-static class members, or both, as needed to implement the semantics of the member functions specified in [support]through [exec] and [depr].
For the sake of exposition, some subclauses provide representative declarations, and semantic requirements, for private members of classes that meet the external specifications of the classes.
The declarations for such members are followed by a comment that ends with exposition only, as in:streambuf* sb;
An implementation may use any technique that provides equivalent observable behavior.
16.3.3.7 Freestanding items [freestanding.item]
A freestanding item is a declaration, entity, typedef-name, or macro that is required to be present in a freestanding implementation and a hosted implementation.
Unless otherwise specified, the requirements on freestanding items for a freestanding implementation are the same as the corresponding requirements for a hosted implementation, except that not all of the members of those items are required to be present.
Function declarations and function template declarations followed by a comment that include freestanding-deleted arefreestanding deleted functions.
On freestanding implementations, it is implementation-defined whether each entity introduced by a freestanding deleted function is a deleted function ([dcl.fct.def.delete]) or whether the requirements are the same as the corresponding requirements for a hosted implementation.
[Note 1:
Deleted definitions reduce the chance of overload resolution silently changing when migrating from a freestanding implementation to a hosted implementation.
— _end note_]
[Example 1: double abs(double j); — _end example_]
A declaration in a synopsis is a freestanding item if
- it is followed by a comment that includes freestanding,
- it is followed by a comment that includes freestanding-deleted, or
- the header synopsis begins with a comment that includes freestanding and the declaration is not followed by a comment that includes hosted.
[Note 2:
Declarations followed by hosted in freestanding headers are not freestanding items.
As a result, looking up the name of such functions can vary between hosted and freestanding implementations.
— _end note_]
[Example 2: namespace std { — _end example_]
An entity, deduction guide, or typedef-nameis a freestanding item if its introducing declaration is not followed by a comment that includes hosted, and is:
- introduced by a declaration that is a freestanding item,
- a member of a freestanding item other than a namespace,
- an enumerator of a freestanding item,
- a deduction guide of a freestanding item,
- an enclosing namespace of a freestanding item,
- a friend of a freestanding item,
- denoted by a typedef-name that is a freestanding item, or
- denoted by an alias template that is a freestanding item.
A macro is a freestanding item if it is defined in a header synopsis and
- the definition is followed by a comment that includes freestanding, or
- the header synopsis begins with a comment that includes freestanding and the definition is not followed by a comment that includes hosted.
[Example 3: #define NULL see below — _end example_]
[Note 3:
Freestanding annotations follow some additional exposition conventions that do not impose any additional normative requirements.
Header synopses that begin with a comment containing "all freestanding" contain no hosted items and no freestanding deleted functions.
Header synopses that begin with a comment containing "mostly freestanding" contain at least one hosted item or freestanding deleted function.
Classes and class templates followed by a comment containing "partially freestanding" contain at least one hosted item or freestanding deleted function.
— _end note_]
[Example 4: template<class T, size_t N> struct array; template<class T, size_t N> struct array { constexpr reference operator[](size_type n);constexpr const_reference operator[](size_type n) const;constexpr reference at(size_type n); constexpr const_reference at(size_type n) const; }; — _end example_]
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 exceptoperator newandoperator deleteare defined within the namespacestdor 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
Whenever an unqualified name other thanswap, make_error_code, make_error_condition,from_stream, orsubmdspan_mappingis used in the specification of a declaration Din [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_]
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_mappingare established as-if by performing argument-dependent lookup ([basic.lookup.argdep]).
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 stdthat 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 .
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 stdthat are provided by the C++ headers for C library facilities (Table 25), except the explicitly excluded declarations described in [support.c.headers.other] and
- declarations provided by the headers and .
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.
16.4.2.5 Freestanding implementations [compliance]
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.
A freestanding implementation has animplementation-defined set of headers.
This set shall include at least the headers shown in Table 27.
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.3 Linkage [using.linkage]
Unless otherwise specified, objects and functions have the defaultextern "C++"linkage ([dcl.link]).
Whether a name from the C standard library declared with external linkage hasextern "C"orextern "C++"linkage is implementation-defined.
It is recommended that an implementation useextern "C++"linkage for this purpose.150
Objects and functions defined in the library and required by a C++ program are included in the program prior to program startup.
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,
- T denotes an object or reference type to be supplied by a C++ program instantiating a template,
- a,b, andc denote values of type (possibly const) T,
- s and t denote modifiable lvalues of type T,
- u denotes an identifier,
- rv denotes an rvalue of type T, and
- 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]
| decltype(a == b) models boolean-testable | == is an equivalence relation, that is, it has the following properties:If a == b and b == c, then a == c. |
|---|
Table 30 — Cpp17DefaultConstructible requirements [tab:cpp17.defaultconstructible]
| object t is default-initialized |
|---|
| object u is value-initialized or aggregate-initialized |
| an object of type T is value-initialized or aggregate-initialized |
Table 31 — Cpp17MoveConstructible requirements [tab:cpp17.moveconstructible]
| u is equivalent to the value of rv before the construction |
|---|
| 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]
| the value of v is unchanged and is equivalent to u |
|---|
| 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 35 — Cpp17Destructible requirements [tab:cpp17.destructible]
| 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 udenote an expression of type U.
An object t is swappable with an object u if and only if
- the expressions swap(t, u) and swap(u, t) are valid when evaluated in the context described below, and
- these expressions have the following effects:
- the object referred to by t has the value originally held by u and
- 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:
- the two swap function templates defined in and
- 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 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) orstd::swap(u, t) as appropriate.
— _end note_]
[Note 2:
It is unspecified whether a library component that has a swappable requirement includes the header 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 objectx 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> template<class T, class U> void value_swap(T&& t, U&& u) { using std::swap; swap(std::forward<T>(t), std::forward<U>(u)); } template<class T> void lv_swap(T& t1, T& t2) { using std::swap; swap(t1, t2); } 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); } void swap(Proxy p, A& x) { swap(x, p); } } 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
- P meets the Cpp17EqualityComparable,Cpp17DefaultConstructible, Cpp17CopyConstructible, Cpp17CopyAssignable,Cpp17Swappable, and Cpp17Destructible requirements,
- the expressions shown in Table 36 are valid and have the indicated semantics, and
- 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_]
The effect shall be as if p != nullptrhad 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, tdenotes a non-const lvalue of type P, a and bdenote 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
- it is a function object type ([function.objects]),
- it meets the Cpp17CopyConstructible (Table 32) andCpp17Destructible (Table 35) requirements, and
- the expressions shown in Table 37are 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]
| 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(). |
|---|
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]), andmatch_results are parameterized in terms of allocators.
- T, U, C denote any cv-unqualified object type ([basic.types.general]),
- X denotes an allocator class for type T,
- Y denotes the corresponding allocator class for type U,
- XX denotes the type allocator_traits<X>,
- YY denotes the type allocator_traits<Y>,
- a, a1, a2 denote lvalues of type X,
- u denotes the name of a variable being declared,
- b denotes a value of type Y,
- c denotes a pointer of type C*through which indirection is valid,
- p denotes a value of type XX::pointerobtained by calling a1.allocate, where a1 == a,
- q denotes a value of type XX::const_pointerobtained by conversion from a value p,
- r denotes a value of type T&obtained by the expression *p,
- w denotes a value of type XX::void_pointerobtained by conversion from a value p,
- x denotes a value of type XX::const_void_pointerobtained by conversion from a value q or a value w,
- y denotes a value of type XX::const_void_pointerobtained by conversion from a result value of YY::allocate, or else a value of type (possibly const) std::nullptr_t,
- n denotes a value of type XX::size_type,
- Args denotes a template parameter pack, and
- 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_traitstemplate, 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::const_pointer
Mandates: XX::pointer is convertible to XX::const_pointer.
Remarks: Default: pointer_traits<XX::pointer>::rebind<const T>
typename X::void_pointertypename 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_pointertypename Y::const_void_pointer
Mandates: XX::pointer, XX::const_pointer, and XX::void_pointerare convertible to XX::const_void_pointer.
XX::const_void_pointer and YY::const_void_pointerare the same type.
Remarks: Default:pointer_traits<XX::pointer>::rebind<const void>
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
Postconditions: For all U (including T),YY::rebind_alloc<T> is X.
Remarks: If Allocator is a class template instantiation of the formSomeAllocator<T, Args>, where Args is zero or more type arguments, and Allocator does not supply a rebind member template, the standard allocator_traits template usesSomeAllocator<U, Args> in place of Allocator::rebind<U>::otherby 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>, thenAllocator::rebind<U>::other is the same type asSomeAllocator<U>, whereSomeAllocator<T>::value_type is T andSomeAllocator<U>::value_type is U.
— _end note_]
Postconditions: *q refers to the same object as *p.
Preconditions: (*p).m is well-defined.
Effects: Equivalent to (*p).m.
Preconditions: (*q).m is well-defined.
Effects: Equivalent to (*q).m.
static_cast<XX::pointer>(w)
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)
Postconditions: Same as p.
Effects: Memory is allocated for an array of n Tand 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.
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)
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 Tand 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}.
Preconditions:
- If p is memory that was obtained by a call to a.allocate_at_least, let ret be the value returned andreq be the value passed as the first argument of that call.
p is equal to ret.ptr andn is a value such thatreq ≤ n ≤ ret.count. - 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.
Returns: The largest value n that can meaningfully be passed to a.allocate(n).
Remarks: Default:numeric_limits<size_type>::max() / sizeof(value_type)
Returns: true only if storage allocated from each can be deallocated via the other.
Remarks: operator== shall be reflexive, symmetric, and transitive.
Returns: a == YY::rebind_alloc<T>(b).
Postconditions: Y(u) == b and u == X(b).
X u(std::move(a)); X u = std::move(a);
Postconditions: The value of a is unchanged and is equal to u.
Postconditions: u is equal to the prior value of X(b).
Effects: Constructs an object of type C at c.
Remarks: Default:construct_at(c, std::forward<Args>(args)...)
Effects: Destroys the object at c.
Remarks: Default: destroy_at(c)
a.select_on_container_copy_construction()
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) valuesa1, a2 of type X.
Remarks: Default: is_empty<X>::type
An allocator type X shall meet theCpp17CopyConstructible requirements (Table 32).
The XX::pointer, XX::const_pointer, XX::void_pointer, andXX::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) + nis true.
Let x1 and x2 denote objects of (possibly different) typesXX::void_pointer, XX::const_void_pointer, XX::pointer, or XX::const_pointer.
Then, x1 and x2 areequivalently-valued pointer values, if and only if both x1 and x2can be explicitly converted to the two corresponding objects px1 and px2of type XX::const_pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2evaluates to true.
Let w1 and w2 denote objects of type XX::void_pointer.
Then for the expressionsw1 == w2 w1 != w2either or both objects may be replaced by an equivalently-valued object of typeXX::const_void_pointer with no change in semantics.
Let p1 and p2 denote objects of type XX::pointer.
Then for the expressionsp1 == p2 p1 != p2 p1 < p2 p1 <= p2 p1 >= p2 p1 > p2 p1 - p2either or both objects may be replaced by an equivalently-valued object of typeXX::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 allocatefor that type can fail by throwing an object of typebad_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<U>& other); T* allocate(std::size_t n);void deallocate(T* p, std::size_t n);template<class U> bool operator==(const SimpleAllocator<U>& 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-allocatorif 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:
- X is a complete type, and
- all the member types of allocator_traits 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 namespacestdor to a namespace within namespacestd.
Unless explicitly prohibited, a program may add a template specialization for any standard library class template to namespacestd provided that
- the added declaration depends on at least one program-defined type, and
- the specialization meets the standard library requirements for the original template.151
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
- an explicit specialization of any member function of a standard library class template, or
- an explicit specialization of any member function template of a standard library class or class template, or
- an explicit or partial specialization of any member class template of a standard library class or class template, or
- 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
- depends on the name of at least one program-defined type, and
- 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.
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]).
16.4.5.2.2 Namespace posix [namespace.posix]
The behavior of a C++ program is undefined if it adds declarations or definitions to namespaceposixor to a namespace within namespaceposixunless 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 stdfollowed 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:
- macros
- global names
- 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:
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:
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 #undefnames 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 linkagein a header is reserved to the implementation to designate that library object with external linkage,152both in namespace std and in the global namespace.
Eachglobal function signature declared withexternal linkage in a header is reserved to the implementation to designate that function signature withexternal linkage.153
Each name from the C standard library declared with external linkageis reserved to the implementation for use as a name withextern "C"linkage, both in namespace std and in the global namespace.
Each function signature from the C standard library declared withexternal linkage is reserved to the implementation for use as a function signature with bothextern "C"andextern "C++"linkage,154or as a name of namespace scope in the global namespace.
16.4.5.3.5 Types [extern.types]
For each type T from the C standard library, the types::Tandstd::Tare reserved to the implementation and, when defined,::Tshall be identical tostd::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.5 Derived classes [derived.classes]
Virtual member function signatures definedfor a base class in the C++ standardlibrary may be overridden in a derived class defined in the program ([class.virtual]).
16.4.5.7 Handler functions [handler.functions]
The C++ standard library provides a default version of the following handler function ([support]):
- 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):
- set_new_handler
- 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:
- get_new_handler
- 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 sameset_* 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:
- For replacement functions ([replacement.functions]), if the installed replacement function does not implement the semantics of the applicable_Required behavior_: paragraph.
- For handler functions ([new.handler], [terminate.handler]), if the installed handler function does not implement the semantics of the applicable_Required behavior_: paragraph.
- Operations on such types can report a failure by throwing an exception unless otherwise specified.
- If any replacement function or handler function or destructor operation exits via an exception, unless specifically allowed in the applicable_Required behavior_: paragraph.
- 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 argumentsto functions defined in the C++ standard library,unless explicitly stated otherwise.
- If an argument to a function has an invalid value (suchas a value outside the domain of the function or a pointer invalid for its intended use), the behavior is undefined.
- 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.
- 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 lifetimedoes 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 tomodel a concept Cif Argssatisfies 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],
- 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],
- exceptions in [res.on.exception.handling], and
- contract assertions in [res.contract.assertions].
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 asinline.
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.155
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 ofostream_iterator::operator=:
Effects: *out_stream << value;if (delim != 0) *out_stream << delim;return *this;
— _end note_]
16.4.6.5 Member functions [member.functions]
It is unspecified whether any member functions in the C++ standard library are defined asinline.
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.7 Constexpr functions and constructors [constexpr.functions]
This document explicitly requires that certain standard library functions areconstexpr ([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:
- For the sort algorithms the relative order of equivalent elements is preserved.
- For the remove and copy algorithms the relative order of the elements that are not removed is preserved.
- 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 preventdata 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 arevisible to users.
[Note 3:
This allows implementations to parallelize operations if there are no visibleside effects.
— _end note_]
16.4.6.11 Properties of library classes [library.class.props]
Unless explicitly stated otherwise, it is unspecified whether any class described in [support] through [exec] and[depr] is a trivially copyable class, a standard-layout class, or an implicit-lifetime class ([class.prop]).
Unless explicitly stated otherwise, it is unspecified whether any class for which trivial relocation (i.e., the effects oftrivially_relocate ([obj.lifetime])) would be semantically equivalent to move-construction of the destination object followed by destruction of the source object is a trivially relocatable class ([class.prop]).
Unless explicitly stated otherwise, it is unspecified whether a class Cis a replaceable class ([class.prop]) if assigning an xvalue a of type C to an object b of type C is semantically equivalent to destroying b and then constructing from a inb's place.
16.4.6.13 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:
- Every base class described asvirtualshall be virtual;
- Every base class not specified asvirtual shall not be virtual;
- Unless explicitly stated otherwise, types with distinct names shall be distinct types.
All types specified in the C++ standard library shall be non-final types unless otherwise specified.
16.4.6.14 Restrictions on exception handling [res.on.exception.handling]
Any of the functions defined in the C++ standard librarycan 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 exceptions156except when such a function calls a program-supplied function that throws an exception.157
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 librarythat do not have a Throws: paragraph but do have a potentially-throwing exception specification may throw implementation-defined exceptions.158
An implementation may strengthen the exception specification for a non-virtual function by adding a non-throwing exception specification.
16.4.6.15 Contract assertions [res.contract.assertions]
Unless specified otherwise, an implementation may check the specified preconditions and postconditions of a function in the C++ standard library using contract assertions ([basic.contract], [structure.specifications]).
16.4.6.16 Value of error codes [value.error.codes]
Certain functions in the C++ standard library report errors via astd::error_code object.
That object'scategory() member shall return std::system_category() for errors originating from the operating system, or a reference to animplementation-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.17 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.