Working Draft, Standard for Programming Language C++ (N4713, 2017 year)

(3.4)

—

Postconditions: the observable results established by the function

(3.5)

—

Returns: a description of the value(s) returned by the function

(3.6)

—

Throws: any exceptions thrown by the function, and the conditions that would cause the exception

(3.7)

—

Complexity: the time and/or space complexity of the function

(3.8)

—

Remarks: additional semantic constraints on the function

(3.9)

—

Error conditions: the error conditions for error codes reported by 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, 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 the return statements 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 21 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.¹⁶²

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

20.4.1.5

C library

[structure.see.also]

Paragraphs labeled “See also” contain cross-references to the relevant portions of the ISO C standard.

20.4.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 (20.4.2.1), and member functions (20.4.2.2).

20.4.2.1

Type descriptions

[type.descriptions]

20.4.2.1.1

General

[type.descriptions.general]

The Requirements subclauses may describe names that are used to specify constraints on template argu-

ments.¹⁶³ 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 30 are used to describe implementation-defined types. They are based on

other types, but with added constraints.

20.4.2.1.2

Exposition-only types

[expos.only.types]

Several types defined in Clause 21 through Clause 33 and Annex D that are used as function parameter or

return types are defined for the purpose of exposition only in order to capture their language linkage. The

declarations of such types are followed by a comment ending in exposition only. [ Example:

namespace std {

extern "C" using some-handler = int(int, void*, double);

// exposition only

}

The type placeholder some-handler can now be used to specify a function that takes a callback parameter

with C language linkage.

— end example ]

162) This simplifies the presentation of complexity requirements in some cases.

163) Examples from 20.5.3 include: EqualityComparable, LessThanComparable, CopyConstructible. Examples from 27.2 include:

InputIterator, ForwardIterator.

§ 20.4.2.1.2

412

20.4.2.1.3

Enumerated types

[enumerated.types]

Several types defined in Clause 30 are enumerated types. Each enumerated type may be implemented as an

enumeration or as a synonym for an enumeration.¹⁶⁴

The enumerated type enumerated can be written:

enum enumerated

{ V0, V1, V2, V3,

};

inline const enumerated C 0(V 0);

inline const enumerated C 1(V 1);

inline const enumerated C 2(V 2);

inline const enumerated C 3(V 3);

Here, the names C₀, C₁, etc. represent enumerated elements for this particular enumerated type. All such

elements have distinct values.

20.4.2.1.4

Bitmask types

[bitmask.types]

Several types defined in Clause 21 through Clause 33 and Annex D 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 (23.9.2).

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,

};

inline constexpr bitmask C 0(V 0);

inline constexpr bitmask C 1(V 1);

inline constexpr bitmask C 2(V 2);

inline constexpr bitmask C 3(V 3);

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 C₀, C₁, etc. represent bitmask elements for this particular bitmask type. All such elements

have distinct, nonzero values such that, for any pair C_i and C_j where i = j, C_i & C_i is nonzero and C_i & C_j

is zero. Additionally, the value 0 is used to represent an empty bitmask, in which no bitmask elements are set.

164) Such as an integer type, with constant integer values (6.7.1).

§ 20.4.2.1.4

413

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

(4.1)

—

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

(4.2)

—

To clear a value Y in an object X is to evaluate the expression X &= ~Y.

(4.3)

—

The value Y is set in the object X if the expression X & Y is nonzero.

20.4.2.1.5

Character sequences

[character.seq]

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

conventions:

(1.1)

—

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

(1.2)

—

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 Clause 21 through Clause

33 and Annex D 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*),¹⁶⁵ or by a change to a locale object,

as described in 25.3 and Clause 30.

—

(1.3)

A character sequence is an array object (11.3.4) A that can be declared as T A[N ], where T is any of

the types char, unsigned char, or signed char (6.7.1), 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.

20.4.2.1.5.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.¹⁶⁶

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.¹⁶⁷

20.4.2.1.5.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.¹⁶⁸

A static ntmbs is an ntmbs with static storage duration.

20.4.2.2

Functions within classes

[functions.within.classes]

For the sake of exposition, Clause 21 through Clause 33 and Annex D 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 (15.1, 15.4, 15.8). It is unspecified whether the implementation provides explicit

definitions for such member function signatures, or for virtual destructors that can be generated by default.

For the sake of exposition, the library clauses sometimes annotate constructors with EXPLICIT. Such a

constructor is conditionally declared as either explicit or non-explicit (15.3.1).

[Note: This is typically

implemented by declaring two such constructors, of which at most one participates in overload resolution.

— end note ]

165) declared in <clocale> (25.5).

166) Many of the objects manipulated by function signatures declared in <cstring> (24.5) 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.

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

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

§ 20.4.2.2

414

20.4.2.3

Operators

[operators]

In this library, whenever a declaration is provided for an operator!=, operator>, operator>=, or operator<=

