17 Library introduction [library]

17.1 General [library.general]

This Clause describes the contents of the C++ 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 definitions ([definitions]), method of description ([description]), and organization ([organization]) of the library. Clause [requirements], Clauses [language.support] through [thread], and Annex [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 Clauses [language.support][thread], as shown in Table [tab:library.categories].

Table 13 — Library categories
Clause Category
[language.support] Language support library
[diagnostics] Diagnostics library
[utilities] General utilities library
[strings] Strings library
[localization] Localization library
[containers] Containers library
[iterators] Iterators library
[algorithms] Algorithms library
[numerics] Numerics library
[input.output] Input/output library
[re] Regular expressions library
[atomics] Atomic operations library
[thread] Thread support library

The language support library (Clause [language.support]) provides components that are required by certain parts of the C++ language, such as memory allocation ([expr.new], [expr.delete]) and exception processing (Clause [except]).

The diagnostics library (Clause [diagnostics]) provides a consistent framework for reporting errors in a C++ program, including predefined exception classes.

The general utilities library (Clause [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 a tuples, function wrappers, and time facilities.

The strings library (Clause [strings]) provides support for manipulating text represented as sequences of type char, sequences of type char16_t, sequences of type char32_t, sequences of type wchar_t, and sequences of any other character-like type.

The localization library (Clause [localization]) provides extended internationalization support for text processing.

The containers (Clause [containers]), iterators (Clause [iterators]), and algorithms (Clause [algorithms]) libraries provide a C++ program with access to a subset of the most widely used algorithms and data structures.

The numerics library (Clause [numerics]) provides numeric algorithms and complex number components that extend support for numeric processing. The valarray component 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 input/output library (Clause [input.output]) provides the iostream components 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 regular expressions library (Clause [re]) provides regular expression matching and searching.

The atomic operations library (Clause [atomics]) allows more fine-grained concurrent access to shared data than is possible with locks.

The thread support library (Clause [thread]) provides components to create and manage threads, including mutual exclusion and interthread communication.

17.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 signatures and semantics of those functions. In all such cases, any use of the restrict qualifier shall be omitted.

17.3 Definitions [definitions]

17.3.1 arbitrary-positional stream [defns.arbitrary.stream]

a stream (described in Clause [input.output]) that can seek to any integral position within the length of the stream
Note: Every arbitrary-positional stream is also a repositional stream.  — end note ]

17.3.2 block [defns.block]

place a thread in the blocked state

17.3.3 blocked thread [defns.blocked]

a thread that is waiting for some condition (other than the availability of a processor) to be satisfied before it can continue execution160

This definition is taken from POSIX.

17.3.4 character [defns.character]

<Clauses [strings], [localization], [input.output], and [re]> any object which, when treated sequentially, can represent text
Note: The term does not mean only char, char16_t, char32_t, and wchar_t objects, but any value that can be represented by a type that provides the definitions specified in these Clauses.  — end note ]

17.3.5 character container type [defns.character.container]

a class or a type used to represent a character
Note: It is used for one of the template parameters of the string, iostream, and regular expression class templates. A character container type is a POD ([basic.types]) type.  — end note ]

17.3.6 comparison function [defns.comparison]

an operator function ([over.oper]) for any of the equality ([expr.eq]) or relational ([expr.rel]) operators

17.3.7 component [defns.component]

a group of library entities directly related as members, parameters, or return types
Note: For example, the class template basic_string and the non-member function templates that operate on strings are referred to as the string component.  — end note ]

17.3.8 deadlock [defns.deadlock]

one or more threads are unable to continue execution because each is blocked waiting for one or more of the others to satisfy some condition

17.3.9 default behavior [defns.default.behavior.impl]

<implementation> any specific behavior provided by the implementation, within the scope of the required behavior

17.3.10 default behavior [defns.default.behavior.func]

<specification> a description of replacement function and handler function semantics

17.3.11 handler function [defns.handler]

a non-reserved function whose definition may be provided by a C++ program
Note: A C++ program may designate a handler function at various points in its execution by supplying a pointer to the function when calling any of the library functions that install handler functions (Clause [language.support]).  — end note ]

17.3.12 iostream class templates [defns.iostream.templates]

templates, defined in Clause [input.output], that take two template arguments
Note: The arguments are named charT and traits. The argument charT is a character container class, and the argument traits is a class which defines additional characteristics and functions of the character type represented by charT necessary to implement the iostream class templates.  — end note ]

17.3.13 modifier function [defns.modifier]

a class member function ([class.mfct]) other than a constructor, assignment operator, or destructor that alters the state of an object of the class

17.3.14 move construction [defns.move.constr]

