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

Meaningful for all floating-point types.

static constexpr int max_exponent;

Maximum positive integer such that radix raised to the power one less than that integer is a representable

finite floating-point number.²⁰²

Meaningful for all floating-point types.

static constexpr int max_exponent10;

Maximum positive integer such that 10 raised to that power is in the range of representable finite

floating-point numbers.²⁰³

Meaningful for all floating-point types.

static constexpr bool has_infinity;

true if the type has a representation for positive infinity.

Meaningful for all floating-point types.

Shall be true for all specializations in which is_iec559 != false.

static constexpr bool has_quiet_NaN;

true if the type has a representation for a quiet (non-signaling) “Not a Number”.²⁰⁴

Meaningful for all floating-point types.

Shall be true for all specializations in which is_iec559 != false.

static constexpr bool has_signaling_NaN;

true if the type has a representation for a signaling “Not a Number”.²⁰⁵

Meaningful for all floating-point types.

Shall be true for all specializations in which is_iec559 != false.

static constexpr float_denorm_style has_denorm;

denorm_present if the type allows subnormal values (variable number of exponent bits)²⁰⁶, denorm_-

absent if the type does not allow subnormal values, and denorm_indeterminate if it is indeterminate

at compile time whether the type allows subnormal values.

Meaningful for all floating-point types.

static constexpr bool has_denorm_loss;

true if loss of accuracy is detected as a denormalization loss, rather than as an inexact result.²⁰⁷

static constexpr T infinity() noexcept;

Representation of positive infinity, if available.²⁰⁸

Meaningful for all specializations for which has_infinity != false. Required in specializations for

which is_iec559 != false.

static constexpr T quiet_NaN() noexcept;

Representation of a quiet “Not a Number”, if available.²⁰⁹

Meaningful for all specializations for which has_quiet_NaN != false. Required in specializations for

which is_iec559 != false.

202) Equivalent to FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP.

203) Equivalent to FLT_MAX_10_EXP, DBL_MAX_10_EXP, LDBL_MAX_10_EXP.

204) Required by LIA-1.

205) Required by LIA-1.

206) Required by LIA-1.

207) See ISO/IEC/IEEE 60559.

208) Required by LIA-1.

209) Required by LIA-1.

§ 21.3.4.1

442

static constexpr T signaling_NaN() noexcept;

Representation of a signaling “Not a Number”, if available.²¹⁰

Meaningful for all specializations for which has_signaling_NaN != false. Required in specializations

for which is_iec559 != false.

static constexpr T denorm_min() noexcept;

Minimum positive subnormal value.²¹¹

Meaningful for all floating-point types.

In specializations for which has_denorm == false, returns the minimum positive normalized value.

static constexpr bool is_iec559;

true if and only if the type adheres to ISO/IEC/IEEE 60559.²¹²

Meaningful for all floating-point types.

static constexpr bool is_bounded;

true if the set of values representable by the type is finite.²¹³ [ Note: All fundamental types (6.7.1) are

bounded. This member would be false for arbitrary precision types. — end note ]

Meaningful for all specializations.

static constexpr bool is_modulo;

true if the type is modulo.²¹⁴ A type is modulo if, for any operation involving +, -, or * on values of

that type whose result would fall outside the range [min(), max()], the value returned differs from

the true value by an integer multiple of max() - min() + 1.

[ Example: is_modulo is false for signed integer types (6.7.1) unless an implementation, as an extension

to this document, defines signed integer overflow to wrap.

— end example ]

Meaningful for all specializations.

static constexpr bool traps;

true if, at program startup, there exists a value of the type that would cause an arithmetic operation

using that value to trap.²¹⁵

Meaningful for all specializations.

static constexpr bool tinyness_before;

true if tinyness is detected before rounding.²¹⁶

Meaningful for all floating-point types.

static constexpr float_round_style round_style;

The rounding style for the type.²¹⁷

Meaningful for all floating-point types. Specializations for integer types shall return round_toward_-

zero.

21.3.4.2

numeric_limits specializations

[numeric.special]

All members shall be provided for all specializations. However, many values are only required to be meaningful

under certain conditions (for example, epsilon() is only meaningful if is_integer is false). Any value

that is not “meaningful” shall be set to 0 or false.

[ Example:

210) Required by LIA-1.

211) Required by LIA-1.

212) ISO/IEC/IEEE 60559:2011 is the same as IEEE 754-2008.

213) Required by LIA-1.

214) Required by LIA-1.

215) Required by LIA-1.

216) Refer to ISO/IEC/IEEE 60559. Required by LIA-1.

217) Equivalent to FLT_ROUNDS. Required by LIA-1.

§ 21.3.4.2

443

namespace std {

template<> class numeric_limits<float> {

public:

static

constexpr

bool is_specialized = true;

static

constexpr

float min() noexcept { return 1.17549435E-38F; }

static

constexpr

float max() noexcept { return 3.40282347E+38F; }

static

constexpr

float lowest() noexcept { return -3.40282347E+38F; }

static

constexpr

int digits

= 24;

static

constexpr

int digits10 =

static

constexpr

int max_digits10 =

static

constexpr

bool is_signed

= true;

static

constexpr

bool is_integer = false;

static

constexpr

bool is_exact

= false;

static

constexpr

int radix = 2;

static

constexpr

float epsilon() noexcept

{ return 1.19209290E-07F;

}

static

constexpr

float round_error() noexcept { return 0.5F; }

static

constexpr

int min_exponent

= -125;

static

constexpr

int min_exponent10 = - 37;

static

constexpr

int max_exponent

= +128;

static

constexpr

int max_exponent10 = + 38;

static

constexpr

bool has_infinity

= true;

static

constexpr

bool has_quiet_NaN

= true;

static

constexpr

bool has_signaling_NaN

= true;

static

constexpr

float_denorm_style has_denorm = denorm_absent;

static

constexpr

bool has_denorm_loss

= false;

static

constexpr

float infinity()

noexcept { return value ; }

static

constexpr

float quiet_NaN()

noexcept { return value ; }

static

constexpr

float signaling_NaN() noexcept { return value ; }

static

constexpr

float denorm_min()

noexcept { return min(); }

static

constexpr

bool is_iec559

= true;

static

constexpr

bool is_bounded = true;

static

constexpr

bool is_modulo

= false;

static

constexpr

bool traps

= true;

static

constexpr

bool tinyness_before = true;

static

constexpr

float_round_style round_style = round_to_nearest;

};

}

— end example ]

The specialization for bool shall be provided as follows:

namespace std {

template<> class numeric_limits<bool> {

public:

static constexpr bool is_specialized = true;

static constexpr bool min() noexcept { return false; }

static constexpr bool max() noexcept { return true; }

static constexpr bool lowest() noexcept { return false; }

static constexpr int digits = 1;

static constexpr int digits10 = 0;

static constexpr int max_digits10 = 0;

static constexpr bool is_signed = false;

static constexpr bool is_integer = true;

§ 21.3.4.2

444

static

constexpr

bool is_exact = true;

static

constexpr

int radix = 2;

static

constexpr

bool epsilon() noexcept { return 0; }

static

constexpr

bool round_error() noexcept { return 0; }

static

constexpr

int min_exponent = 0;

static

constexpr

int min_exponent10 = 0;

static

constexpr

int max_exponent = 0;

static

constexpr

int max_exponent10 = 0;

static

constexpr

bool has_infinity = false;

static

constexpr

bool has_quiet_NaN = false;

static

constexpr

bool has_signaling_NaN = false;

static

constexpr

float_denorm_style has_denorm = denorm_absent;

static

constexpr

bool has_denorm_loss = false;

static

constexpr

bool infinity() noexcept { return 0; }

static

constexpr

bool quiet_NaN() noexcept { return 0; }

static

constexpr

bool signaling_NaN() noexcept { return 0; }

static

constexpr

bool denorm_min() noexcept { return 0; }

static

constexpr

bool is_iec559 = false;

static

constexpr

bool is_bounded = true;

static

constexpr

bool is_modulo = false;

static

constexpr

bool traps = false;

static

constexpr

bool tinyness_before = false;

static

constexpr

float_round_style round_style

round_toward_zero;

};

}