for a type T, its requirements and semantics are as follows, unless explicitly specified otherwise.

bool operator!=(const T& x, const T& y);

Requires: Type T is EqualityComparable (Table 20).

Returns: !(x == y).

bool operator>(const T& x, const T& y);

Requires: Type T is LessThanComparable (Table 21).

Returns: y < x.

bool operator<=(const T& x, const T& y);

Requires: Type T is LessThanComparable (Table 21).

Returns: !(y < x).

bool operator>=(const T& x, const T& y);

Requires: Type T is LessThanComparable (Table 21).

Returns: !(x < y).

20.4.2.4

Private members

[objects.within.classes]

Clause 21 through Clause 33 and Annex D do not specify the representation of classes, and intentionally omit

specification of class members (12.2). An implementation may define static or non-static class members, or

both, as needed to implement the semantics of the member functions specified in Clause 21 through Clause

33 and Annex D.

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;

// exposition only

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

20.5

Library-wide requirements

[requirements]

This subclause specifies requirements that apply to the entire C++ standard library. Clause 21 through

Clause 33 and Annex D 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, 20.5.1 describes the library’s contents and organization, 20.5.2 describes how well-

formed C++ programs gain access to library entities, 20.5.3 describes constraints on types and functions

used with the C++ standard library, 20.5.4 describes constraints on well-formed C++ programs, and 20.5.5

describes constraints on conforming implementations.

20.5.1

Library contents and organization

[organization]

20.5.1.1 describes the entities and macros defined in the C++ standard library. 20.5.1.2 lists the standard library

headers and some constraints on those headers. 20.5.1.3 lists requirements for a freestanding implementation

of the C++ standard library.

20.5.1.1

Library contents

[contents]

The C++ standard library provides definitions for the entities and macros described in the synopses of the

C++ standard library headers (20.5.1.2).

All library entities except operator new and operator delete are defined within the namespace std or

namespaces nested within namespace std.¹⁶⁹ It is unspecified whether names declared in a specific namespace

are declared directly in that namespace or in an inline namespace inside that namespace.¹⁷⁰

169) The C standard library headers (D.5) also define names within the global namespace, while the C++ headers for C library

facilities (20.5.1.2) may also define names within the global namespace.

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

§ 20.5.1.1

415

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: element for library function F

is described as calling library function G, the function ::std::G is meant.

20.5.1.2

Headers

[headers]

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

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

Table 16 — C++ library headers

<mutex>

<any>

<new>

<string_view>

<array>

<initializer_list>

<system_error>

<ios>

<queue>

<tuple>

<ratio>

<type_traits>

<regex>

<scoped_allocator>

<condition_variable>

<set>

<unordered_map>

<deque>

<list>

<shared_mutex>

<unordered_set>

<map>

<stack>

<forward_list>

<memory_resource>

The facilities of the C standard library are provided in the additional headers shown in Table 17.¹⁷²

Table 17 — C++ headers for C library facilities

<cfenv>

<cmath>

<ctime>

Except as noted in Clause 20 through Clause 33 and Annex D, the contents of each header cname

the

same as that of the corresponding header name.h as specified in the C standard library (Clause 2). In the

C++ standard library, however, the declarations (except for names which are defined as macros in C) are

within namespace scope (6.3.6) of the namespace std. It is unspecified whether these names (including any

overloads added in Clause 21 through Clause 33 and Annex D) are first declared within the global namespace

scope and are then injected into namespace std by explicit using-declarations (10.3.3).

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.¹⁷³

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

headers.¹⁷⁴

171) A header is not necessarily a source file, nor are the sequences delimited by < and > in header names necessarily valid source

file names (19.2).

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

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

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

§ 20.5.1.2

416

D.5, C standard library headers, describes the effects of using the name.h (C header) form in a C++ program.¹⁷⁵

Annex K of the C standard describes a large number of functions, with associated types and macros, which

“promote safer, more secure programming” than many of the traditional C library functions. The names of

the functions have a suffix of _s; most of them provide the same service as the C library function with the

unsuffixed name, but generally take an additional argument whose value is the size of the result array. If any

C++ header is included, it is implementation-defined whether any of these names is declared in the global

namespace. (None of them is declared in namespace std.)

Table 18 lists the Annex K names that may be declared in some header. These names are also subject to the

restrictions of 20.5.4.3.2.

Table 18 — C standard Annex K names

abort_handler_s

mbstowcs_s

strncat_s

vswscanf_s

asctime_s

memcpy_s

strncpy_s

vwprintf_s

bsearch_s

memmove_s

strtok_s

vwscanf_s

constraint_handler_t

memset_s

swprintf_s

wcrtomb_s

ctime_s

printf_s

swscanf_s

wcscat_s

errno_t

qsort_s

tmpfile_s

wcscpy_s

fopen_s

RSIZE_MAX

TMP_MAX_S

wcsncat_s

fprintf_s