direct-initialization of an object of some type with an rvalue of the same type

17.3.15 move assignment [defns.move.assign]

assignment of an rvalue of some object type to a modifiable lvalue of the same type

17.3.16 object state [defns.obj.state]

the current value of all non-static class members of an object ([class.mem])
Note: The state of an object can be obtained by using one or more observer functions.  — end note ]

17.3.17 NTCTS [defns.ntcts]

a sequence of values that have character type that precede the terminating null character type value charT()

17.3.18 observer function [defns.observer]

a class member function ([class.mfct]) that accesses the state of an object of the class but does not alter that state
Note: Observer functions are specified as const member functions ([class.this]).  — end note ]

17.3.19 replacement function [defns.replacement]

a non-reserved function whose definition is provided by a C++ program
Note: Only one definition for such a function is in effect for the duration of the program's execution, as the result of creating the program ([lex.phases]) and resolving the definitions of all translation units ([basic.link]).  — end note ]

17.3.20 repositional stream [defns.repositional.stream]

a stream (described in Clause [input.output]) that can seek to a position that was previously encountered

17.3.21 required behavior [defns.required.behavior]

a description of replacement function and handler function semantics applicable to both the behavior provided by the implementation and the behavior of any such function definition in the program
Note: If such a function defined in a C++ program fails to meet the required behavior when it executes, the behavior is undefined.  — end note ]

17.3.22 reserved function [defns.reserved.function]

a function, specified as part of the C++ standard library, that must be defined by the implementation
Note: If a C++ program provides a definition for any reserved function, the results are undefined.  — end note ]

17.3.23 stable algorithm [defns.stable]

an algorithm that preserves, as appropriate to the particular algorithm, the order of elements
Note: Requirements for stable algorithms are given in [algorithm.stable].  — end note ]

17.3.24 traits class [defns.traits]

a class that encapsulates a set of types and functions necessary for class templates and function templates to manipulate objects of types for which they are instantiated
Note: Traits classes defined in Clauses [strings], [localization] and [input.output] are character traits, which provide the character handling support needed by the string and iostream classes.  — end note ]

17.3.25 unblock [defns.unblock]

place a thread in the unblocked state

17.3.26 valid but unspecified state [defns.valid]

an object state that is not specified except that the object's invariants are met and operations on the object behave as specified for its type
Example: If an object x of type std::vector<int> is in a valid but unspecified state, x.empty() can be called unconditionally, and x.front() can be called only if x.empty() returns false.  — end example ]

17.4 Additional definitions [defns.additional]

[intro.defs] defines additional terms used elsewhere in this International Standard.

17.5 Method of description (Informative) [description]

This subclause describes the conventions used to specify the C++ standard library. [structure] describes the structure of the normative Clauses [language.support] through [thread] and Annex [depr]. [conventions] describes other editorial conventions.

17.5.1 Structure of each clause [structure]

17.5.1.1 Elements [structure.elements]

Each library clause contains the following elements, as applicable:161

  • Summary

  • Requirements

  • Detailed specifications

  • References to the Standard C library

To save space, items that do not apply to a Clause are omitted. For example, if a Clause does not specify any requirements, there will be no “Requirements” subclause.

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

Paragraphs labeled “Note(s):” or “Example(s):” are informative, other paragraphs are normative.