21.3.5

Header <climits> synopsis

[climits.syn]

#define CHAR_BIT see below

#define SCHAR_MIN see below

#define SCHAR_MAX see below

#define UCHAR_MAX see below

#define CHAR_MIN see below

#define CHAR_MAX see below

#define MB_LEN_MAX see below

#define SHRT_MIN see below

#define SHRT_MAX see below

#define USHRT_MAX see below

#define INT_MIN see below

#define INT_MAX see below

#define UINT_MAX see below

#define LONG_MIN see below

#define LONG_MAX see below

#define ULONG_MAX see below

#define LLONG_MIN see below

#define LLONG_MAX see below

#define ULLONG_MAX see below

The header <climits> defines all macros the same as the C standard library header <limits.h>. [Note:

The types of the constants defined by macros in <climits> are not required to match the types to which the

macros refer.

— end note ]

See also: ISO C 7.22.4

21.6

Dynamic memory management

[support.dynamic]

The header <new> defines several functions that manage the allocation of dynamic storage in a program. It

also defines components for reporting storage management errors.

21.6.1

Header <new> synopsis

[new.syn]

namespace std {

class bad_alloc;

class bad_array_new_length;

enum class align_val_t : size_t {};

struct nothrow_t { explicit nothrow_t() = default; };

extern const nothrow_t nothrow;

218) A function is called for every time it is registered.

219) Objects with automatic storage duration are all destroyed in a program whose main function (6.8.3.1) contains no automatic

objects and executes the call to exit(). Control can be transferred directly to such a main function by throwing an exception

that is caught in main.

220) The macros EXIT_FAILURE and EXIT_SUCCESS are defined in <cstdlib>.

§ 21.6.1

448

using new_handler = void (*)();

new_handler get_new_handler() noexcept;

new_handler set_new_handler(new_handler new_p) noexcept;

// 21.6.4, pointer optimization barrier

template<class T> [[nodiscard]] constexpr T* launder(T* p) noexcept;

// 21.6.5, hardware interference size

inline constexpr size_t hardware_destructive_interference_size = implementation-defined ;

inline constexpr size_t hardware_constructive_interference_size = implementation-defined ;

}

[[nodiscard]] void* operator new(std::size_t size);

[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment);

[[nodiscard]] void* operator new(std::size_t size, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment,

const std::nothrow_t&) noexcept;

void operator delete(void* ptr) noexcept;

void operator delete(void* ptr, std::size_t size) noexcept;

void operator delete(void* ptr, std::align_val_t alignment) noexcept;

void operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;

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

void operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new[](std::size_t size);

[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment);

[[nodiscard]] void* operator new[](std::size_t size, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment,

const std::nothrow_t&) noexcept;

void operator delete[](void* ptr) noexcept;

void operator delete[](void* ptr, std::size_t size) noexcept;

void operator delete[](void* ptr, std::align_val_t alignment) noexcept;

void operator delete[](void* ptr, std::size_t size, std::align_val_t alignment) noexcept;

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

void operator delete[](void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new

(std::size_t size, void* ptr) noexcept;

[[nodiscard]] void* operator new[](std::size_t size, void* ptr) noexcept;

void operator delete

(void* ptr, void*) noexcept;

void operator delete[](void* ptr, void*) noexcept;

21.6.2

Storage allocation and deallocation

[new.delete]

Except where otherwise specified, the provisions of 6.6.4.4 apply to the library versions of operator new

and operator delete. If the value of an alignment argument passed to any of these functions is not a valid

alignment value, the behavior is undefined.

21.6.2.1

Single-object forms

[new.delete.single]

[[nodiscard]] void* operator new(std::size_t size);

[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment);

Effects: The allocation functions (6.6.4.4.1) called by a new-expression (8.5.2.4) to allocate size bytes

of storage. The second form is called for a type with new-extended alignment, and allocates storage

with the specified alignment. The first form is called otherwise, and allocates storage suitably aligned

to represent any object of that size provided the object’s type does not have new-extended alignment.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Required behavior: Return a non-null pointer to suitably aligned storage (6.6.4.4), or else throw a

bad_alloc exception. This requirement is binding on any replacement versions of these functions.

Default behavior:

§ 21.6.2.1

449

(4.1)

—

Executes a loop: Within the loop, the function first attempts to allocate the requested storage.

Whether the attempt involves a call to the C standard library functions malloc or aligned_alloc

is unspecified.

(4.2)

—

Returns a pointer to the allocated storage if the attempt is successful. Otherwise, if the current

new_handler (21.6.3.5) is a null pointer value, throws bad_alloc.

(4.3)

—

Otherwise, the function calls the current new_handler function (21.6.3.3). If the called function

returns, the loop repeats.

(4.4)

—

The loop terminates when an attempt to allocate the requested storage is successful or when a

called new_handler function does not return.

[[nodiscard]] void* operator new(std::size_t size, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment,

const std::nothrow_t&) noexcept;

Effects: Same as above, except that these are called by a placement version of a new-expression when a

C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Required behavior: Return a non-null pointer to suitably aligned storage (6.6.4.4), or else return a null

pointer. Each of these nothrow versions of operator new returns a pointer obtained as if acquired

from the (possibly replaced) corresponding non-placement function. This requirement is binding on

any replacement versions of these functions.

Default behavior: Calls operator new(size), or operator new(size, alignment), respectively. If

the call returns normally, returns the result of that call. Otherwise, returns a null pointer.

[ Example:

T* p1 = new T;

// throws bad_alloc if it fails

T* p2 = new(nothrow) T;

// returns nullptr if it fails

— end example ]

void

operator delete(void* ptr) noexcept;

void

operator delete(void* ptr, std::size_t size) noexcept;

void

operator delete(void* ptr, std::align_val_t alignment) noexcept;

void

operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;

Effects: The deallocation functions (6.6.4.4.2) called by a delete-expression (8.5.2.5) to render the value

of ptr invalid.

Replaceable: A C++ program may define functions with any of these function signatures, and thereby

displace the default versions defined by the C++ standard library. If a function without a size parameter

is defined, the program should also define the corresponding function with a size parameter. If a

function with a size parameter is defined, the program shall also define the corresponding version

without the size parameter. [ Note: The default behavior below may change in the future, which will

require replacing both deallocation functions when replacing the allocation function.

— end note ]

Requires: ptr shall be a null pointer or its value shall represent the address of a block of memory allocated

by an earlier call to a (possibly replaced) operator new(std::size_t) or operator new(std::size_-

t, std::align_val_t) which has not been invalidated by an intervening call to operator delete.

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Requires: If the alignment parameter is not present, ptr shall have been returned by an allocation

function without an alignment parameter. If present, the alignment argument shall equal the

alignment argument passed to the allocation function that returned ptr. If present, the size argument

shall equal the size argument passed to the allocation function that returned ptr.

Required behavior: A call to an operator delete with a size parameter may be changed to a call to

the corresponding operator delete without a size parameter, without affecting memory allocation.

[Note: A conforming implementation is for operator delete(void* ptr, std::size_t size) to

simply call operator delete(ptr).

— end note ]

§ 21.6.2.1

450

Default behavior: The functions that have a size parameter forward their other parameters to the

corresponding function without a size parameter.

[Note: See the note in the above Replaceable:

paragraph.

— end note ]

Default behavior: If ptr is null, does nothing. Otherwise, reclaims the storage allocated by the earlier

call to operator new.

Remarks: It is unspecified under what conditions part or all of such reclaimed storage will be allocated

by subsequent calls to operator new or any of aligned_alloc, calloc, malloc, or realloc, declared

in <cstdlib>.

void

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

void

operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;

Effects: The deallocation functions (6.6.4.4.2) called by the implementation to render the value of ptr

invalid when the constructor invoked from a nothrow placement version of the new-expression throws

an exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Requires: ptr shall be a null pointer or its value shall represent the address of a block of memory allocated

by an earlier call to a (possibly replaced) operator new(std::size_t) or operator new(std::size_-

t, std::align_val_t) which has not been invalidated by an intervening call to operator delete.

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Requires: If the alignment parameter is not present, ptr shall have been returned by an allocation

function without an alignment parameter. If present, the alignment argument shall equal the

alignment argument passed to the allocation function that returned ptr.

Default behavior: Calls operator delete(ptr), or operator delete(ptr, alignment), respectively.

21.6.2.2

Array forms

[new.delete.array]

[[nodiscard]] void* operator new[](std::size_t size);

[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment);

Effects: The allocation functions (6.6.4.4.1) called by the array form of a new-expression (8.5.2.4) to

allocate size bytes of storage. The second form is called for a type with new-extended alignment, and

allocates storage with the specified alignment. The first form is called otherwise, and allocates storage

suitably aligned to represent any array object of that size or smaller, provided the object’s type does

not have new-extended alignment.²²¹

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Required behavior: Same as for the corresponding single-object forms. This requirement is binding on

any replacement versions of these functions.

Default behavior: Returns operator new(size), or operator new(size, alignment), respectively.

[[nodiscard]] void* operator new[](std::size_t size, const std::nothrow_t&) noexcept;

[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment,

const std::nothrow_t&) noexcept;

Effects: Same as above, except that these are called by a placement version of a new-expression when a

C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Required behavior: Return a non-null pointer to suitably aligned storage (6.6.4.4), or else return a null

pointer. Each of these nothrow versions of operator new[] returns a pointer obtained as if acquired

from the (possibly replaced) corresponding non-placement function. This requirement is binding on

any replacement versions of these functions.

221) It is not the direct responsibility of operator new[] or operator delete[] to note the repetition count or element size of