rsize_t

tmpnam_s

wcsncpy_s

freopen_s

scanf_s

vfprintf_s

wcsnlen_s

fscanf_s

set_constraint_handler_s

vfscanf_s

wcsrtombs_s

fwprintf_s

snprintf_s

vfwprintf_s

wcstok_s

fwscanf_s

snwprintf_s

vfwscanf_s

wcstombs_s

getenv_s

sprintf_s

vprintf_s

wctomb_s

gets_s

sscanf_s

vscanf_s

wmemcpy_s

gmtime_s

strcat_s

vsnprintf_s

wmemmove_s

ignore_handler_s

strcpy_s

vsnwprintf_s

wprintf_s

L_tmpnam_s

strerror_s

vsprintf_s

wscanf_s

localtime_s

strerrorlen_s

vsscanf_s

mbsrtowcs_s

strlen_s

vswprintf_s

20.5.1.3

Freestanding implementations

[compliance]

Two kinds of implementations are defined: hosted and freestanding (4.1). For a hosted implementation, this

document describes the set of available headers.

A freestanding implementation has an implementation-defined set of headers. This set shall include at least

the headers shown in Table 19.

The supplied version of the header <cstdlib> shall declare at least the functions abort, atexit, at_quick_-

exit, exit, and quick_exit (21.5). The other headers listed in this table shall meet the same requirements

as for a hosted implementation.

20.5.2

Using the library

[using]

20.5.2.1

Overview

[using.overview]

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

20.5.2.2 describes effects during translation phase 4, while 20.5.2.3 describes effects during phase 8 (5.2).

20.5.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 (19.2).

A translation unit may include library headers in any order (Clause 5). 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.¹⁷⁶

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

176) This is the same as the C standard library.

§ 20.5.2.2

417

Table 19 — C++ headers for freestanding implementations

Subclause

Header(s)

21.2

Types

21.3

Implementation properties

21.4

Integer types

21.5

Start and termination

21.6

Dynamic memory management

<new>

21.7

Type identification

21.8

Exception handling

21.9

Initializer lists

<initializer_list>

21.11

Other runtime support

23.15

Type traits

<type_traits>

Clause 32

Atomics

D.4.2, D.4.3

Deprecated headers

A translation unit shall include a header only outside of any 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.

No diagnostic is required.

20.5.2.3

Linkage

[using.linkage]

Entities in the C++ standard library have external linkage (6.5). Unless otherwise specified, objects and

functions have the default extern "C++" linkage (10.5).

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

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 (20.5.4.6), runtime changes (20.5.4.7).

20.5.3

Requirements on types and expressions

[utility.requirements]

20.5.3.1 describes requirements on types and expressions used to instantiate templates defined in the C++

standard library. 20.5.3.2 describes the requirements on swappable types and swappable expressions. 20.5.3.3

describes the requirements on pointer-like types that support null values. 20.5.3.4 describes the requirements

on hash function objects. 20.5.3.5 describes the requirements on storage allocators.

20.5.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 20-27. 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 (11.6) if one of those signatures is called

using the default argument (11.3.6).

177) The only reliable way to declare an object or function signature from the C standard library is by including the header that

declares it, notwithstanding the latitude granted in 7.1.4 of the C Standard.

§ 20.5.3.1

418

Table 20 — EqualityComparable requirements

Expression

Return type

Requirement

a == b

convertible to

== is an equivalence relation, that is, it has the

bool

following properties:

— For all a, a == a.

— If a == b, then b == a.

— If a == b and b == c, then a == c.

Table 21 — LessThanComparable requirements

Expression

Return type

Requirement

a < b

convertible to

< is a strict weak ordering relation (28.7)

bool

Table 22 — DefaultConstructible requirements

Expression

Post-condition

T t;

object t is default-initialized

T u{};

object u is value-initialized or aggregate-initialized

T()

an object of type T is value-initialized or aggregate-

T{}

initialized

Table 23 — MoveConstructible 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 24 — CopyConstructible 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 25 — MoveAssignable requirements

Expression

Return type

Return value Post-condition

t = rv

If t and rv do not refer to the

same object, t is equivalent to

the value of rv before the assign-

ment

rv’s state is unspecified.

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

§ 20.5.3.1

419

Table 26 — CopyAssignable requirements (in addition to MoveAssignable)

Expression

Return type

Return value Post-condition

t = v

t is equivalent to v, the value of

v is unchanged

Table 27 — Destructible requirements

Expression

Post-condition

u.~T()

All resources owned by u are reclaimed, no exception is propagated.

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

(2.1)

—

the expressions swap(t, u) and swap(u, t) are valid when evaluated in the context described below,

and

(2.2)

—

these expressions have the following effects:

(2.2.1)

—

the object referred to by t has the value originally held by u and

(2.2.2)

—

the object referred to by u has the value originally held by t.

The context in which swap(t, u) and swap(u, t) are evaluated shall ensure that a binary non-member