The contents of the summary and the detailed specifications include:

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

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 satisfy the requirements. For every set of well-defined expression requirements there is a table that specifies an initial set of the valid expressions and their semantics. Any generic algorithm (Clause [algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its formal type parameters.

Template argument requirements are sometimes referenced by name. See [type.descriptions].

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

Although in some cases the code given is unambiguously the optimum implementation.

17.5.1.4 Detailed specifications [structure.specifications]

The detailed specifications each contain the following elements:

  • name and brief description

  • synopsis (class definition or function prototype, 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):163

  • constructor(s) and destructor

  • copying, moving & assignment functions

  • comparison functions

  • modifier functions

  • observer functions

  • operators and other non-member functions

Descriptions of function semantics contain the following elements (as appropriate):164

  • Requires: the preconditions for calling the function

  • Effects: the actions performed by the function

  • Synchronization: the synchronization operations ([intro.multithread]) applicable to the function

  • Postconditions: the observable results established by the function

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

  • Notes: non-normative comments about the function

Whenever the Effects: element specifies that the semantics of some function F are Equivalent to some code sequence, then the various elements are interpreted as follows. If F's semantics specifies a Requires: element, then that requirement is logically imposed prior to the equivalent-to semantics. Next, the semantics of the code sequence are determined by the Requires:, Effects:, Postconditions:, Returns:, Throws:, Complexity:, Remarks:, Error conditions:, and Notes: 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 the Returns: elements 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, Clause [language.support] specifies two behaviors for the functions in question: their required and default behavior. The default behavior describes a function definition provided by the implementation. The required behavior describes 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.165

Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.

Error conditions specify conditions where a function may fail. The conditions are listed, together with a suitable explanation, as the enum class errc constants ([syserr]).

To save space, items that do not apply to a class are omitted. For example, if a class does not specify any comparison functions, there will be no “Comparison functions” subclause.

To save space, items that do not apply to a function are omitted. For example, if a function does not specify any further preconditions, there will be no “Requires” paragraph.

This simplifies the presentation of complexity requirements in some cases.

17.5.1.5 C library [structure.see.also]

Paragraphs labeled “See also:” contain cross-references to the relevant portions of this International Standard and the ISO C standard, which is incorporated into this International Standard by reference.

17.5.2 Other conventions [conventions]

This subclause describes several editorial conventions used to describe the contents of the C++ standard library. These conventions are for describing implementation-defined types ([type.descriptions]), and member functions ([functions.within.classes]).

17.5.2.1 Type descriptions [type.descriptions]

17.5.2.1.1 General [type.descriptions.general]

The Requirements subclauses may describe names that are used to specify constraints on template arguments.166 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 Clause [input.output] are used to describe implementation-defined types. They are based on other types, but with added constraints.

Examples from [utility.requirements] include: EqualityComparable, LessThanComparable, CopyConstructible. Examples from [iterator.requirements] include: InputIterator, ForwardIterator, Function, Predicate.

17.5.2.1.2 Enumerated types [enumerated.types]

Several types defined in Clause [input.output] are enumerated types. Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.167

The enumerated type enumerated can be written:

enum enumerated { V0, V1, V2, V3, ..... };

static const enumerated C0 (V0);
static const enumerated C1 (V1);
static const enumerated C2 (V2);
static const enumerated C3 (V3);
  .....

Here, the names C0, C1, etc. represent enumerated elements for this particular enumerated type. All such elements have distinct values.

Such as an integer type, with constant integer values ([basic.fundamental]).

17.5.2.1.3 Bitmask types [bitmask.types]

Several types defined in Clauses [language.support] through [thread] and Annex [depr] are bitmask types. Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as a bitset ([template.bitset]).

The bitmask type bitmask can be written:

// For exposition only.
// int_type is an integral type capable of
// representing all values of the bitmask type.
enum bitmask : int_type {
  V0 = 1 << 0, V1 = 1 << 1, V2 = 1 << 2, V3 = 1 << 3, .....
};

constexpr bitmask C0(V0);
constexpr bitmask C1(V1);
constexpr bitmask C2(V2);
constexpr bitmask C3(V3);
  .....

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 C0, C1, etc. represent bitmask elements for this particular bitmask type. All such elements have distinct values such that, for any pair Ci and Cj, Ci & Ci is nonzero and Ci & Cj is zero.

The following terms apply to objects and values of bitmask types:

  • To set a value Y in an object X is to evaluate the expression X |= Y.

  • To clear a 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.

17.5.2.1.4 Character sequences [character.seq]

The C standard library makes widespread use of characters and character sequences that follow a few uniform conventions:

  • A letter is any of the 26 lowercase or 26 uppercase letters in the basic execution character set.168

  • The decimal-point character is the (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 Clauses [language.support] through [thread] and Annex [depr] by a period, '.', which is also its value in the "C" locale, but may change during program execution by a call to setlocale(int, const char*),169 or by a change to a locale object, as described in Clauses [locales] and [input.output].

  • A character sequence is an array object ([dcl.array]) A that can be declared as T A[N], where T is any of the types char, unsigned char, or signed char ([basic.fundamental]), optionally qualified by any combination of const or volatile. 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.

Note that this definition differs from the definition in ISO C 7.1.1.

declared in <clocale> ([c.locales]).

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

The length of an ntbs is the number of elements that precede the terminating null character. An empty ntbs has a length of zero.

The value of an ntbs is the sequence of values of the elements up to and including the terminating null character.

A static ntbs is an ntbs with static storage duration.171

Many of the objects manipulated by function signatures declared in <cstring> ([c.strings]) are character sequences or ntbss. The size of some of these character sequences is limited by a length value, maintained separately from the character sequence.

A string literal, such as "abc", is a static ntbs.

17.5.2.1.4.2 Multibyte strings [multibyte.strings]

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

A static ntmbs is an ntmbs with static storage duration.

An ntbs that contains characters only from the basic execution character set is also an ntmbs. Each multibyte character then consists of a single byte.

17.5.2.2 Functions within classes [functions.within.classes]

For the sake of exposition, Clauses [language.support] through [thread] and Annex [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.ctor], [class.dtor], [class.copy]).

It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default.

17.5.2.3 Private members [objects.within.classes]

Clauses [language.support] through [thread] and Annex [depr] do not specify the representation of classes, and intentionally omit specification of class members ([class.mem]). An implementation may define static or non-static class members, or both, as needed to implement the semantics of the member functions specified in Clauses [language.support] through [thread] and Annex [depr].

Objects of certain classes are sometimes required by the external specifications of their classes to store data, apparently in member objects. For the sake of exposition, some subclauses provide representative declarations, and semantic requirements, for private member objects of classes that meet the external specifications of the classes. The declarations for such member objects and the definitions of related member types are followed by a comment that ends with exposition only, as in:

streambuf* sb;  // exposition only

An implementation may use any technique that provides equivalent external behavior.

17.6 Library-wide requirements [requirements]

This subclause specifies requirements that apply to the entire C++ standard library. Clauses [language.support] through [thread] and Annex [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.

Within this subclause, [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.

17.6.1 Library contents and organization [organization]

[contents] describes the entities 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.

17.6.1.1 Library contents [contents]

The C++ standard library provides definitions for the following types of entities: macros, values, types, templates, classes, functions, objects.

All library entities except macros, operator new and operator delete are defined within the namespace std or namespaces nested within namespace std.173 It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace.174

Whenever a name x defined in the standard library is mentioned, the name x is assumed to be fully qualified as ::std::x, unless explicitly described otherwise. For example, if the Effects section for library function F is described as calling library function G, the function ::std::G is meant.

The C standard library headers (Annex [depr.c.headers]) also define names within the global namespace, while the C++ headers for C library facilities ([headers]) may also define names within the global namespace.

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

17.6.1.2 Headers [headers]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

17.6.1.3 Freestanding implementations [compliance]

Two kinds of implementations are defined: hosted and freestanding ([intro.compliance]). For a hosted implementation, this International Standard 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 [tab:cpp.headers.freestanding].

Table 16 — C++ headers for freestanding implementations
Subclause Header(s)
<ciso646>
[support.types] Types <cstddef>
[support.limits] Implementation properties <cfloat> <limits> <climits>
[cstdint] Integer types <cstdint>
[support.start.term] Start and termination <cstdlib>
[support.dynamic] Dynamic memory management <new>
[support.rtti] Type identification <typeinfo>
[support.exception] Exception handling <exception>
[support.initlist] Initializer lists <initializer_list>
[support.runtime] Other runtime support <cstdalign> <cstdarg> <cstdbool>
[meta] Type traits <type_traits>
[atomics] Atomics <atomic>

The supplied version of the header <cstdlib> shall declare at least the functions abort, atexit, at_quick_exit, exit, and quick_exit ([support.start.term]). The other headers listed in this table shall meet the same requirements as for a hosted implementation.

17.6.2 Using the library [using]

17.6.2.1 Overview [using.overview]

This section 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 ([lex.phases]).

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

A translation unit may include library headers in any order (Clause [lex]). 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.179

A translation unit shall include a header only outside of any external declaration or definition, and shall include the header lexically before the first reference in that translation unit to any of the entities declared in that header.

This is the same as the Standard C library.

17.6.2.3 Linkage [using.linkage]

Entities in the C++ standard library have external linkage ([basic.link]). 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.180

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

See also: replacement functions ([replacement.functions]), run-time changes ([handler.functions]).

The only reliable way to declare an object or function signature from the Standard C library is by including the header that declares it, notwithstanding the latitude granted in 7.1.7 of the C Standard.

17.6.3 Requirements on types and expressions [utility.requirements]

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

17.6.3.1 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 [equalitycomparable][destructible]. In these tables, T is an object or reference type to be supplied by a C++ program instantiating a template; a, b, and c are values of type (possibly const) T; s and t are modifiable lvalues of type T; u denotes an identifier; rv is an rvalue of type T; and v is 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 ([dcl.fct.default]).

Table 17EqualityComparable requirements
Expression Return type Requirement
a == b convertible to bool == 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 18LessThanComparable requirements
Expression Return type Requirement
a < b convertible to bool < is a strict weak ordering relation ([alg.sorting])

Table 19DefaultConstructible requirements
Expression Post-condition
T t; object t is default-initialized
T u{}; object u is value-initialized
T() a temporary object of type T is value-initialized
T{}

Table 20MoveConstructible requirements
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: 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 21CopyConstructible requirements (in addition to MoveConstructible)
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 22MoveAssignable requirements
Expression Return type Return value Post-condition
t = rv T& t t is equivalent to the value of rv before the assignment
rv's state is unspecified. [ Note: 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 23CopyAssignable requirements (in addition to MoveAssignable)
Expression Return type Return value Post-condition
t = v T& t t is equivalent to v, the value of v is unchanged

Table 24Destructible requirements
Expression Post-condition
u.~T() All resources owned by u are reclaimed, no exception is propagated.

17.6.3.2 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:

  • 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 ([over.match]) on a candidate set that includes:

Note: 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: 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 satisfying any of the iterator requirements ([iterator.requirements]) is ValueSwappable if, for any dereferenceable object x of type X, *x is swappable.

Example: User code can ensure that the evaluation of swap calls is performed in an appropriate context under the various conditions as follows:

#include <utility>

// Requires: std::forward<T>(t) shall be swappable with std::forward<U>(u).
template <class T, class U>
void value_swap(T&& t, U&& u) {
  using std::swap;
  swap(std::forward<T>(t), std::forward<U>(u)); // OK: uses “swappable with” conditions
                                                // for rvalues and lvalues
}

// Requires: lvalues of T shall be swappable.
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 ]

17.6.3.3 NullablePointer requirements [nullablepointer.requirements]

A NullablePointer type is a pointer-like type that supports null values. A type P meets the requirements of NullablePointer if:

  • P satisfies the requirements of EqualityComparable, DefaultConstructible, CopyConstructible, CopyAssignable, and Destructible,

  • lvalues of type P are swappable ([swappable.requirements]),

  • the expressions shown in Table [nullablepointer] are valid and have the indicated semantics, and

  • P satisfies 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 value. [ Note: Operations involving indeterminate values may cause undefined behavior.  — end note ]

An object p of type P can be contextually converted to bool (Clause [conv]). The effect shall be as if p != nullptr had been evaluated in place of p.

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

In Table [nullablepointer], 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 25NullablePointer requirements
Expression Return type Operational semantics
P u(np);
post: u == nullptr
P u = np;
P(np) post: P(np) == nullptr
t = np P& post: t == nullptr
a != b contextually convertible to bool !(a == b)
a == np contextually convertible to bool a == P()
np == a
a != np contextually convertible to bool !(a == np)
np != a

17.6.3.4 Hash requirements [hash.requirements]

A type H meets the Hash requirements if:

Given Key is an argument type for function objects of type H, in Table [hash] 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 26Hash requirements
Expression Return type Requirement
h(k) size_t The value returned shall depend only on the argument k. [ Note: Thus all evaluations of the expression h(k) with the same value for k yield the same result.  — end note ] [ 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().  — end note ]
h(u) size_t Shall not modify u.

17.6.3.5 Allocator requirements [allocator.requirements]

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 (Clause [strings]), containers (Clause [containers]) (except array), string buffers and string streams (Clause [input.output]), and match_results (Clause [re]) are parameterized in terms of allocators.

The template struct allocator_traits ([allocator.traits]) supplies a uniform interface to all allocator types. Table [tab:desc.var.def] describes the types manipulated through allocators. Table [tab:utilities.allocator.requirements] describes the requirements on allocator types and thus on types used to instantiate allocator_traits. A requirement is optional if the last column of Table [tab:utilities.allocator.requirements] specifies a default for a given expression. Within the standard library allocator_traits template, an optional requirement that is not supplied by an allocator is replaced by the specified default expression. A user specialization of allocator_traits may provide different defaults and may provide defaults for different requirements than the primary template. Within Tables [tab:desc.var.def] and [tab:utilities.allocator.requirements], the use of move and forward always refers to std::move and std::forward, respectively.

Table 27 — Descriptive variable definitions
VariableDefinition
T, U, C any non-const object type ([basic.types])
V a type convertible to T
X an Allocator class for type T
Y the corresponding Allocator class for type U
XX the type allocator_traits<X>
YY the type allocator_traits<Y>
t a value of type const T&
a, a1, a2 values of type X&
a3 an rvalue of type X
b a value of type Y
c a dereferenceable pointer of type C*
p a value of type XX::pointer, obtained by calling a1.allocate, where a1 == a
q a value of type XX::const_pointer obtained by conversion from a value p.
w a value of type XX::void_pointer obtained by conversion from a value p
z a value of type XX::const_void_pointer obtained by conversion from a value q or a value w
r a value of type T& obtained by the expression *p.
s a value of type const T& obtained by the expression *q or by conversion from a value r.
u a value of type YY::const_pointer obtained by calling YY::allocate, or else nullptr.
v a value of type V
n a value of type XX::size_type.
Args a template parameter pack
args a function parameter pack with the pattern Args&&
Table 28 — Allocator requirements
ExpressionReturn typeAssertion/noteDefault
pre-/post-condition
X::pointer T*
X::const_pointer X::pointer is convertible to X::const_pointer pointer_traits<X::pointer>::rebind<const T>
X::void_pointer
Y::void_pointer
X::pointer is convertible to X::void_pointer. X::void_pointer and Y::void_pointer are the same type. pointer_traits<X::pointer>::rebind<void>
X::const_void_pointer
Y::const_void_pointer
X::pointer, X::const_pointer, and X::void_pointer are convertible to X::const_void_pointer. X::const_void_pointer and Y::const_void_pointer are the same type. pointer_traits<X::pointer>::rebind<const void>
X::value_type Identical to T
X::size_type unsigned integer type a type that can represent the size of the largest object in the allocation model. make_unsigned<X::difference_type>::type
X::difference_type signed integer type a type that can represent the difference between any two pointers in the allocation model. pointer_traits<X::pointer>::difference_type
typename X::template rebind<U>::other Y For all U (including T), Y::template rebind<T>::other is X. See Note A, below.
*p T&
*q const T& *q refers to the same object as *p
p->m type of T::m pre: (*p).m is well-defined. equivalent to (*p).m
q->m type of T::m pre: (*q).m is well-defined. equivalent to (*q).m
static_- cast<X::pointer>(w) X::pointer static_cast<X::pointer>(w) == p
static_cast<X ::const_pointer>(z) X::const_pointer static_cast<X ::const_pointer>(z) == q
a.allocate(n) X::pointer Memory is allocated for n objects of type T but objects are not constructed. allocate may raise an appropriate exception.181Note: If n == 0, the return value is unspecified.  — end note ]
a.allocate(n, u) X::pointer Same as a.allocate(n). The use of u is unspecified, but it is intended as an aid to locality. a.allocate(n)
a.deallocate(p,n) (not used) All n T objects in the area pointed to by p shall be destroyed prior to this call. n shall match the value passed to allocate to obtain this memory. Does not throw exceptions. [ Note: p shall not be singular. — end note ]
a.max_size() X::size_type the largest value that can meaningfully be passed to X::allocate() numeric_limits<size_type>::max()
a1 == a2 bool returns true only if storage allocated from each can be deallocated via the other. operator== shall be reflexive, symmetric, and transitive, and shall not exit via an exception.
a1 != a2 bool same as !(a1 == a2)
a == b bool same as a == Y::rebind<T>::other(b)
a != b bool same as !(a == b)
X a1(a); Shall not exit via an exception.
post: a1 == a
X a(b); Shall not exit via an exception.
post: Y(a) == b, a == X(b)
X a1(move(a)); Shall not exit via an exception.
post: a1 equals the prior value of a.
X a(move(b)); Shall not exit via an exception.
post: a equals the prior value of X(b).
a.construct(c, args) (not used) Effect: Constructs an object of type C at c ::new ((void*)c) C(forward<Args>(args)...)
a.destroy(c) (not used) Effect: Destroys the object at c c->~C()
a.select_on_container_copy_construction() X Typically returns either a or X() return a;
X::propagate_on_container_copy_assignment Identical to or derived from true_type or false_type true_type only if an allocator of type X should be copied when the client container is copy-assigned. false_type
X::propagate_on_container_move_assignment Identical to or derived from true_type or false_type true_type only if an allocator of type X should be moved when the client container is move-assigned. false_type
X::propagate_on_- container_swap Identical to or derived from true_type or false_type true_type only if an allocator of type X should be swapped when the client container is swapped. false_type

Note A: The member class template rebind in the table above is effectively a typedef template. [ Note: In general, if the name Allocator is bound to SomeAllocator<T>, then Allocator::rebind<U>::other is the same type as SomeAllocator<U>, where SomeAllocator<T>::value_type is T and SomeAllocator<U>::value_type is U.  — end note ] 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<U>::other by default. For allocator types that are not template instantiations of the above form, no default is provided.

The X::pointer, X::const_pointer, X::void_pointer, and X::const_void_pointer types shall satisfy the requirements of NullablePointer ([nullablepointer.requirements]). No constructor, comparison operator, copy operation, move operation, or swap operation on these types shall exit via an exception. X::pointer and X::const_pointer shall also satisfy the requirements for a random access iterator ([iterator.requirements]).

An allocator may constrain the types on which it can be instantiated and the arguments for which its construct member may be called. If a type cannot be used with a particular allocator, the allocator class or the call to construct may fail to instantiate.

Example: the following is an allocator class template supporting the minimal interface that satisfies the requirements of Table [tab:utilities.allocator.requirements]:

template <class Tp>
struct SimpleAllocator {
  typedef Tp value_type;
  SimpleAllocator(ctor args);

  template <class T> SimpleAllocator(const SimpleAllocator<T>& other);

  Tp *allocate(std::size_t n);
  void deallocate(Tp *p, std::size_t n);
};

 — end example ]

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: Additionally, the member function allocate for that type may fail by throwing an object of type std::bad_alloc. — end note ]

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.