the array. Those operations are performed elsewhere in the array new and delete expressions. The array new expression, may,

however, increase the size argument to operator new[] to obtain space to store supplemental information.

§ 21.6.2.2

451

Default behavior: Calls operator new[](size), or operator new[](size, alignment), respectively.

If the call returns normally, returns the result of that call. Otherwise, returns a null pointer.

void

operator delete[](void* ptr) noexcept;

void

operator delete[](void* ptr, std::size_t size) noexcept;

void

operator delete[](void* ptr, std::align_val_t alignment) noexcept;

void

operator delete[](void* ptr, std::size_t size, std::align_val_t alignment) noexcept;

Effects: The deallocation functions (6.6.4.4.2) called by the array form of a delete-expression to render

the value of ptr invalid.

Replaceable: A C++ program may define functions with any of these function signatures, and thereby

displace the default versions defined by the C++ standard library. If a function without a size parameter

is defined, the program should also define the corresponding function with a size parameter. If a

function with a size parameter is defined, the program shall also define the corresponding version

without the size parameter. [ Note: The default behavior below may change in the future, which will

require replacing both deallocation functions when replacing the allocation function.

— end note ]

Requires: ptr shall be a null pointer or its value shall represent the address of a block of memory

allocated by an earlier call to a (possibly replaced) operator new[](std::size_t) or operator

new[](std::size_t, std::align_val_t) which has not been invalidated by an intervening call to

operator delete[].

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Requires: If the alignment parameter is not present, ptr shall have been returned by an allocation

function without an alignment parameter. If present, the alignment argument shall equal the

alignment argument passed to the allocation function that returned ptr. If present, the size argument

shall equal the size argument passed to the allocation function that returned ptr.

Required behavior: A call to an operator delete[] with a size parameter may be changed to a call to

the corresponding operator delete[] without a size parameter, without affecting memory allocation.

[ Note: A conforming implementation is for operator delete[](void* ptr, std::size_t size) to

simply call operator delete[](ptr).

— end note ]

Default behavior: The functions that have a size parameter forward their other parameters to the

corresponding function without a size parameter. The functions that do not have a size parameter

forward their parameters to the corresponding operator delete (single-object) function.

void

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

void

operator delete[](void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;

Effects: The deallocation functions (6.6.4.4.2) called by the implementation to render the value of ptr

invalid when the constructor invoked from a nothrow placement version of the array new-expression

throws an exception.

Replaceable: A C++ program may define functions with either of these function signatures, and thereby

displace the default versions defined by the C++ standard library.

Requires: ptr shall be a null pointer or its value shall represent the address of a block of memory

allocated by an earlier call to a (possibly replaced) operator new[](std::size_t) or operator

new[](std::size_t, std::align_val_t) which has not been invalidated by an intervening call to

operator delete[].

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Requires: If the alignment parameter is not present, ptr shall have been returned by an allocation

function without an alignment parameter. If present, the alignment argument shall equal the

alignment argument passed to the allocation function that returned ptr.

Default behavior: Calls operator delete[](ptr), or operator delete[](ptr, alignment), respec-

tively.

21.6.2.3

Non-allocating forms

[new.delete.placement]

These functions are reserved; a C++ program may not define functions that displace the versions in the

C++ standard library (20.5.4). The provisions of 6.6.4.4 do not apply to these reserved placement forms of

§ 21.6.2.3

452

operator new and operator delete.

[[nodiscard]] void* operator new(std::size_t size, void* ptr) noexcept;

Returns: ptr.

Remarks: Intentionally performs no other action.

[ Example: This can be useful for constructing an object at a known address:

void* place = operator new(sizeof(Something));

Something* p = new (place) Something();

— end example ]

[[nodiscard]] void* operator new[](std::size_t size, void* ptr) noexcept;

Returns: ptr.

Remarks: Intentionally performs no other action.

void operator delete(void* ptr, void*) noexcept;

Effects: Intentionally performs no action.

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Remarks: Default function called when any part of the initialization in a placement new-expression that

invokes the library’s non-array placement operator new terminates by throwing an exception (8.5.2.4).

void operator delete[](void* ptr, void*) noexcept;

Effects: Intentionally performs no action.

Requires: If an implementation has strict pointer safety (6.6.4.4.3) then ptr shall be a safely-derived

pointer.

Remarks: Default function called when any part of the initialization in a placement new-expression

that invokes the library’s array placement operator new terminates by throwing an exception (8.5.2.4).

21.6.2.4

Data races

[new.delete.dataraces]

For purposes of determining the existence of data races, the library versions of operator new, user replacement

versions of global operator new, the C standard library functions aligned_alloc, calloc, and malloc, the

library versions of operator delete, user replacement versions of operator delete, the C standard library

function free, and the C standard library function realloc shall not introduce a data race (20.5.5.9). Calls

to these functions that allocate or deallocate a particular unit of storage shall occur in a single total order,

and each such deallocation call shall happen before (6.8.2) the next allocation (if any) in this order.

21.6.3

Storage allocation errors

[alloc.errors]

21.6.3.1

Class bad_alloc

[bad.alloc]

namespace std {

class bad_alloc : public exception {

public:

bad_alloc() noexcept;

bad_alloc(const bad_alloc&) noexcept;

bad_alloc& operator=(const bad_alloc&) noexcept;

const char* what() const noexcept override;

};

}

The class bad_alloc defines the type of objects thrown as exceptions by the implementation to report a

failure to allocate storage.

bad_alloc() noexcept;

Effects: Constructs an object of class bad_alloc.

bad_alloc(const bad_alloc&) noexcept;

bad_alloc& operator=(const bad_alloc&) noexcept;

Effects: Copies an object of class bad_alloc.

§ 21.6.3.1

453

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4).