function named “swap” is selected via overload resolution (16.3) on a candidate set that includes:

(3.1)

—

the two swap function templates defined in <utility> (23.2) and

(3.2)

—

the lookup set produced by argument-dependent lookup (6.4.2).

[ 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 (27.2) satisfies the requirements of 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).

template<class T, class U>

void value_swap(T&& t, U&& u) {

using std::swap;

swap(std::forward<T>(t), std::forward(u)); // OK: uses “swappable with” conditions

// for rvalues and lvalues

}

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

}

§ 20.5.3.2

420

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 ]

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

(1.1)

—

P satisfies the requirements of EqualityComparable, DefaultConstructible, CopyConstructible,

CopyAssignable, and Destructible,

(1.2)

—

lvalues of type P are swappable (20.5.3.2),

(1.3)

—

the expressions shown in Table 28 are valid and have the indicated semantics, and

(1.4)

—

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 7). 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 28, 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 28 — NullablePointer requirements

Expression Return type

Operational semantics

P u(np);

Postconditions: u == nullptr

P u = np;

P(np)

Postconditions: P(np) == nullptr

t = np

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

20.5.3.4

Hash requirements

[hash.requirements]

A type H meets the Hash requirements if:

§ 20.5.3.4

421

(1.1)

—

it is a function object type (23.14),

(1.2)

—

it satisfies the requirements of CopyConstructible and Destructible (20.5.3.1), and

(1.3)

—

the expressions shown in Table 29 are valid and have the indicated semantics.

Given Key is an argument type for function objects of type H, in Table 29 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 29 — Hash requirements

Expression Return type Requirement

h(k)

size_t

The value returned shall depend only on the argument k for

the duration of the program. [ Note: 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 ]

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

20.5.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 24), containers (Clause 26) (except array),

string buffers and string streams (Clause 30), and match_results (Clause 31) are parameterized in terms of

allocators.

The class template allocator_traits (23.10.9) supplies a uniform interface to all allocator types. Table 30

describes the types manipulated through allocators. Table 31 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 31 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 30 and 31, the use of move and forward

always refers to std::move and std::forward, respectively.

Table 30 — Descriptive variable definitions

Variable

Definition

T, U, C

any cv-unqualified object type (6.7)

an Allocator class for type T

the corresponding Allocator class for type U

the type allocator_traits<X>

the type allocator_traits<Y>

a, a1, a2

lvalues of type X

the name of a variable being declared

a value of type Y

a pointer of type C* through which indirection is valid

a value of type XX::pointer, obtained by calling

a1.allocate, where a1 == a

a value of type XX::const_pointer obtained by conversion

from a value p.

a value of type T& obtained by the expression *p.

a value of type XX::void_pointer obtained by conversion

from a value p

§ 20.5.3.5

422

Table 30 — Descriptive variable definitions (continued)

Variable

Definition

a value of type XX::const_void_pointer obtained by

conversion from a value q or a value w

a value of type XX::const_void_pointer obtained by

conversion from a result value of YY::allocate, or else a

value of type (possibly const) std::nullptr_t.

a value of type XX::size_type.

Args

a template parameter pack

args

a function parameter pack with the pattern Args&&

Table 31 — Allocator requirements

Expression

Return type

Assertion/note

Default

pre-/post-condition

X::pointer

X::const_pointer

X::pointer is convertible to

pointer_-

X::const_pointer

traits<X::

pointer>::

rebind<const

X::void_pointer

X::pointer is convertible to

pointer_-

Y::void_pointer

X::void_pointer.

traits<X::

X::void_pointer and

pointer>::

Y::void_pointer are the same

rebind<void>

type.

X::const_void_-

X::pointer,

pointer_-

pointer

X::const_pointer, and

traits<X::

Y::const_void_-

X::void_pointer are

pointer>::

pointer

convertible to

rebind<const

X::const_void_pointer.

void>

X::const_void_pointer and

Y::const_void_pointer are

the same type.

X::value_type

Identical to T

X::size_type

unsigned integer type

a type that can represent the

make_-

size of the largest object in the

unsigned_-

allocation model.

t<X::

difference_-

type>

X::difference_type

signed integer type

a type that can represent the

pointer_-

difference between any two

traits<X::

pointers in the allocation model.

pointer>::

difference_-

type

typename

For all U (including T),

See Note A,

X::template

Y::template

below.

rebind::other

rebind<T>::other is X.

const T&

*q refers to the same object as

p->m

type of T::m

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

equivalent to (*p).m

q->m

type of T::m

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

equivalent to (*q).m

§ 20.5.3.5

423

Table 31 — Allocator requirements (continued)

Expression

Return type

Assertion/note

Default

pre-/post-condition

static_cast<

X::pointer

static_cast<X::pointer>(w)

X::pointer>(w)

== p

static_cast<

X::const_pointer

static_cast<

X::const_pointer