17.6.4 Constraints on programs [constraints]

17.6.4.1 Overview [constraints.overview]

This section 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 ([namespace.std]), its use of various reserved names ([reserved.names]), its use of headers ([alt.headers]), its use of standard library classes as base classes ([derived.classes]), its definitions of replacement functions ([replacement.functions]), and its installation of handler functions during execution ([handler.functions]).

17.6.4.2 Namespace use [namespace.constraints]

17.6.4.2.1 Namespace std [namespace.std]

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 otherwise specified. A program may add a template specialization for any standard library template to namespace std only if the declaration depends on a user-defined type and the specialization meets the standard library requirements for the original template and is not explicitly prohibited.182

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.

A program may explicitly instantiate a template defined in the standard library only if the declaration depends on the name of a user-defined type and the instantiation meets the standard library requirements for the original template.

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

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

17.6.4.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 9945 and other POSIX standards.

17.6.4.3 Reserved names [reserved.names]

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

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

17.6.4.3.1 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 [tab:identifiers.special], or to the attribute-tokens described in [dcl.attr].

17.6.4.3.2 Global names [global.names]

Certain sets of names and function signatures are always reserved to the implementation:

  • Each name that contains a double underscore __ or begins with an underscore followed by an uppercase letter ([lex.key]) is reserved to the implementation for any use.

  • Each name that begins with an underscore is reserved to the implementation for use as a name in the global namespace.