21.6.3.2

Class bad_array_new_length

[new.badlength]

namespace std {

class bad_array_new_length : public bad_alloc {

public:

bad_array_new_length() noexcept;

const char* what() const noexcept override;

};

}

The class bad_array_new_length defines the type of objects thrown as exceptions by the implementation

to report an attempt to allocate an array of size less than zero or greater than an implementation-defined

limit (8.5.2.4).

bad_array_new_length() noexcept;

Effects: Constructs an object of class bad_array_new_length.

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4).

21.6.3.3

Type new_handler

[new.handler]

using new_handler = void (*)();

The type of a handler function to be called by operator new() or operator new[]() (21.6.2) when

they cannot satisfy a request for additional storage.

Required behavior: A new_handler shall perform one of the following:

(2.1)

—

make more storage available for allocation and then return;

(2.2)

—

throw an exception of type bad_alloc or a class derived from bad_alloc;

(2.3)

—

terminate execution of the program without returning to the caller.

21.6.3.4

set_new_handler

[set.new.handler]

new_handler set_new_handler(new_handler new_p) noexcept;

Effects: Establishes the function designated by new_p as the current new_handler.

Returns: The previous new_handler.

Remarks: The initial new_handler is a null pointer.

21.6.3.5

get_new_handler

[get.new.handler]

new_handler get_new_handler() noexcept;

Returns: The current new_handler. [ Note: This may be a null pointer value.

— end note ]

21.6.4

Pointer optimization barrier

[ptr.launder]

template<class T> [[nodiscard]] constexpr T* launder(T* p) noexcept;

Requires: p represents the address A of a byte in memory. An object X that is within its lifetime (6.6.3)

and whose type is similar (7.5) to T is located at the address A. All bytes of storage that would be

reachable through the result are reachable through p (see below).

Returns: A value of type T * that points to X.

Remarks: An invocation of this function may be used in a core constant expression whenever the value

of its argument may be used in a core constant expression. A byte of storage is reachable through a

§ 21.6.4

454

pointer value that points to an object Y if it is within the storage occupied by Y, an object that is

pointer-interconvertible with Y, or the immediately-enclosing array object if Y is an array element.

The program is ill-formed if T is a function type or cv void.

[ Note: If a new object is created in storage occupied by an existing object of the same type, a pointer

to the original object can be used to refer to the new object unless the type contains const or reference

members; in the latter cases, this function can be used to obtain a usable pointer to the new object.

See 6.6.3.

— end note ]

[ Example:

struct X { const int n; };

X *p = new X{3};

const int a = p->n;

new (p) X{5};

// p does not point to new object (6.6.3) because X::n is const

const int b = p->n;

// undefined behavior

const int c = std::launder(p)->n;

// OK

— end example ]

21.6.5

Hardware interference size

[hardware.interference]

inline constexpr size_t hardware_destructive_interference_size = implementation-defined ;

This number is the minimum recommended offset between two concurrently-accessed objects to avoid

additional performance degradation due to contention introduced by the implementation. It shall be at least

alignof(max_align_t).

[ Example:

struct keep_apart {

alignas(hardware_destructive_interference_size) atomic<int> cat;

alignas(hardware_destructive_interference_size) atomic<int> dog;

};

— end example ]

inline constexpr size_t hardware_constructive_interference_size = implementation-defined ;

This number is the maximum recommended size of contiguous memory occupied by two objects accessed

with temporal locality by concurrent threads. It shall be at least alignof(max_align_t).

[ Example:

struct together {

atomic<int> dog;

int puppy;

};

struct kennel {

// Other data members...

alignas(sizeof(together)) together pack;

// Other data members...

};

static_assert(sizeof(together) <= hardware_constructive_interference_size);

— end example ]

21.7

Type identification

[support.rtti]

The header <typeinfo> defines a type associated with type information generated by the implementation. It

also defines two types for reporting dynamic type identification errors.

21.7.1

Header <typeinfo> synopsis

[typeinfo.syn]

namespace std {

class type_info;

class bad_cast;

class bad_typeid;

}

§ 21.7.1

455

21.7.2

Class type_info

[type.info]

namespace std {

class type_info {

public:

virtual ~type_info();

bool operator==(const type_info& rhs) const noexcept;

bool operator!=(const type_info& rhs) const noexcept;

bool before(const type_info& rhs) const noexcept;

size_t hash_code() const noexcept;

const char* name() const noexcept;

type_info(const type_info& rhs) = delete;

// cannot be copied

type_info& operator=(const type_info& rhs) = delete;

// cannot be copied

};

}

The class type_info describes type information generated by the implementation (8.5.1.8). Objects of this

class effectively store a pointer to a name for the type, and an encoded value suitable for comparing two types

for equality or collating order. The names, encoding rule, and collating sequence for types are all unspecified

and may differ between programs.

bool operator==(const type_info& rhs) const noexcept;

Effects: Compares the current object with rhs.

Returns: true if the two values describe the same type.

bool operator!=(const type_info& rhs) const noexcept;

Returns: !(*this == rhs).

bool before(const type_info& rhs) const noexcept;

Effects: Compares the current object with rhs.

Returns: true if *this precedes rhs in the implementation’s collation order.

size_t hash_code() const noexcept;

Returns: An unspecified value, except that within a single execution of the program, it shall return the

same value for any two type_info objects which compare equal.

Remarks: An implementation should return different values for two type_info objects which do not

compare equal.

const char* name() const noexcept;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4)

21.7.3

Class bad_cast

[bad.cast]

namespace std {

class bad_cast : public exception {

public:

bad_cast() noexcept;

bad_cast(const bad_cast&) noexcept;

bad_cast& operator=(const bad_cast&) noexcept;

const char* what() const noexcept override;

};

}

The class bad_cast defines the type of objects thrown as exceptions by the implementation to report the

execution of an invalid dynamic_cast expression (8.5.1.7).

bad_cast() noexcept;

Effects: Constructs an object of class bad_cast.

§ 21.7.3

456

bad_cast(const bad_cast&) noexcept;

bad_cast& operator=(const bad_cast&) noexcept;

Effects: Copies an object of class bad_cast.

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4)

21.7.4

Class bad_typeid

[bad.typeid]

namespace std {

class bad_typeid : public exception {

public:

bad_typeid() noexcept;

bad_typeid(const bad_typeid&) noexcept;

bad_typeid& operator=(const bad_typeid&) noexcept;

const char* what() const noexcept override;

};

}

The class bad_typeid defines the type of objects thrown as exceptions by the implementation to report a

null pointer in a typeid expression (8.5.1.8).

bad_typeid() noexcept;

Effects: Constructs an object of class bad_typeid.

bad_typeid(const bad_typeid&) noexcept;

bad_typeid& operator=(const bad_typeid&) noexcept;

Effects: Copies an object of class bad_typeid.

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4)

21.8

Exception handling

[support.exception]

The header <exception> defines several types and functions related to the handling of exceptions in a C++

program.

21.8.1

Header <exception> synopsis

[exception.syn]

namespace std {

class exception;

class bad_exception;

class nested_exception;

using terminate_handler = void (*)();

terminate_handler get_terminate() noexcept;

terminate_handler set_terminate(terminate_handler f) noexcept;

[[noreturn]] void terminate() noexcept;

int uncaught_exceptions() noexcept;

using exception_ptr = unspecified ;

exception_ptr current_exception() noexcept;

[[noreturn]] void rethrow_exception(exception_ptr p);

template<class E> exception_ptr make_exception_ptr(E e) noexcept;

§ 21.8.1

457

template<class T> [[noreturn]] void throw_with_nested(T&& t);

template<class E> void rethrow_if_nested(const E& e);

}

21.8.2

Class exception

[exception]

namespace std {

class exception {

public:

exception() noexcept;

exception(const exception&) noexcept;

exception& operator=(const exception&) noexcept;

virtual ~exception();

virtual const char* what() const noexcept;

};

}