X::const_pointer>(x) == q

>(x)

pointer_traits<

X::pointer

same as p

X::pointer

>::pointer_to(r)

a.allocate(n)

X::pointer

Memory is allocated for n

objects of type T but objects are

not constructed. allocate may

throw an appropriate

exception.¹⁷⁸ [ Note: If n == 0,

the return value is unspecified.

— end note ]

a.allocate(n, y)

X::pointer

Same as a.allocate(n). The

a.allocate(n)

use of y is unspecified, but it is

intended as an aid to locality.

a.deallocate(p,n)

(not used)

Requires: p shall be a value

returned by an earlier call to

allocate that has not been

invalidated by an intervening

call to deallocate. n shall

match the value passed to

allocate to obtain this

memory.

Throws: Nothing.

a.max_size()

X::size_type

the largest value that can

numeric_-

meaningfully be passed to

limits<size_-

X::allocate()

type>::max()

/ sizeof

(value_type)

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 u(a);

Shall not exit via an exception.

X u = a;

Postconditions: u == a

X u(b);

Shall not exit via an exception.

Postconditions: Y(u) == b, u

== X(b)

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

Shall not exit via an exception.

X u = std::move(a);

Postconditions: The value of a

is unchanged and is equal to u.

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

§ 20.5.3.5

424

Table 31 — Allocator requirements (continued)

Expression

Return type

Assertion/note

Default

pre-/post-condition

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

Shall not exit via an exception.

Postconditions: u is equal to the

prior value of X(b).

a.construct(c,

(not used)

Effects: Constructs an object of

::new

args)

type C at c

((void*)c)

C(forward<

Args>

(args)...)

a.destroy(c)

(not used)

Effects: Destroys the object at c

c->~C()

a.select_on_-

Typically returns either a or X()

return a;

container_copy_-

construction()

X::propagate_on_-

Identical to or derived

true_type only if an allocator

false_type

container_copy_-

from true_type or

of type X should be copied when

assignment

false_type

the client container is

copy-assigned. See Note B,

below.

X::propagate_on_-

Identical to or derived

true_type only if an allocator

false_type

container_move_-

from true_type or

of type X should be moved when

assignment

false_type

the client container is

move-assigned. See Note B,

below.

X::propagate_on_-

Identical to or derived

true_type only if an allocator

false_type

container_swap

from true_type or

of type X should be swapped

false_type

when the client container is

swapped. See Note B, below.

X::is_always_equal

Identical to or derived

true_type only if the expression

is_empty<X>::

from true_type or

a1 == a2 is guaranteed to be

type

false_type

true for any two (possibly

const) values a1, a2 of type X.

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::other is

the same type as SomeAllocator, where SomeAllocator<T>::value_type is T and SomeAllocator::

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::other by default. For allocator types that are not template instantiations of the above form,

no default is provided.

Note B: If X::propagate_on_container_copy_assignment::value is true, X shall satisfy the CopyAssign-

able requirements (Table 26) and the copy operation shall not throw exceptions. If X::propagate_on_-

container_move_assignment::value is true, X shall satisfy the MoveAssignable requirements (Table 25)

and the move operation shall not throw exceptions. If X::propagate_on_container_swap::value is true,

lvalues of type X shall be swappable (20.5.3.2) and the swap operation shall not throw exceptions.

An allocator type X shall satisfy the requirements of CopyConstructible (20.5.3.1). The X::pointer,

X::const_pointer, X::void_pointer, and X::const_void_pointer types shall satisfy the requirements of

NullablePointer (20.5.3.3). No constructor, comparison function, copy operation, move operation, or swap

operation on these pointer types shall exit via an exception. X::pointer and X::const_pointer shall also

satisfy the requirements for a random access iterator (27.2.7) and of a contiguous iterator (27.2.1).

Let x1 and x2 denote objects of (possibly different) types X::void_pointer, X::const_void_pointer,

X::pointer, or X::const_pointer. Then, x1 and x2 are equivalently-valued pointer values, if and only if

§ 20.5.3.5

425

both x1 and x2 can be explicitly converted to the two corresponding objects px1 and px2 of type X::const_-

pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2

evaluates to true.

Let w1 and w2 denote objects of type X::void_pointer. Then for the expressions

w1 == w2

w1 != w2

either or both objects may be replaced by an equivalently-valued object of type X::const_void_pointer

with no change in semantics.

Let p1 and p2 denote objects of type X::pointer. Then for the expressions

p1 == p2

p1 != p2

p1 < p2

p1 <= p2

p1 >= p2

p1 > p2

p1 - p2

either or both objects may be replaced by an equivalently-valued object of type X::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.

[Example: The following is an allocator class template supporting the minimal interface that satisfies the

requirements of Table 31:

template<class Tp>

struct SimpleAllocator {

typedef Tp value_type;

SimpleAllocator(ctor args );

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

[[nodiscard]] Tp* allocate(std::size_t n);

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

};

template<class T, class U>

bool operator==(const SimpleAllocator<T>&, const SimpleAllocator&);

template<class T, class U>

bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator&);