17.6.4.3.3 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,183 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. 184

Each name from the Standard C 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 Standard C library declared with external linkage is reserved to the implementation for use as a function signature with both extern "C" and extern "C++" linkage, 185 or as a name of namespace scope in the global namespace.

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

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

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.

17.6.4.3.4 Types [extern.types]

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

These types are clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mbstate_t, ptrdiff_t, sig_atomic_t, size_t, time_t, tm, va_list, wctrans_t, wctype_t, and wint_t.

17.6.4.3.5 User-defined literal suffixes [usrlit.suffix]

Literal suffix identifiers that do not start with an underscore are reserved for future standardization.

17.6.4.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 ([cpp.include]), the behavior is undefined.

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

17.6.4.6 Replacement functions [replacement.functions]

Clauses [language.support] through [thread] and Annex [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 ([definitions]).

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

  • operator new(std::size_t)

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

  • operator new[](std::size_t)

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

  • operator delete(void*)

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

  • operator delete[](void*)

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

The program's definitions are used instead of the default versions supplied by the implementation ([support.dynamic]). Such replacement occurs prior to program startup ([basic.def.odr], [basic.start]). The program's definitions shall not be specified as inline. No diagnostic is required.

17.6.4.7 Handler functions [handler.functions]

The C++ standard library provides default versions of the following handler functions (Clause [language.support]):

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

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

Calling the set_* and get_* functions shall not incur a data race. A call to any of the set_* functions shall synchronize with subsequent calls to the same set_* function and to the corresponding get_* function.

17.6.4.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, the Standard places no requirements on the implementation.

In particular, the effects are undefined in the following cases:

  • for replacement functions ([new.delete]), if the installed replacement function does not implement the semantics of the applicable Required behavior: paragraph.

  • for handler functions ([new.handler], [terminate.handler], [unexpected.handler]), if the installed handler function does not implement the semantics of the applicable Required behavior: paragraph

  • 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], [numeric.requirements]). 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]) is used as a template argument when instantiating a template component, unless specifically allowed for that component.

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

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

  • 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 binds to an rvalue reference parameter, the implementation may assume that this parameter is a unique reference to this argument. [ Note: If the parameter is a generic parameter of the form T&& and an lvalue of type A is bound, the argument binds to an lvalue reference ([temp.deduct.call]) and thus is not covered by the previous sentence.  — end note ] [ Note: 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 move(x)), the program is effectively asking that function to treat that lvalue as a temporary. The implementation is free to optimize away aliasing checks which might be needed if the argument was an lvalue.  — end note ]