The class exception defines the base class for the types of objects thrown as exceptions by C++ standard

library components, and certain expressions, to report errors detected during program execution.

Each standard library class T that derives from class exception shall have a publicly accessible copy

constructor and a publicly accessible copy assignment operator that do not exit with an exception. These

member functions shall meet the following postcondition: If two objects lhs and rhs both have dynamic

type T and lhs is a copy of rhs, then strcmp(lhs.what(), rhs.what()) shall equal 0.

exception() noexcept;

Effects: Constructs an object of class exception.

exception(const exception& rhs) noexcept;

exception& operator=(const exception& rhs) noexcept;

Effects: Copies an exception object.

Postconditions: If *this and rhs both have dynamic type exception then the value of the expression

strcmp(what(), rhs.what()) shall equal 0.

virtual ~exception();

Effects: Destroys an object of class exception.

virtual const char* what() const noexcept;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4). The return value remains valid until the exception object

from which it is obtained is destroyed or a non-const member function of the exception object is called.

21.8.3

Class bad_exception

[bad.exception]

namespace std {

class bad_exception : public exception {

public:

bad_exception() noexcept;

bad_exception(const bad_exception&) noexcept;

bad_exception& operator=(const bad_exception&) noexcept;

const char* what() const noexcept override;

};

}

The class bad_exception defines the type of the object referenced by the exception_ptr returned from a

call to current_exception (21.8.6) when the currently active exception object fails to copy.

bad_exception() noexcept;

Effects: Constructs an object of class bad_exception.

bad_exception(const bad_exception&) noexcept;

bad_exception& operator=(const bad_exception&) noexcept;

Effects: Copies an object of class bad_exception.

§ 21.8.3

458

const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

Remarks: The message may be a null-terminated multibyte string (20.4.2.1.5.2), suitable for conversion

and display as a wstring (24.3, 25.4.1.4).

21.8.4

Abnormal termination

[exception.terminate]

21.8.4.1

Type terminate_handler

[terminate.handler]

using terminate_handler = void (*)();

The type of a handler function to be called by std::terminate() when terminating exception process-

ing.

Required behavior: A terminate_handler shall terminate execution of the program without returning

to the caller.

Default behavior: The implementation’s default terminate_handler calls abort().

21.8.4.2

set_terminate

[set.terminate]

terminate_handler set_terminate(terminate_handler f) noexcept;

Effects: Establishes the function designated by f as the current handler function for terminating

exception processing.

Remarks: It is unspecified whether a null pointer value designates the default terminate_handler.

Returns: The previous terminate_handler.

21.8.4.3

get_terminate

[get.terminate]

terminate_handler get_terminate() noexcept;

Returns: The current terminate_handler. [ Note: This may be a null pointer value.

— end note ]

21.8.4.4

terminate

[terminate]

[[noreturn]] void terminate() noexcept;

Remarks: Called by the implementation when exception handling must be abandoned for any of several

reasons (18.5.1). May also be called directly by the program.

Effects: Calls a terminate_handler function. It is unspecified which terminate_handler function

will be called if an exception is active during a call to set_terminate. Otherwise calls the current

terminate_handler function. [ Note: A default terminate_handler is always considered a callable

handler in this context.

— end note ]

21.8.5

uncaught_exceptions

[uncaught.exceptions]

int uncaught_exceptions() noexcept;

Returns: The number of uncaught exceptions (18.5.2).

Remarks: When uncaught_exceptions() > 0, throwing an exception can result in a call of

std::terminate() (18.5.1).

21.8.6

Exception propagation

[propagation]

using exception_ptr = unspecified ;

The type exception_ptr can be used to refer to an exception object.

exception_ptr shall satisfy the requirements of NullablePointer (20.5.3.3).

Two non-null values of type exception_ptr are equivalent and compare equal if and only if they refer

to the same exception.

The default constructor of exception_ptr produces the null value of the type.

exception_ptr shall not be implicitly convertible to any arithmetic, enumeration, or pointer type.

[Note: An implementation might use a reference-counted smart pointer as exception_ptr.

— end

note ]

§ 21.8.6

459

For purposes of determining the presence of a data race, operations on exception_ptr objects shall

access and modify only the exception_ptr objects themselves and not the exceptions they refer to.

Use of rethrow_exception on exception_ptr objects that refer to the same exception object shall

not introduce a data race. [ Note: If rethrow_exception rethrows the same exception object (rather

than a copy), concurrent access to that rethrown exception object may introduce a data race. Changes

in the number of exception_ptr objects that refer to a particular exception do not introduce a data

race.

— end note ]

exception_ptr current_exception() noexcept;

Returns: An exception_ptr object that refers to the currently handled exception (18.3) or a copy of

the currently handled exception, or a null exception_ptr object if no exception is being handled. The

referenced object shall remain valid at least as long as there is an exception_ptr object that refers to it.

If the function needs to allocate memory and the attempt fails, it returns an exception_ptr object that

refers to an instance of bad_alloc. It is unspecified whether the return values of two successive calls

to current_exception refer to the same exception object. [Note: That is, it is unspecified whether

current_exception creates a new copy each time it is called.

— end note ] If the attempt to copy

the current exception object throws an exception, the function returns an exception_ptr object that

refers to the thrown exception or, if this is not possible, to an instance of bad_exception. [ Note: The

copy constructor of the thrown exception may also fail, so the implementation is allowed to substitute

a bad_exception object to avoid infinite recursion. — end note ]

[[noreturn]] void rethrow_exception(exception_ptr p);

Requires: p shall not be a null pointer.

Throws: The exception object to which p refers.

template<class E> exception_ptr make_exception_ptr(E e) noexcept;

Effects: Creates an exception_ptr object that refers to a copy of e, as if:

try {

throw e;

} catch(...) {

return current_exception();

}

[ Note: This function is provided for convenience and efficiency reasons.

— end note ]

21.8.7

nested_exception

[except.nested]

namespace std {

class nested_exception {

public:

nested_exception() noexcept;

nested_exception(const nested_exception&) noexcept = default;

nested_exception& operator=(const nested_exception&) noexcept = default;

virtual ~nested_exception() = default;

// access functions

[[noreturn]] void rethrow_nested() const;

exception_ptr nested_ptr() const noexcept;

};

template<class T> [[noreturn]] void throw_with_nested(T&& t);

template<class E> void rethrow_if_nested(const E& e);

}

The class nested_exception is designed for use as a mixin through multiple inheritance. It captures the

currently handled exception and stores it for later use.

[ Note: nested_exception has a virtual destructor to make it a polymorphic class. Its presence can be tested

for with dynamic_cast.

— end note ]

nested_exception() noexcept;

Effects: The constructor calls current_exception() and stores the returned value.

§ 21.8.7

460

[[noreturn]] void rethrow_nested() const;

Effects: If nested_ptr() returns a null pointer, the function calls std::terminate(). Otherwise, it

throws the stored exception captured by *this.

exception_ptr nested_ptr() const noexcept;

Returns: The stored exception captured by this nested_exception object.

template<class T> [[noreturn]] void throw_with_nested(T&& t);

Let U be decay_t<T>.

Requires: U shall be CopyConstructible.

Throws: If is_class_v<U> && !is_final_v<U> && !is_base_of_v<nested_exception, U> is true,

an exception of unspecified type that is publicly derived from both U and nested_exception and

constructed from std::forward<T>(t), otherwise std::forward<T>(t).

template<class E> void rethrow_if_nested(const E& e);

Effects: If E is not a polymorphic class type, or if nested_exception is an inaccessible or ambiguous

base class of E, there is no effect. Otherwise, performs:

if (auto p = dynamic_cast<const nested_exception*>(addressof(e)))

p->rethrow_nested();

21.9

Initializer lists