— 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

bad_alloc. — end note ]

20.5.3.5.1

Allocator completeness requirements

[allocator.requirements.completeness]

If X is an allocator class for type T, X additionally satisfies the allocator completeness requirements if, whether

or not T is a complete type:

(1.1)

—

X is a complete type, and

(1.2)

—

all the member types of allocator_traits<X> (23.10.9) other than value_type are complete types.

20.5.4

Constraints on programs

[constraints]

20.5.4.1

Overview

[constraints.overview]

Subclause 20.5.4 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 (20.5.4.2.1), its use of

various reserved names (20.5.4.3), its use of headers (20.5.4.4), its use of standard library classes as base

§ 20.5.4.1

426

classes (20.5.4.5), its definitions of replacement functions (20.5.4.6), and its installation of handler functions

during execution (20.5.4.7).

20.5.4.2

Namespace use

[namespace.constraints]

20.5.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.¹⁷⁹

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.

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

(3.1)

—

an explicit specialization of any member function of a standard library class template, or

(3.2)

—

an explicit specialization of any member function template of a standard library class or class template,

(3.3)

—

an explicit or partial specialization of any member class template of a standard library class or class

template, or

(3.4)

—

a deduction guide for any standard library 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 (10.3.1).

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

20.5.4.2.3

Namespaces for future standardization

[namespace.future]

Top level namespaces with a name starting with std and followed by a non-empty sequence of digits are

reserved for future standardization. The behavior of a C++ program is undefined if it adds declarations or

definitions to such a namespace.

[Example: The top level namespace std2 is reserved for use by future

revisions of this International Standard.

— end example ]

20.5.4.3

Reserved names

[reserved.names]

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

(1.1)

—

macros

(1.2)

—

global names

(1.3)

—

names with external linkage

If a program declares or defines a name in a context where it is reserved, other than as explicitly allowed by

this Clause, its behavior is undefined.

20.5.4.3.1

Zombie names

[zombie.names]

In namespace std, the following names are reserved for previous standardization:

(1.1)

—

auto_ptr,

(1.2)

—

binary_function,

(1.3)

—

bind1st,

(1.4)

—

bind2nd,

(1.5)

—

binder1st,

179) Any library code that instantiates other library templates must be prepared to work adequately with any user-supplied

specialization that meets the minimum requirements of this document.

§ 20.5.4.3.1

427

(1.6)

—

binder2nd,

(1.7)

—

const_mem_fun1_ref_t,

(1.8)

—

const_mem_fun1_t,

(1.9)

—

const_mem_fun_ref_t,

(1.10)

—

const_mem_fun_t,

(1.11)

—

get_unexpected,

(1.12)

—

mem_fun1_ref_t,

(1.13)

—

mem_fun1_t,

(1.14)

—

mem_fun_ref_t,

(1.15)

—

mem_fun_ref,

(1.16)

—

mem_fun_t,

(1.17)

—

mem_fun,

(1.18)

—

pointer_to_binary_function,

(1.19)

—

pointer_to_unary_function,

(1.20)

—

ptr_fun,

(1.21)

—

random_shuffle,

(1.22)

—

set_unexpected,

(1.23)

—

unary_function,

(1.24)

—

unexpected, and

(1.25)

—

unexpected_handler.

20.5.4.3.2

Macro names

[macro.names]

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

any standard library header.

A translation unit shall not #define or #undef names lexically identical to keywords, to the identifiers listed

in Table 4, or to the attribute-tokens described in 10.6.

20.5.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,¹⁸⁰ 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.¹⁸¹

Each name from the C standard library declared with external linkage is reserved to the implementation for

use as a name with extern "C" linkage, both in namespace std and in the global namespace.

Each function signature from the C standard library declared with external linkage is reserved to the

implementation for use as a function signature with both extern "C" and extern "C++" linkage,¹⁸² or as a

name of namespace scope in the global namespace.

20.5.4.3.4

Types

[extern.types]

For each type T from the C standard library,¹⁸³ the types ::T and std::T are reserved to the implementation

and, when defined, ::T shall be identical to std::T.

20.5.4.3.5

User-defined literal suffixes

[usrlit.suffix]

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

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

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

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

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

§ 20.5.4.3.5

428

20.5.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 (19.2), the behavior is undefined.

20.5.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 (13.3).

20.5.4.6

Replacement functions

[replacement.functions]

Clause 21 through Clause 33 and Annex D 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 (20.3).

A C++ program may provide the definition for any of the following dynamic memory allocation function

signatures declared in header <new> (6.6.4.4, 21.6):

operator new(std::size_t)

operator new(std::size_t, std::align_val_t)

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

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

operator delete(void*)

operator delete(void*, std::size_t)