17.6.4.10 Shared objects and the library [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: 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 sharable without data races or the user supplies a locking mechanism.  — end note ]

Note: In particular, the program is required to ensure that completion of the constructor of any object of a class type defined in the standard library happens before any other member function invocation on that object and, unless otherwise specified, to ensure that completion of any member function invocation other than destruction on such an object happens before destruction of that object. This applies even to objects such as mutexes intended for thread synchronization.  — end note ]

17.6.4.11 Requires paragraph [res.on.required]

Violation of the preconditions specified in a function's Requires: paragraph results in undefined behavior unless the function's Throws: paragraph specifies throwing an exception when the precondition is violated.

17.6.5 Conforming implementations [conforming]

17.6.5.1 Overview [conforming.overview]

This section 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], global 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].

17.6.5.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 headers ([depr.c.headers]) shall include only their corresponding C++ standard header, as described in [headers].

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

17.6.5.4 Global and non-member functions [global.functions]

It is unspecified whether any global or non-member functions in the C++ standard library are defined as inline ([dcl.fct.spec]).

A call to a global or non-member function signature described in Clauses [language.support] through [thread] and Annex [depr] shall behave as if the implementation declared no additional global or non-member function signatures.187

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

Unless otherwise specified, global and non-member functions in the standard library shall not use functions from another namespace which are found through argument-dependent name lookup ([basic.lookup.argdep]). [ Note: The phrase “unless otherwise specified” is intended to allow argument-dependent lookup in cases like that of ostream_iterators: Effects:

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

 — end note ]