[support.initlist]

The header <initializer_list> defines a class template and several support functions related to list-

initialization (see 11.6.4). All functions specified in this subclause are signal-safe (21.11.4).

21.9.1

Header <initializer_list> synopsis

[initializer_list.syn]

namespace std {

template<class E> class initializer_list {

public:

using value_type

= E;

using reference

= const E&;

using const_reference = const E&;

using size_type

= size_t;

using iterator

= const E*;

using const_iterator

= const E*;

constexpr initializer_list() noexcept;

constexpr size_t size() const noexcept;

// number of elements

constexpr const E* begin() const noexcept;

// first element

constexpr const E* end() const noexcept;

// one past the last element

};

// 21.9.4, initializer list range access

template<class E> constexpr const E* begin(initializer_list<E> il) noexcept;

template<class E> constexpr const E* end(initializer_list<E> il) noexcept;

}

An object of type initializer_list<E> provides access to an array of objects of type const E. [Note:

A pair of pointers or a pointer plus a length would be obvious representations for initializer_list.

initializer_list is used to implement initializer lists as specified in 11.6.4. Copying an initializer list does

not copy the underlying elements.

— end note ]

If an explicit specialization or partial specialization of initializer_list is declared, the program is

ill-formed.

21.9.2

Initializer list constructors

[support.initlist.cons]

constexpr initializer_list() noexcept;

Effects: Constructs an empty initializer_list object.

§ 21.9.2

461

Postconditions: size() == 0.

21.9.3

Initializer list access

[support.initlist.access]

constexpr const E* begin() const noexcept;

Returns: A pointer to the beginning of the array. If size() == 0 the values of begin() and end()

are unspecified but they shall be identical.

constexpr const E* end() const noexcept;

Returns: begin() + size().

constexpr size_t size() const noexcept;

Returns: The number of elements in the array.

Complexity: Constant time.

21.9.4

Initializer list range access

[support.initlist.range]

template<class E> constexpr const E* begin(initializer_list<E> il) noexcept;

Returns: il.begin().

template<class E> constexpr const E* end(initializer_list<E> il) noexcept;

Returns: il.end().

21.10

Comparisons

[cmp]

21.10.1

Header <compare> synopsis

[cmp.syn]

The header <compare> specifies types, objects, and functions for use primarily in connection with the

three-way comparison operator (8.5.8).

namespace std {

// 21.10.2, comparison category types

class weak_equality;

class strong_equality;

class partial_ordering;

class weak_ordering;

class strong_ordering;

// named comparison functions

constexpr bool is_eq

(weak_equality cmp) noexcept

{ return cmp == 0; }

constexpr bool is_neq (weak_equality cmp) noexcept

{ return cmp != 0; }

constexpr bool is_lt

(partial_ordering cmp) noexcept { return cmp < 0; }

constexpr bool is_lteq(partial_ordering cmp) noexcept { return cmp <= 0; }

constexpr bool is_gt

(partial_ordering cmp) noexcept { return cmp > 0; }

constexpr bool is_gteq(partial_ordering cmp) noexcept { return cmp >= 0; }

// 21.10.3, common comparison category type

template<class... Ts>

struct common_comparison_category {

using type = see below ;

};

template<class... Ts>

using common_comparison_category_t = typename common_comparison_category<Ts...>::type;

// 21.10.4, comparison algorithms

template<class T> constexpr strong_ordering strong_order(const T& a, const T& b);

template<class T> constexpr weak_ordering weak_order(const T& a, const T& b);

template<class T> constexpr partial_ordering partial_order(const T& a, const T& b);

template<class T> constexpr strong_equality strong_equal(const T& a, const T& b);

template<class T> constexpr weak_equality weak_equal(const T& a, const T& b);

}

§ 21.10.1

462

21.10.2

Comparison category types

[cmp.categories]

21.10.2.1

Preamble

[cmp.categories.pre]

The types weak_equality, strong_equality, partial_ordering, weak_ordering, and strong_ordering

are collectively termed the comparison category types. Each is specified in terms of an exposition-only data

member named value whose value typically corresponds to that of an enumerator from one of the following

exposition-only enumerations:

enum class eq { equal = 0, equivalent = equal,

nonequal = 1, nonequivalent = nonequal };

// exposition only

enum class ord { less = -1, greater = 1 };

// exposition only

enum class ncmp { unordered = -127 };

// exposition only

[ Note: The types strong_ordering and weak_equality correspond, respectively, to the terms total ordering

and equivalence in mathematics.

— end note ]

The relational and equality operators for the comparison category types are specified with an anonymous

parameter of unspecified type. This type shall be selected by the implementation such that these parameters

can accept literal 0 as a corresponding argument. [Example: nullptr_t satisfies this requirement.

— end

example ] In this context, the behavior of a program that supplies an argument other than a literal 0 is

undefined.

For the purposes of this subclause, substitutability is the property that f(a) == f(b) is true whenever a

== b is true, where f denotes a function that reads only comparison-salient state that is accessible via the

argument’s public const members.

21.10.2.2

Class weak_equality

[cmp.weakeq]

The weak_equality type is typically used as the result type of a three-way comparison operator (8.5.8) that

(a) admits only equality and inequality comparisons, and (b) does not imply substitutability.

namespace std {

class weak_equality {

int value;

// exposition only

// exposition-only constructor

explicit constexpr weak_equality(eq v) noexcept : value(int(v)) {}

// exposition only

public:

// valid values

static const weak_equality equivalent;

static const weak_equality nonequivalent;

// comparisons

friend constexpr bool operator==(weak_equality v, unspecified ) noexcept;

friend constexpr bool operator!=(weak_equality v, unspecified ) noexcept;

friend constexpr bool operator==(unspecified , weak_equality v) noexcept;

friend constexpr bool operator!=(unspecified , weak_equality v) noexcept;

};

// valid values’ definitions

inline constexpr weak_equality weak_equality::equivalent(eq::equivalent);

inline constexpr weak_equality weak_equality::nonequivalent(eq::nonequivalent);

}

constexpr bool operator==(weak_equality v, unspecified ) noexcept;

constexpr bool operator==(unspecified , weak_equality v) noexcept;

Returns: v.value == 0.

constexpr bool operator!=(weak_equality v, unspecified ) noexcept;

constexpr bool operator!=(unspecified , weak_equality v) noexcept;

Returns: v.value != 0.

21.10.2.3

Class strong_equality

[cmp.strongeq]

The strong_equality type is typically used as the result type of a three-way comparison operator (8.5.8)

that (a) admits only equality and inequality comparisons, and (b) does imply substitutability.

§ 21.10.2.3

463

namespace std {

class strong_equality {

int value;

// exposition only

// exposition-only constructor

explicit constexpr strong_equality(eq v) noexcept : value(int(v)) {}

// exposition only

public:

// valid values

static const strong_equality equal;

static const strong_equality nonequal;

static const strong_equality equivalent;

static const strong_equality nonequivalent;

// conversion

constexpr operator weak_equality() const noexcept;

// comparisons

friend constexpr bool operator==(strong_equality v, unspecified ) noexcept;

friend constexpr bool operator!=(strong_equality v, unspecified ) noexcept;

friend constexpr bool operator==(unspecified , strong_equality v) noexcept;

friend constexpr bool operator!=(unspecified , strong_equality v) noexcept;

};

// valid values’ definitions

inline constexpr strong_equality strong_equality::equal(eq::equal);

inline constexpr strong_equality strong_equality::nonequal(eq::nonequal);

inline constexpr strong_equality strong_equality::equivalent(eq::equivalent);

inline constexpr strong_equality strong_equality::nonequivalent(eq::nonequivalent);

}

constexpr operator weak_equality() const noexcept;

Returns: value == 0 ? weak_equality::equivalent : weak_equality::nonequivalent.

constexpr bool operator==(strong_equality v, unspecified ) noexcept;