operator delete(void*, std::align_val_t)

operator delete(void*, std::size_t, std::align_val_t)

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

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

operator new[](std::size_t)

operator new[](std::size_t, std::align_val_t)

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

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

operator delete[](void*)

operator delete[](void*, std::size_t)

operator delete[](void*, std::align_val_t)

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

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

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

The program’s definitions are used instead of the default versions supplied by the implementation (21.6).

Such replacement occurs prior to program startup (6.2, 6.8.3). The program’s declarations shall not be

specified as inline. No diagnostic is required.

20.5.4.7

Handler functions

[handler.functions]

The C++ standard library provides a default version of the following handler function (Clause 21):

(1.1)

—

terminate_handler

A C++ program may install different handler functions during execution, by supplying a pointer to a function

defined in the program or the library as an argument to (respectively):

(2.1)

—

set_new_handler

(2.2)

—

set_terminate

See also subclauses 21.6.3, Storage allocation errors, and 21.8, Exception handling.

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

(3.1)

—

get_new_handler

(3.2)

—

get_terminate

Calling the set_* and get_* functions shall not incur a data race. A call to any of the set_* functions shall

synchronize with subsequent calls to the same set_* function and to the corresponding get_* function.

§ 20.5.4.7

429

20.5.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++ pro-

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

implementation.

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

(2.1)

—

for replacement functions (21.6.2), if the installed replacement function does not implement the semantics

of the applicable Required behavior: paragraph.

(2.2)

—

for handler functions (21.6.3.3, 21.8.4.1), if the installed handler function does not implement the

semantics of the applicable Required behavior: paragraph

(2.3)

—

for types used as template arguments when instantiating a template component, if the operations on

the type do not implement the semantics of the applicable Requirements subclause (20.5.3.5, 26.2, 27.2,

28.3, 29.3). Operations on such types can report a failure by throwing an exception unless otherwise

specified.

(2.4)

—

if any replacement function or handler function or destructor operation exits via an exception, unless

specifically allowed in the applicable Required behavior: paragraph.

(2.5)

—

if an incomplete type (6.7) is used as a template argument when instantiating a template component,

unless specifically allowed for that component.

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

(1.1)

—

If an argument to a function has an invalid value (such as a value outside the domain of the function or

a pointer invalid for its intended use), the behavior is undefined.

(1.2)

—

If a function argument is described as being an array, the pointer actually passed to the function shall

have a value such that all address computations and accesses to objects (that would be valid if the

pointer did point to the first element of such an array) are in fact valid.

—

(1.3)

If a function argument 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 (17.9.2.1) 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

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 might be needed if the

argument was an lvalue.

— end note ]

20.5.4.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 20.5.5.9. [ 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 shareable without data races or the user supplies a locking

mechanism. — end note ]

If an object of a standard library type is accessed, and the beginning of the object’s lifetime (6.6.3) does not

happen before the access, or the access does not happen before the end of the object’s lifetime, the behavior

is undefined unless otherwise specified. [ Note: This applies even to objects such as mutexes intended for

thread synchronization.

— end note ]

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

20.5.5

Conforming implementations

[conforming]

20.5.5.1

Overview

[conforming.overview]

Subclause 20.5.5 describes the constraints upon, and latitude of, implementations of the C++ standard library.

§ 20.5.5.1

430

An implementation’s use of headers is discussed in 20.5.5.2, its use of macros in 20.5.5.3, non-member functions

in 20.5.5.4, member functions in 20.5.5.5, data race avoidance in 20.5.5.9, access specifiers in 20.5.5.10, class

derivation in 20.5.5.11, and exceptions in 20.5.5.12.

20.5.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 (6.2).

The C standard library headers (D.5) shall include only their corresponding C++ standard library header, as

described in 20.5.1.2.

20.5.5.3

Restrictions on macro definitions

[res.on.macro.definitions]

The names and global function signatures described in 20.5.1.1 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.

20.5.5.4

Non-member functions

[global.functions]

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

A call to a non-member function signature described in Clause 21 through Clause 33 and Annex D shall

behave as if the implementation declared no additional non-member function signatures.¹⁸⁴

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 (6.4.2). [ Note: The phrase “unless otherwise specified” applies to cases such as the swappable with

requirements (20.5.3.2). The exception for overloaded operators allows argument-dependent lookup in cases

like that of ostream_iterator::operator= (27.6.2.2):

Effects:

*out_stream

<< value;

if (delim

!= 0)

*out_stream

<< delim ;

return *this;

— end note ]

20.5.5.5

Member functions

[member.functions]

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

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: For instance, an implementation may 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 ]

20.5.5.6

Constexpr functions and constructors

[constexpr.functions]

This document explicitly requires that certain standard library functions are constexpr (10.1.5). 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.

184) A valid C++ program always calls the expected library non-member function. An implementation may also define additional

non-member functions that would otherwise not be called by a valid C++ program.