A valid C++ program always calls the expected library global or non-member function. An implementation may also define additional global or non-member functions that would otherwise not be called by a valid C++ program.

17.6.5.5 Member functions [member.functions]

It is unspecified whether any member functions in the C++ standard library are defined as inline ([dcl.fct.spec]).

An implementation may declare additional non-virtual member function signatures within a class:

  • by adding arguments with default values to a member function signature;188Note: An implementation may not add arguments with default values to virtual, global, or non-member functions. — end note ]

  • by replacing a member function signature with default values by two or more member function signatures with equivalent behavior; and

  • by adding a member function signature for a member function name.

A call to a member function signature described in the C++ standard library behaves as if the implementation declares no additional member function signatures.189

Hence, the address of a member function of a class in the C++ standard library has an unspecified type.

A valid C++ program always calls the expected library member function, or one with equivalent behavior. An implementation may also define additional member functions that would otherwise not be called by a valid C++ program.

17.6.5.6 constexpr functions and constructors [constexpr.functions]

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

17.6.5.7 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 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 precede the elements from the second range.

17.6.5.8 Reentrancy [reentrancy]

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

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

This section specifies requirements that implementations shall meet to prevent data races ([intro.multithread]). 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: This means, for example, that implementations can't use a static object for internal purposes without synchronization because it could 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: 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 ([intro.multithread]) to users.