constexpr bool operator==(unspecified , strong_equality v) noexcept;

Returns: v.value == 0.

constexpr bool operator!=(strong_equality v, unspecified ) noexcept;

constexpr bool operator!=(unspecified , strong_equality v) noexcept;

Returns: v.value != 0.

21.10.2.4

Class partial_ordering

[cmp.partialord]

The partial_ordering type is typically used as the result type of a three-way comparison operator (8.5.8)

that (a) admits all of the six two-way comparison operators (8.5.9, 8.5.10), (b) does not imply substitutability,

and (c) permits two values to be incomparable.²²²

namespace std {

class partial_ordering {

int value;

// exposition only

bool is_ordered;

// exposition only

// exposition-only constructors

explicit constexpr

partial_ordering(eq v) noexcept : value(int(v)), is_ordered(true) {}

// exposition only

explicit constexpr

partial_ordering(ord v) noexcept : value(int(v)), is_ordered(true) {}

// exposition only

explicit constexpr

partial_ordering(ncmp v) noexcept : value(int(v)), is_ordered(false) {}

// exposition only

222) That is, a < b, a == b, and a > b might all be false.

§ 21.10.2.4

464

public:

// valid values

static const partial_ordering less;

static const partial_ordering equivalent;

static const partial_ordering greater;

static const partial_ordering unordered;

// conversion

constexpr operator weak_equality() const noexcept;

// comparisons

friend constexpr bool operator==(partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator!=(partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator< (partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator<=(partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator> (partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator>=(partial_ordering v, unspecified ) noexcept;

friend constexpr bool operator==(unspecified , partial_ordering v) noexcept;

friend constexpr bool operator!=(unspecified , partial_ordering v) noexcept;

friend constexpr bool operator< (unspecified , partial_ordering v) noexcept;

friend constexpr bool operator<=(unspecified , partial_ordering v) noexcept;

friend constexpr bool operator> (unspecified , partial_ordering v) noexcept;

friend constexpr bool operator>=(unspecified , partial_ordering v) noexcept;

};

// valid values’ definitions

inline constexpr partial_ordering partial_ordering::less(ord::less);

inline constexpr partial_ordering partial_ordering::equivalent(eq::equivalent);

inline constexpr partial_ordering partial_ordering::greater(ord::greater);

inline constexpr partial_ordering partial_ordering::unordered(ncmp::unordered);

}

constexpr operator weak_equality() const noexcept;

Returns: value == 0 ? weak_equality::equivalent : weak_equality::nonequivalent.

[Note:

The result is independent of the is_ordered member.

— end note ]

constexpr bool operator==(partial_ordering v, unspecified ) noexcept;

constexpr bool operator< (partial_ordering v, unspecified ) noexcept;

constexpr bool operator<=(partial_ordering v, unspecified ) noexcept;

constexpr bool operator> (partial_ordering v, unspecified ) noexcept;

constexpr bool operator>=(partial_ordering v, unspecified ) noexcept;

Returns: For operator@, v.is_ordered && v.value @ 0.

constexpr bool operator==(unspecified , partial_ordering v) noexcept;

constexpr bool operator< (unspecified , partial_ordering v) noexcept;

constexpr bool operator<=(unspecified , partial_ordering v) noexcept;

constexpr bool operator> (unspecified , partial_ordering v) noexcept;

constexpr bool operator>=(unspecified , partial_ordering v) noexcept;

Returns: For operator@, v.is_ordered && 0 @ v.value.

constexpr bool operator!=(partial_ordering v, unspecified ) noexcept;

constexpr bool operator!=(unspecified , partial_ordering v) noexcept;

Returns: For operator@, !v.is_ordered || v.value != 0.

21.10.2.5

Class weak_ordering

[cmp.weakord]

The weak_ordering type is typically used as the result type of a three-way comparison operator (8.5.8) that

(a) admits all of the six two-way comparison operators (8.5.9, 8.5.10), and (b) does not imply substitutability.

namespace std {

class weak_ordering {

int value;

// exposition only

§ 21.10.2.5

465

// exposition-only constructors

explicit constexpr weak_ordering(eq v) noexcept : value(int(v)) {}

// exposition only

explicit constexpr weak_ordering(ord v) noexcept : value(int(v)) {} // exposition only

public:

// valid values

static const weak_ordering less;

static const weak_ordering equivalent;

static const weak_ordering greater;

// conversions

constexpr operator weak_equality() const noexcept;

constexpr operator partial_ordering() const noexcept;

// comparisons

friend constexpr bool operator==(weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator!=(weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator< (weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator<=(weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator> (weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator>=(weak_ordering v, unspecified ) noexcept;

friend constexpr bool operator==(unspecified , weak_ordering v) noexcept;

friend constexpr bool operator!=(unspecified , weak_ordering v) noexcept;

friend constexpr bool operator< (unspecified , weak_ordering v) noexcept;

friend constexpr bool operator<=(unspecified , weak_ordering v) noexcept;

friend constexpr bool operator> (unspecified , weak_ordering v) noexcept;

friend constexpr bool operator>=(unspecified , weak_ordering v) noexcept;

};

// valid values’ definitions

inline constexpr weak_ordering weak_ordering::less(ord::less);

inline constexpr weak_ordering weak_ordering::equivalent(eq::equivalent);

inline constexpr weak_ordering weak_ordering::greater(ord::greater);

}

constexpr operator weak_equality() const noexcept;

Returns: value == 0 ? weak_equality::equivalent : weak_equality::nonequivalent.

constexpr operator partial_ordering() const noexcept;

Returns:

value == 0 ? partial_ordering::equivalent :

value < 0

? partial_ordering::less :

partial_ordering::greater

constexpr bool operator==(weak_ordering v, unspecified ) noexcept;

constexpr bool operator!=(weak_ordering v, unspecified ) noexcept;

constexpr bool operator< (weak_ordering v, unspecified ) noexcept;

constexpr bool operator<=(weak_ordering v, unspecified ) noexcept;

constexpr bool operator> (weak_ordering v, unspecified ) noexcept;

constexpr bool operator>=(weak_ordering v, unspecified ) noexcept;

Returns: v.value @ 0 for operator@.

constexpr bool operator==(unspecified , weak_ordering v) noexcept;

constexpr bool operator!=(unspecified , weak_ordering v) noexcept;

constexpr bool operator< (unspecified , weak_ordering v) noexcept;

constexpr bool operator<=(unspecified , weak_ordering v) noexcept;

constexpr bool operator> (unspecified , weak_ordering v) noexcept;

constexpr bool operator>=(unspecified , weak_ordering v) noexcept;

Returns: 0 @ v.value for operator@.

§ 21.10.2.5

466

21.10.2.6

Class strong_ordering

[cmp.strongord]

The strong_ordering type is typically used as the result type of a three-way comparison operator (8.5.8)

that (a) admits all of the six two-way comparison operators (8.5.9, 8.5.10), and (b) does imply substitutability.

namespace std {

class strong_ordering {

int value;

// exposition only

// exposition-only constructors

explicit constexpr strong_ordering(eq v) noexcept : value(int(v)) {}

// exposition only

explicit constexpr strong_ordering(ord v) noexcept : value(int(v)) {}

// exposition only

public:

// valid values

static const strong_ordering less;

static const strong_ordering equal;

static const strong_ordering equivalent;

static const strong_ordering greater;

// conversions

constexpr operator weak_equality() const noexcept;

constexpr operator strong_equality() const noexcept;

constexpr operator partial_ordering() const noexcept;

constexpr operator weak_ordering() const noexcept;

// comparisons

friend constexpr bool operator==(strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator!=(strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator< (strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator<=(strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator> (strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator>=(strong_ordering v, unspecified ) noexcept;

friend constexpr bool operator==(unspecified , strong_ordering v) noexcept;

friend constexpr bool operator!=(unspecified , strong_ordering v) noexcept;

friend constexpr bool operator< (unspecified , strong_ordering v) noexcept;

friend constexpr bool operator<=(unspecified , strong_ordering v) noexcept;

friend constexpr bool operator> (unspecified , strong_ordering v) noexcept;

friend constexpr bool operator>=(unspecified , strong_ordering v) noexcept;

};

// valid values’ definitions

inline constexpr strong_ordering strong_ordering::less(ord::less);

inline constexpr strong_ordering strong_ordering::equal(eq::equal);

inline constexpr strong_ordering strong_ordering::equivalent(eq::equivalent);

inline constexpr strong_ordering strong_ordering::greater(ord::greater);

}

constexpr operator weak_equality() const noexcept;

Returns: value == 0 ? weak_equality::equivalent : weak_equality::nonequivalent.

constexpr operator strong_equality() const noexcept;

Returns: value == 0 ? strong_equality::equal : strong_equality::nonequal.

constexpr operator partial_ordering() const noexcept;

Returns:

value == 0 ? partial_ordering::equivalent :

value < 0

? partial_ordering::less :

partial_ordering::greater

constexpr operator weak_ordering() const noexcept;

Returns:

§ 21.10.2.6

467

value == 0 ? weak_ordering::equivalent :

value < 0

? weak_ordering::less :

weak_ordering::greater

constexpr bool operator==(strong_ordering v, unspecified ) noexcept;

constexpr bool operator!=(strong_ordering v, unspecified ) noexcept;

constexpr bool operator< (strong_ordering v, unspecified ) noexcept;

constexpr bool operator<=(strong_ordering v, unspecified ) noexcept;

constexpr bool operator> (strong_ordering v, unspecified ) noexcept;

constexpr bool operator>=(strong_ordering v, unspecified ) noexcept;

Returns: v.value @ 0 for operator@.

constexpr bool operator==(unspecified , strong_ordering v) noexcept;

constexpr bool operator!=(unspecified , strong_ordering v) noexcept;

constexpr bool operator< (unspecified , strong_ordering v) noexcept;

constexpr bool operator<=(unspecified , strong_ordering v) noexcept;

constexpr bool operator> (unspecified , strong_ordering v) noexcept;

constexpr bool operator>=(unspecified , strong_ordering v) noexcept;

Returns: 0 @ v.value for operator@.

21.10.3

Class template common_comparison_category

[cmp.common]

The type common_comparison_category provides an alias for the strongest comparison category to which

all of the template arguments can be converted. [ Note: A comparison category type is stronger than another

if they are distinct types and an instance of the former can be converted to an instance of the latter.

— end

note ]

template<class... Ts>

struct common_comparison_category {

using type = see below ;

};

Remarks: The member typedef-name type denotes the common comparison type (15.9.2) of Ts..., the

expanded parameter pack. [ Note: This is well-defined even if the expansion is empty or includes a type

that is not a comparison category type.

— end note ]

21.10.4

Comparison algorithms

[cmp.alg]

template<class T> constexpr strong_ordering strong_order(const T& a, const T& b);

Effects: Compares two values and produces a result of type strong_ordering:

(1.1)

—

If numeric_limits<T>::is_iec559 is true, returns a result of type strong_ordering that is

consistent with the totalOrder operation as specified in ISO/IEC/IEEE 60559.

(1.2)

—

Otherwise, returns a <=> b if that expression is well-formed and convertible to strong_ordering.

(1.3)

—

Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.

(1.4)

—

Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool,

then

(1.4.1)

—

if a

== b is true, returns strong_ordering::equal;

(1.4.2)

—

otherwise, if a < b is true, returns strong_ordering::less;

(1.4.3)

—

otherwise, returns strong_ordering::greater.

(1.5)

—

Otherwise, the function is defined as deleted.

template<class T> constexpr weak_ordering weak_order(const T& a, const T& b);

Effects: Compares two values and produces a result of type weak_ordering:

(2.1)

—

Returns a <=> b if that expression is well-formed and convertible to weak_ordering.

(2.2)

—

Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.

(2.3)

—

Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool,

then

(2.3.1)

—

if a

== b is true, returns weak_ordering::equivalent;

§ 21.10.4

468

(2.3.2)

—

otherwise, if a < b is true, returns weak_ordering::less;

(2.3.3)

—

otherwise, returns weak_ordering::greater.

(2.4)

—

Otherwise, the function is defined as deleted.

template<class T> constexpr partial_ordering partial_order(const T& a, const T& b);

Effects: Compares two values and produces a result of type partial_ordering:

(3.1)

—

Returns a <=> b if that expression is well-formed and convertible to partial_ordering.

(3.2)

—

Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.

(3.3)

—

Otherwise, if the expressions a == b and a < b are each well-formed and convertible to bool,

then

(3.3.1)

—

if a

== b is true, returns partial_ordering::equivalent;

(3.3.2)

—

otherwise, if a < b is true, returns partial_ordering::less;

(3.3.3)

—

otherwise, returns partial_ordering::greater.

(3.4)

—

Otherwise, the function is defined as deleted.

template<class T> constexpr strong_equality strong_equal(const T& a, const T& b);

Effects: Compares two values and produces a result of type strong_equality:

(4.1)

—

Returns a <=> b if that expression is well-formed and convertible to strong_equality.

(4.2)

—

Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.

(4.3)

—

Otherwise, if the expression a == b is well-formed and convertible to bool, then

(4.3.1)

—

if a

== b is true, returns strong_equality::equal;

(4.3.2)

—

otherwise, returns strong_equality::nonequal.

(4.4)

—

Otherwise, the function is defined as deleted.

template<class T> constexpr weak_equality weak_equal(const T& a, const T& b);

Effects: Compares two values and produces a result of type weak_equality:

(5.1)

—

Returns a <=> b if that expression is well-formed and convertible to weak_equality.

(5.2)

—

Otherwise, if the expression a <=> b is well-formed, then the function is defined as deleted.

(5.3)

—

Otherwise, if the expression a == b is well-formed and convertible to bool, then

(5.3.1)

—

if a

== b is true, returns weak_equality::equivalent;

(5.3.2)

—

otherwise, returns weak_equality::nonequivalent.

(5.4)

—

Otherwise, the function is defined as deleted.

21.11

Other runtime support

[support.runtime]

Headers <csetjmp> (nonlocal jumps), <csignal> (signal handling), <cstdarg> (variable arguments), and

<cstdlib> (runtime environment getenv, system), provide further compatibility with C code.

Calls to the function getenv (21.2.2) shall not introduce a data race (20.5.5.9) provided that nothing modifies

the environment. [ Note: Calls to the POSIX functions setenv and putenv modify the environment.

— end

note ]

A call to the setlocale function (25.5) may introduce a data race with other calls to the setlocale function

or with calls to functions that are affected by the current C locale. The implementation shall behave as if no

library function other than locale::global calls the setlocale function.

21.11.1

Header <cstdarg> synopsis

[cstdarg.syn]

namespace std {

using va_list = see below ;

}

§ 21.11.1

469

#define va_arg(V, P) see below

#define va_copy(VDST, VSRC) see below

#define va_end(V) see below

#define va_start(V, P) see below

The contents of the header <cstdarg> are the same as the C standard library header <stdarg.h>, with the

following changes: The restrictions that ISO C places on the second parameter to the va_start macro in

header <stdarg.h> are different in this document. The parameter parmN is the rightmost parameter in the

variable parameter list of the function definition (the one just before the ...).²²³ If the parameter parmN is a

pack expansion (17.6.3) or an entity resulting from a lambda capture (8.4.5), the program is ill-formed, no

diagnostic required. If the parameter parmN is of a reference type, or of a type that is not compatible with

the type that results when passing an argument for which there is no parameter, the behavior is undefined.

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