§ 20.5.5.6

431

20.5.5.7

Requirements for stable algorithms

[algorithm.stable]

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

(1.1)

—

For the sort algorithms the relative order of equivalent elements is preserved.

(1.2)

—

For the remove and copy algorithms the relative order of the elements that are not removed is preserved.

(1.3)

—

For the merge algorithms, for equivalent elements in the original two ranges, the elements from the first

range (preserving their original order) precede the elements from the second range (preserving their

original order).

20.5.5.8

Reentrancy

[reentrancy]

Except where explicitly specified in this document, it is implementation-defined which functions in the C++

standard library may be recursively reentered.

20.5.5.9

Data race avoidance

[res.on.data.races]

This subclause specifies requirements that implementations shall meet to prevent data races (6.8.2). 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 (6.8.2) 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 (6.8.2) 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 (6.8.2) to users.

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

— end note ]

20.5.5.10

Protection within classes

[protection.within.classes]

It is unspecified whether any function signature or class described in Clause 21 through Clause 33 and Annex

D is a friend of another class in the C++ standard library.

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

(3.1)

—

Every base class described as virtual shall be virtual;

(3.2)

—

Every base class not specified as virtual shall not be virtual;

§ 20.5.5.11

432

(3.3)

—

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.

20.5.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, or of a type derived from a type named in the Throws: paragraph

that would be caught by an exception handler for the base type.

Functions from the C standard library shall not throw exceptions¹⁸⁶ except when such a function calls a

program-supplied function that throws an exception.¹⁸⁷

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.

Functions defined in the C++ standard library that do not have a Throws: paragraph but do have a potentially-

throwing exception specification may throw implementation-defined exceptions.¹⁸⁸ Implementations should

report errors by throwing exceptions of or derived from the standard exception classes (21.6.3.1, 21.8, 22.2).

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

non-throwing exception specification.

20.5.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 (6.6.4.4.3). [ 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 ]

20.5.5.14

Value of error codes

[value.error.codes]

Certain functions in the C++ standard library report errors via a std::error_code (22.5.3.1) 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 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 ]

20.5.5.15

Moved-from state of library types

[lib.types.movedfrom]

Objects of types defined in the C++ standard library may be moved from (15.8). 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.

185) There is an implicit exception to this rule for types that are described as synonyms for basic integral types, such as

size_t (21.2) and streamoff (30.5.2).

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

187) The functions qsort() and bsearch() (28.8) meet this condition.

188) 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 (21.6.3.1).

§ 20.5.5.15

433

Language support library

[language.support]

21.1

General

[support.general]

This Clause describes the function signatures that are called implicitly, and the types of objects generated

implicitly, during the execution of some C++ programs. It also describes the headers that declare these

function signatures and define any related types.

The following subclauses describe common type definitions used throughout the library, characteristics of

the predefined types, functions supporting start and termination of a C++ program, support for dynamic

memory management, support for dynamic type identification, support for exception processing, support for

initializer lists, and other runtime support, as summarized in Table 32.

Table 32 — Language support library summary

Subclause

Header(s)

21.2

Common definitions

21.3

Implementation properties

21.4

Integer types

21.5

Start and termination

21.6

Dynamic memory management

<new>

21.7

Type identification

21.8

Exception handling

21.9

Initializer lists

<initializer_list>

21.10

Comparisons

21.11

Other runtime support

21.2

Common definitions

[support.types]

21.2.1

Header <cstddef> synopsis

[cstddef.syn]

namespace std {

using ptrdiff_t = see below ;

using size_t = see below ;

using max_align_t = see below ;

using nullptr_t = decltype(nullptr);

enum class byte : unsigned char {};

// 21.2.5, byte type operations

template<class IntType>

constexpr byte& operator<<=(byte& b, IntType shift) noexcept;

template<class IntType>

constexpr byte operator<<(byte b, IntType shift) noexcept;

template<class IntType>

constexpr byte& operator>>=(byte& b, IntType shift) noexcept;

template<class IntType>

constexpr byte operator>>(byte b, IntType shift) noexcept;

constexpr byte& operator|=(byte& l, byte r) noexcept;

constexpr byte operator|(byte l, byte r) noexcept;

§ 21.2.1

434

constexpr byte& operator&=(byte& l, byte r) noexcept;

constexpr byte operator&(byte l, byte r) noexcept;

constexpr byte& operator^=(byte& l, byte r) noexcept;

constexpr byte operator^(byte l, byte r) noexcept;

constexpr byte operator~(byte b) noexcept;

template<class IntType>

constexpr IntType to_integer(byte b) noexcept;

}

#define NULL see below

#define offsetof(P, D) see below

The contents and meaning of the header <cstddef> are the same as the C standard library header <stddef.h>,

except that it does not declare the type wchar_t, that it also declares the type byte and its associated

operations (21.2.5), and as noted in 21.2.3 and 21.2.4.

Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 15