Note: This allows implementations to parallelize operations if there are no visible side effects.  — end note ]

17.6.5.10 Protection within classes [protection.within.classes]

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

17.6.5.11 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 as virtual shall be virtual;

  • Every base class described as non-virtual shall not be virtual;

  • Unless explicitly stated otherwise, types with distinct names shall be distinct types.190

There is an implicit exception to this rule for types that are described as synonyms for basic integral types, such as size_t ([support.types]) and streamoff ([stream.types]).

17.6.5.12 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. An implementation may strengthen the exception-specification for a non-virtual function by adding a non-throwing noexcept-specification.

A function may throw an object of a type not listed in its Throws clause if its type is derived from a type named in the Throws clause and would be caught by an exception handler for the base type.

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

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. Any other functions defined in the C++ standard library that do not have an exception-specification may throw implementation-defined exceptions unless otherwise specified.193 An implementation may strengthen this implicit exception-specification by adding an explicit one.194

That is, the C 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.

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

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]). Library implementations should report errors by throwing exceptions of or derived from the standard exception classes ([bad.alloc], [support.exception], [std.exceptions]).

That is, an implementation may provide an explicit exception-specification that defines the subset of “any” exceptions thrown by that function. This implies that the implementation may list implementation-defined types in such an exception-specification.

17.6.5.13 Restrictions on storage of pointers [res.on.pointer.storage]

Objects constructed by the standard library that may hold a user-supplied pointer value or an integer of type std::intptr_t shall store such values in a traceable pointer location ([basic.stc.dynamic.safety]). [ Note: Other libraries are strongly encouraged to do the same, since not doing so may result in accidental use of pointers that are not safely derived. Libraries that store pointers outside the user's address space should make it appear that they are stored and retrieved from a traceable pointer location.  — end note ]

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

Certain functions in the C++ standard library report errors via a std::error_code ([syserr.errcode.overview]) 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: For operating systems that are based on POSIX, implementations are encouraged to 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 are encouraged to 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 ]

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