17 Language support library [support]

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 contract-violation handling, support for exception processing, support for initializer lists, and other runtime support, as summarized in Table 42 .

Table 42 — Language support library summary [tab:support.summary]

🔗	Subclause	Header
🔗 [support.types]	Common definitions	<cstddef>, <cstdlib>
🔗 [support.limits]	Implementation properties	<cfloat>, <climits>, <limits>, <version>
🔗 [support.arith.types]	Arithmetic types	<cstdint>, <stdfloat>
🔗 [support.start.term]	Start and termination	<cstdlib>
🔗 [support.dynamic]	Dynamic memory management	<new>
🔗 [support.rtti]	Type identification	<typeinfo>, <typeindex>
🔗 [support.srcloc]	Source location	<source_location>
🔗 [support.exception]	Exception handling	<exception>
🔗 [support.contract]	Contract-violation handling	<contracts>
🔗 [support.initlist]	Initializer lists	<initializer_list>
🔗 [cmp]	Comparisons	<compare>
🔗 [support.coroutine]	Coroutines	<coroutine>
🔗 [support.runtime]	Other runtime support	<csetjmp>, <csignal>, <cstdarg>, <cstdlib>

17.2 Common definitions [support.types]

17.2.1 Header <cstddef> synopsis [cstddef.syn]

// all freestanding 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 {}; // [support.types.byteops], 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; 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 are the same as the C standard library header <stddef.h>, except that it does not declare the type wchar_t, that it does not define the macro unreachable, that it also declares the type byte and its associated operations ([support.types.byteops]), and as noted in [support.types.nullptr] and [support.types.layout].

See also: ISO/IEC 9899:2024, 7.22

17.2.2 Header <cstdlib> synopsis [cstdlib.syn]

🔗

namespace std { using size_t = see below; // freestanding using div_t = see below; // freestanding using ldiv_t = see below; // freestanding using lldiv_t = see below; // freestanding } #define NULL see below // freestanding #define EXIT_FAILURE see below // freestanding #define EXIT_SUCCESS see below // freestanding #define RAND_MAX see below #define MB_CUR_MAX see below namespace std { // Exposition-only function type aliases extern "C" using c-atexit-handler = void(); // exposition only extern "C++" using atexit-handler = void(); // exposition only extern "C" using c-compare-pred = int(const void*, const void*); // exposition only extern "C++" using compare-pred = int(const void*, const void*); // exposition only // [support.start.term], start and termination [[noreturn]] void abort() noexcept; // freestanding int atexit(c-atexit-handler* func) noexcept; // freestanding int atexit(atexit-handler* func) noexcept; // freestanding int at_quick_exit(c-atexit-handler* func) noexcept; // freestanding int at_quick_exit(atexit-handler* func) noexcept; // freestanding [[noreturn]] void exit(int status); // freestanding [[noreturn]] void _Exit(int status) noexcept; // freestanding [[noreturn]] void quick_exit(int status) noexcept; // freestanding char* getenv(const char* name); int system(const char* string); // [c.malloc], C library memory allocation void* aligned_alloc(size_t alignment, size_t size); void* calloc(size_t nmemb, size_t size); void free(void* ptr); void free_sized(void* ptr, size_t size); void free_aligned_sized(void* ptr, size_t alignment, size_t size); void* malloc(size_t size); void* realloc(void* ptr, size_t size); size_t memalignment(const void* p); // freestanding double atof(const char* nptr); int atoi(const char* nptr); long int atol(const char* nptr); long long int atoll(const char* nptr); double strtod(const char* nptr, char** endptr); int strfromd(char* s, size_t n, const char* format, double fp); int strfromf(char* s, size_t n, const char* format, float fp); int strfroml(char* s, size_t n, const char* format, long double fp); float strtof(const char* nptr, char** endptr); long double strtold(const char* nptr, char** endptr); long int strtol(const char* nptr, char** endptr, int base); long long int strtoll(const char* nptr, char** endptr, int base); unsigned long int strtoul(const char* nptr, char** endptr, int base); unsigned long long int strtoull(const char* nptr, char** endptr, int base); // [c.mb.wcs], multibyte / wide string and character conversion functions int mblen(const char* s, size_t n); int mbtowc(wchar_t* pwc, const char* s, size_t n); int wctomb(char* s, wchar_t wchar); size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n); size_t wcstombs(char* s, const wchar_t* pwcs, size_t n); // [alg.c.library], C standard library algorithms void* bsearch(const void* key, void* base, size_t nmemb, size_t size, // freestanding c-compare-pred* compar); void* bsearch(const void* key, void* base, size_t nmemb, size_t size, // freestanding compare-pred* compar); const void* bsearch(const void* key, const void* base, size_t nmemb, // freestanding size_t size, c-compare-pred* compar); const void* bsearch(const void* key, const void* base, size_t nmemb, // freestanding size_t size, compare-pred* compar); void qsort(void* base, size_t nmemb, size_t size, c-compare-pred* compar); // freestanding void qsort(void* base, size_t nmemb, size_t size, compare-pred* compar); // freestanding // [c.math.rand], low-quality random number generation int rand(); void srand(unsigned int seed); // [c.math.abs], absolute values constexpr int abs(int j); // freestanding constexpr long int abs(long int j); // freestanding constexpr long long int abs(long long int j); // freestanding constexpr floating-point-type abs(floating-point-type j); // freestanding-deleted constexpr long int labs(long int j); // freestanding constexpr long long int llabs(long long int j); // freestanding constexpr div_t div(int numer, int denom); // freestanding constexpr ldiv_t div(long int numer, long int denom); // freestanding; see [library.c] constexpr lldiv_t div(long long int numer, long long int denom); // freestanding; see [library.c] constexpr ldiv_t ldiv(long int numer, long int denom); // freestanding constexpr lldiv_t lldiv(long long int numer, long long int denom); // freestanding }

The contents and meaning of the header <cstdlib> are the same as the C standard library header <stdlib.h>, except that it does not declare the types wchar_t or once_flag, and does not declare the function call_once, and except as noted in [support.types.nullptr], [support.types.layout], [support.start.term], [c.malloc], [c.mb.wcs], [alg.c.library], [c.math.rand], and [c.math.abs].

[Note 1:

Several functions have additional overloads in this document, but they have the same behavior as in the C standard library .

— end note]

17.2.3 Null pointers [support.types.nullptr]

The type nullptr_t is a synonym for the type of a nullptr expression, and it has the characteristics described in [basic.fundamental] and [conv.ptr].

[Note 1:

Although nullptr's address cannot be taken, the address of another nullptr_t object that is an lvalue can be taken.

— end note]

The macro NULL is an implementation-defined null pointer constant.159

See also: ISO/IEC 9899:2024, 7.22

159)159)

Possible definitions include 0 and 0L, but not (void*)0.

17.2.4 Sizes, alignments, and offsets [support.types.layout]

The macro offsetof(type, member-designator) has the same semantics as the corresponding macro in the C standard library header <stddef.h>, but accepts a restricted set of type arguments in this document.

Use of the offsetof macro with a type other than a standard-layout class ([class.prop]) is conditionally-supported.160

The expression offsetof(type, member-designator) is never type-dependent and it is value-dependent if and only if type is dependent.

The result of applying the offsetof macro to a static data member or a function member is undefined.

No operation invoked by the offsetof macro shall throw an exception and noexcept(offsetof(type, member-designator)) shall be true.

The type ptrdiff_t is an implementation-defined signed integer type that can hold the difference of two subscripts in an array object, as described in [expr.add].

The type size_t is an implementation-defined unsigned integer type that is large enough to contain the size in bytes of any object ([expr.sizeof]).

Recommended practice: An implementation should choose types for ptrdiff_t and size_t whose integer conversion ranks ([conv.rank]) are no greater than that of signed long int unless a larger size is necessary to contain all the possible values.

The type max_align_t is a trivially copyable standard-layout type whose alignment requirement is at least as great as that of every scalar type, and whose alignment requirement is supported in every context ([basic.align]).

std::is_trivially_default_constructible_v<max_align_t> is true.

See also: ISO/IEC 9899:2024, 7.22

160)160)

Note that offsetof is required to work as specified even if unary operator& is overloaded for any of the types involved.

17.2.5 byte type operations [support.types.byteops]

🔗

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

Constraints: is_integral_v<IntType> is true.

Effects: Equivalent to: return b = b << shift;

🔗

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

Constraints: is_integral_v<IntType> is true.

Effects: Equivalent to: return static_cast<byte>(static_cast<unsigned int>(b) << shift);

🔗

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

Constraints: is_integral_v<IntType> is true.

Effects: Equivalent to: return b = b >> shift;

🔗

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

Constraints: is_integral_v<IntType> is true.

Effects: Equivalent to: return static_cast<byte>(static_cast<unsigned int>(b) >> shift);

🔗

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

Effects: Equivalent to: return l = l | r;

🔗

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

Effects: Equivalent to: return static_cast<byte>(static_cast<unsigned int>(l) | static_cast<unsigned int>(r));

🔗

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

Effects: Equivalent to: return l = l & r;

🔗

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

Effects: Equivalent to: return static_cast<byte>(static_cast<unsigned int>(l) & static_cast<unsigned int>(r));

🔗

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

Effects: Equivalent to: return l = l ^ r;

🔗

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

Effects: Equivalent to: return static_cast<byte>(static_cast<unsigned int>(l) ^ static_cast<unsigned int>(r));

🔗

constexpr byte operator~(byte b) noexcept;

Effects: Equivalent to: return static_cast<byte>(~static_cast<unsigned int>(b));

🔗

template<class IntType>
  constexpr IntType to_integer(byte b) noexcept;

Constraints: is_integral_v<IntType> is true.

Effects: Equivalent to: return static_cast<IntType>(b);

17.3 Implementation properties [support.limits]

17.3.1 General [support.limits.general]

The headers <limits>, <climits>, and <cfloat> supply characteristics of implementation-dependent arithmetic types ([basic.fundamental]).

17.3.2 Header <version> synopsis [version.syn]

The header supplies implementation-dependent information about the C++ standard library (e.g., version number and release date).

Each of the macros defined in <version> is also defined after inclusion of any member of the set of library headers indicated in the corresponding comment in this synopsis.

[Note 1:

Future revisions of this document might replace the values of these macros with greater values.

— end note]

#define __cpp_lib_adaptor_iterator_pair_constructor 202106L // also in <stack>, <queue> #define __cpp_lib_addressof_constexpr 201603L // freestanding, also in <memory> #define __cpp_lib_algorithm_default_value_type 202403L // also in <algorithm>, <ranges>, <string>, <deque>, <list>, <forward_list>, <vector> #define __cpp_lib_algorithm_iterator_requirements 202207L // also in <algorithm>, <numeric>, <memory> #define __cpp_lib_aligned_accessor 202411L // also in <mdspan> #define __cpp_lib_allocate_at_least 202302L // also in <memory> #define __cpp_lib_allocator_traits_is_always_equal 201411L // freestanding, also in <memory>, <scoped_allocator>, <string>, <deque>, <forward_list>, <list>, // <vector>, <map>, <set>, <unordered_map>, <unordered_set> #define __cpp_lib_any 201606L // also in <any> #define __cpp_lib_apply 202506L // freestanding, also in <tuple>, <type_traits> #define __cpp_lib_array_constexpr 201811L // also in <iterator>, <array> #define __cpp_lib_as_const 201510L // freestanding, also in <utility> #define __cpp_lib_associative_heterogeneous_erasure 202110L // also in <map>, <set>, <unordered_map>, <unordered_set> #define __cpp_lib_associative_heterogeneous_insertion 202306L // also in <map>, <set>, <unordered_map>, <unordered_set> #define __cpp_lib_assume_aligned 201811L // freestanding, also in <memory> #define __cpp_lib_atomic_flag_test 201907L // freestanding, also in <atomic> #define __cpp_lib_atomic_float 201711L // freestanding, also in <atomic> #define __cpp_lib_atomic_is_always_lock_free 201603L // freestanding, also in <atomic> #define __cpp_lib_atomic_lock_free_type_aliases 201907L // also in <atomic> #define __cpp_lib_atomic_min_max 202506L // freestanding, also in <atomic> #define __cpp_lib_atomic_reductions 202506L // freestanding, also in <atomic> #define __cpp_lib_atomic_ref 202411L // freestanding, also in <atomic> #define __cpp_lib_atomic_shared_ptr 201711L // also in <memory> #define __cpp_lib_atomic_value_initialization 201911L // freestanding, also in <atomic>, <memory> #define __cpp_lib_atomic_wait 201907L // freestanding, also in <atomic> #define __cpp_lib_barrier 202302L // also in <barrier> #define __cpp_lib_bind_back 202306L // freestanding, also in <functional> #define __cpp_lib_bind_front 202306L // freestanding, also in <functional> #define __cpp_lib_bit_cast 201806L // freestanding, also in <bit> #define __cpp_lib_bitops 201907L // freestanding, also in <bit> #define __cpp_lib_bitset 202306L // also in <bitset> #define __cpp_lib_bool_constant 201505L // freestanding, also in <type_traits> #define __cpp_lib_bounded_array_traits 201902L // freestanding, also in <type_traits> #define __cpp_lib_boyer_moore_searcher 201603L // also in <functional> #define __cpp_lib_byte 201603L // freestanding, also in <cstddef> #define __cpp_lib_byteswap 202110L // freestanding, also in <bit> #define __cpp_lib_char8_t 201907L // freestanding, also in <atomic>, <filesystem>, <istream>, <limits>, <locale>, <ostream>, <string>, // <string_view> #define __cpp_lib_chrono 202306L // also in <chrono> #define __cpp_lib_chrono_udls 201304L // also in <chrono> #define __cpp_lib_clamp 201603L // also in <algorithm> #define __cpp_lib_common_reference 202302L // freestanding, also in <type_traits> #define __cpp_lib_common_reference_wrapper 202302L // freestanding, also in <functional> #define __cpp_lib_complex_udls 201309L // also in <complex> #define __cpp_lib_concepts 202207L // freestanding, also in <concepts>, <compare> #define __cpp_lib_constant_wrapper 202506L // freestanding, also in <type_traits> #define __cpp_lib_constexpr_algorithms 202306L // also in <algorithm>, <utility> #define __cpp_lib_constexpr_atomic 202411L // also in <atomic> #define __cpp_lib_constexpr_bitset 202207L // also in <bitset> #define __cpp_lib_constexpr_charconv 202207L // freestanding, also in <charconv> #define __cpp_lib_constexpr_cmath 202306L // also in <cmath>, <cstdlib> #define __cpp_lib_constexpr_complex 202306L // also in <complex> #define __cpp_lib_constexpr_deque 202502L // also in <deque> #define __cpp_lib_constexpr_dynamic_alloc 201907L // also in <memory> #define __cpp_lib_constexpr_exceptions 202502L // also in <exception>, <stdexcept>, <expected>, <optional>, <variant>, and <format> #define __cpp_lib_constexpr_flat_map 202502L // also in <flat_map> #define __cpp_lib_constexpr_flat_set 202502L // also in <flat_set> #define __cpp_lib_constexpr_forward_list 202502L // also in <forward_list> #define __cpp_lib_constexpr_functional 201907L // freestanding, also in <functional> #define __cpp_lib_constexpr_inplace_vector 202502L // also in <inplace_vector> #define __cpp_lib_constexpr_iterator 201811L // freestanding, also in <iterator> #define __cpp_lib_constexpr_list 202502L // also in <list> #define __cpp_lib_constexpr_map 202502L // also in <map> #define __cpp_lib_constexpr_memory 202506L // freestanding, also in <memory> #define __cpp_lib_constexpr_new 202406L // freestanding, also in <new> #define __cpp_lib_constexpr_numeric 201911L // also in <numeric> #define __cpp_lib_constexpr_queue 202502L // also in <queue> #define __cpp_lib_constexpr_set 202502L // also in <set> #define __cpp_lib_constexpr_stack 202502L // also in <stack> #define __cpp_lib_constexpr_string 201907L // also in <string> #define __cpp_lib_constexpr_string_view 201811L // also in <string_view> #define __cpp_lib_constexpr_tuple 201811L // freestanding, also in <tuple> #define __cpp_lib_constexpr_typeinfo 202106L // freestanding, also in <typeinfo> #define __cpp_lib_constexpr_unordered_map 202502L // also in <unordered_map> #define __cpp_lib_constexpr_unordered_set 202502L // also in <unordered_set> #define __cpp_lib_constexpr_utility 201811L // freestanding, also in <utility> #define __cpp_lib_constexpr_vector 201907L // also in <vector> #define __cpp_lib_constrained_equality 202411L // freestanding, // also in <utility>, <tuple>, <optional>, <variant>, <expected> #define __cpp_lib_containers_ranges 202202L // also in <vector>, <list>, <forward_list>, <map>, <set>, <unordered_map>, <unordered_set>, // <deque>, <queue>, <stack>, <string> #define __cpp_lib_contracts 202502L // freestanding, also in <contracts> #define __cpp_lib_copyable_function 202306L // also in <functional> #define __cpp_lib_coroutine 201902L // freestanding, also in <coroutine> #define __cpp_lib_counting_scope 202506L // also in <execution> #define __cpp_lib_debugging 202403L // freestanding, also in <debugging> #define __cpp_lib_define_static 202506L // freestanding, also in <meta> #define __cpp_lib_destroying_delete 201806L // freestanding, also in <new> #define __cpp_lib_enable_shared_from_this 201603L // also in <memory> #define __cpp_lib_endian 201907L // freestanding, also in <bit> #define __cpp_lib_erase_if 202002L // also in <string>, <deque>, <forward_list>, <list>, <vector>, <map>, <set>, <unordered_map>, // <unordered_set> #define __cpp_lib_exception_ptr_cast 202506L // also in <exception> #define __cpp_lib_exchange_function 201304L // freestanding, also in <utility> #define __cpp_lib_execution 201902L // also in <execution> #define __cpp_lib_expected 202211L // also in <expected> #define __cpp_lib_filesystem 201703L // also in <filesystem> #define __cpp_lib_flat_map 202207L // also in <flat_map> #define __cpp_lib_flat_set 202207L // also in <flat_set> #define __cpp_lib_format 202311L // also in <format> #define __cpp_lib_format_ranges 202207L // also in <format> #define __cpp_lib_format_path 202506L // also in <filesystem> #define __cpp_lib_format_uchar 202311L // also in <format> #define __cpp_lib_formatters 202302L // also in <stacktrace>, <thread> #define __cpp_lib_forward_like 202207L // freestanding, also in <utility> #define __cpp_lib_freestanding_algorithm 202502L // freestanding, also in <algorithm> #define __cpp_lib_freestanding_array 202311L // freestanding, also in <array> #define __cpp_lib_freestanding_char_traits 202306L // freestanding, also in <string> #define __cpp_lib_freestanding_charconv 202306L // freestanding, also in <charconv> #define __cpp_lib_freestanding_cstdlib 202306L // freestanding, also in <cstdlib>, <cmath> #define __cpp_lib_freestanding_cstring 202311L // freestanding, also in <cstring> #define __cpp_lib_freestanding_cwchar 202306L // freestanding, also in <cwchar> #define __cpp_lib_freestanding_errc 202306L // freestanding, also in <cerrno>, <system_error> #define __cpp_lib_freestanding_execution 202502L // freestanding, also in <execution> #define __cpp_lib_freestanding_expected 202311L // freestanding, also in <expected> #define __cpp_lib_freestanding_feature_test_macros 202306L // freestanding #define __cpp_lib_freestanding_functional 202306L // freestanding, also in <functional> #define __cpp_lib_freestanding_iterator 202306L // freestanding, also in <iterator> #define __cpp_lib_freestanding_mdspan 202311L // freestanding, also in <mdspan> #define __cpp_lib_freestanding_memory 202502L // freestanding, also in <memory> #define __cpp_lib_freestanding_numeric 202502L // freestanding, also in <numeric> #define __cpp_lib_freestanding_operator_new see below // freestanding, also in <new> #define __cpp_lib_freestanding_optional 202506L // freestanding, also in <optional> #define __cpp_lib_freestanding_random 202502L // freestanding, also in <random> #define __cpp_lib_freestanding_ranges 202306L // freestanding, also in <ranges> #define __cpp_lib_freestanding_ratio 202306L // freestanding, also in <ratio> #define __cpp_lib_freestanding_string_view 202311L // freestanding, also in <string_view> #define __cpp_lib_freestanding_tuple 202306L // freestanding, also in <tuple> #define __cpp_lib_freestanding_utility 202306L // freestanding, also in <utility> #define __cpp_lib_freestanding_variant 202311L // freestanding, also in <variant> #define __cpp_lib_fstream_native_handle 202306L // also in <fstream> #define __cpp_lib_function_ref 202306L // also in <functional> #define __cpp_lib_gcd_lcm 201606L // also in <numeric> #define __cpp_lib_generator 202207L // also in <generator> #define __cpp_lib_generic_associative_lookup 201304L // also in <map>, <set> #define __cpp_lib_generic_unordered_lookup 201811L // also in <unordered_map>, <unordered_set> #define __cpp_lib_hardware_interference_size 201703L // freestanding, also in <new> #define __cpp_lib_has_unique_object_representations 201606L // freestanding, also in <type_traits> #define __cpp_lib_hazard_pointer 202306L // also in <hazard_pointer> #define __cpp_lib_hive 202502L // also in <hive> #define __cpp_lib_hypot 201603L // also in <cmath> #define __cpp_lib_incomplete_container_elements 201505L // also in <forward_list>, <list>, <vector> #define __cpp_lib_indirect 202502L // also in <memory> #define __cpp_lib_inplace_vector 202406L // also in <inplace_vector> #define __cpp_lib_int_pow2 202002L // freestanding, also in <bit> #define __cpp_lib_integer_comparison_functions 202002L // also in <utility> #define __cpp_lib_integer_sequence 201304L // freestanding, also in <utility> #define __cpp_lib_integral_constant_callable 201304L // freestanding, also in <type_traits> #define __cpp_lib_interpolate 201902L // also in <cmath>, <numeric> #define __cpp_lib_invoke 201411L // freestanding, also in <functional> #define __cpp_lib_invoke_r 202106L // freestanding, also in <functional> #define __cpp_lib_ios_noreplace 202207L // also in <ios> #define __cpp_lib_is_aggregate 201703L // freestanding, also in <type_traits> #define __cpp_lib_is_constant_evaluated 201811L // freestanding, also in <type_traits> #define __cpp_lib_is_final 201402L // freestanding, also in <type_traits> #define __cpp_lib_is_implicit_lifetime 202302L // freestanding, also in <type_traits> #define __cpp_lib_is_invocable 201703L // freestanding, also in <type_traits> #define __cpp_lib_is_layout_compatible 201907L // freestanding, also in <type_traits> #define __cpp_lib_is_nothrow_convertible 201806L // freestanding, also in <type_traits> #define __cpp_lib_is_null_pointer 201309L // freestanding, also in <type_traits> #define __cpp_lib_is_pointer_interconvertible 201907L // freestanding, also in <type_traits> #define __cpp_lib_is_scoped_enum 202011L // freestanding, also in <type_traits> #define __cpp_lib_is_sufficiently_aligned 202411L // also in <memory> #define __cpp_lib_is_swappable 201603L // freestanding, also in <type_traits> #define __cpp_lib_is_virtual_base_of 202406L // freestanding, also in <type_traits> #define __cpp_lib_is_within_lifetime 202306L // freestanding, also in <type_traits> #define __cpp_lib_jthread 201911L // also in <stop_token>, <thread> #define __cpp_lib_latch 201907L // also in <latch> #define __cpp_lib_launder 201606L // freestanding, also in <new> #define __cpp_lib_linalg 202412L // also in <linalg> #define __cpp_lib_list_remove_return_type 201806L // also in <forward_list>, <list> #define __cpp_lib_logical_traits 201510L // freestanding, also in <type_traits> #define __cpp_lib_make_from_tuple 201606L // freestanding, also in <tuple> #define __cpp_lib_make_reverse_iterator 201402L // freestanding, also in <iterator> #define __cpp_lib_make_unique 201304L // also in <memory> #define __cpp_lib_map_try_emplace 201411L // also in <map> #define __cpp_lib_math_constants 201907L // also in <numbers> #define __cpp_lib_math_special_functions 201603L // also in <cmath> #define __cpp_lib_mdspan 202406L // freestanding, also in <mdspan> #define __cpp_lib_memory_resource 201603L // also in <memory_resource> #define __cpp_lib_modules 202207L // freestanding #define __cpp_lib_move_iterator_concept 202207L // freestanding, also in <iterator> #define __cpp_lib_move_only_function 202110L // also in <functional> #define __cpp_lib_node_extract 201606L // also in <map>, <set>, <unordered_map>, <unordered_set> #define __cpp_lib_nonmember_container_access 201411L // freestanding, also in <array>, <deque>, <forward_list>, <iterator>, <list>, <map>, <regex>, <set>, // <string>, <unordered_map>, <unordered_set>, <vector> #define __cpp_lib_not_fn 202306L // freestanding, also in <functional> #define __cpp_lib_null_iterators 201304L // freestanding, also in <iterator> #define __cpp_lib_observable_checkpoint 202506L // freestanding, also in <utility> #define __cpp_lib_optional 202506L // also in <optional> #define __cpp_lib_optional_range_support 202406L // freestanding, also in <optional> #define __cpp_lib_out_ptr 202311L // freestanding, also in <memory> #define __cpp_lib_parallel_algorithm 202506L // also in <algorithm>, <numeric>, <memory> #define __cpp_lib_parallel_scheduler 202506L // also in <execution> #define __cpp_lib_philox_engine 202406L // also in <random> #define __cpp_lib_polymorphic 202502L // also in <memory> #define __cpp_lib_polymorphic_allocator 201902L // also in <memory_resource> #define __cpp_lib_print 202406L // also in <print>, <ostream> #define __cpp_lib_quoted_string_io 201304L // also in <iomanip> #define __cpp_lib_ranges 202406L // also in <algorithm>, <functional>, <iterator>, <memory>, <ranges> #define __cpp_lib_ranges_as_const 202311L // freestanding, also in <ranges> #define __cpp_lib_ranges_as_rvalue 202207L // freestanding, also in <ranges> #define __cpp_lib_ranges_cache_latest 202411L // freestanding, also in <ranges> #define __cpp_lib_ranges_cartesian_product 202207L // freestanding, also in <ranges> #define __cpp_lib_ranges_chunk 202202L // freestanding, also in <ranges> #define __cpp_lib_ranges_chunk_by 202202L // freestanding, also in <ranges> #define __cpp_lib_ranges_concat 202403L // freestanding, also in <ranges> #define __cpp_lib_ranges_contains 202207L // also in <algorithm> #define __cpp_lib_ranges_enumerate 202302L // also in <ranges> #define __cpp_lib_ranges_find_last 202207L // also in <algorithm> #define __cpp_lib_ranges_fold 202207L // also in <algorithm> #define __cpp_lib_ranges_generate_random 202403L // also in <random> #define __cpp_lib_ranges_indices 202506L // also in <ranges> #define __cpp_lib_ranges_iota 202202L // also in <numeric> #define __cpp_lib_ranges_join_with 202202L // freestanding, also in <ranges> #define __cpp_lib_ranges_repeat 202207L // freestanding, also in <ranges> #define __cpp_lib_ranges_reserve_hint 202502L // also in <ranges> #define __cpp_lib_ranges_slide 202202L // freestanding, also in <ranges> #define __cpp_lib_ranges_starts_ends_with 202106L // also in <algorithm> #define __cpp_lib_ranges_stride 202207L // freestanding, also in <ranges> #define __cpp_lib_ranges_to_container 202202L // freestanding, also in <ranges> #define __cpp_lib_ranges_to_input 202502L // freestanding, also in <ranges> #define __cpp_lib_ranges_zip 202110L // freestanding, also in <ranges>, <tuple>, <utility> #define __cpp_lib_ratio 202306L // freestanding, also in <ratio> #define __cpp_lib_raw_memory_algorithms 202411L // also in <memory> #define __cpp_lib_rcu 202306L // also in <rcu> #define __cpp_lib_reference_from_temporary 202202L // freestanding, also in <type_traits> #define __cpp_lib_reference_wrapper 202403L // freestanding, also in <functional> #define __cpp_lib_reflection 202506L // also in <meta> #define __cpp_lib_remove_cvref 201711L // freestanding, also in <type_traits> #define __cpp_lib_result_of_sfinae 201210L // freestanding, also in <functional>, <type_traits> #define __cpp_lib_robust_nonmodifying_seq_ops 201304L // also in <algorithm> #define __cpp_lib_sample 201603L // also in <algorithm> #define __cpp_lib_saturation_arithmetic 202311L // also in <numeric> #define __cpp_lib_scoped_lock 201703L // also in <mutex> #define __cpp_lib_semaphore 201907L // also in <semaphore> #define __cpp_lib_senders 202506L // also in <execution> #define __cpp_lib_shared_mutex 201505L // also in <shared_mutex> #define __cpp_lib_shared_ptr_arrays 201707L // also in <memory> #define __cpp_lib_shared_ptr_weak_type 201606L // also in <memory> #define __cpp_lib_shared_timed_mutex 201402L // also in <shared_mutex> #define __cpp_lib_shift 202202L // also in <algorithm> #define __cpp_lib_simd 202506L // also in <simd> #define __cpp_lib_simd_complex 202502L // also in <simd> #define __cpp_lib_simd_permutations 202506L // also in <simd> #define __cpp_lib_smart_ptr_for_overwrite 202002L // also in <memory> #define __cpp_lib_smart_ptr_owner_equality 202306L // also in <memory> #define __cpp_lib_source_location 201907L // freestanding, also in <source_location> #define __cpp_lib_span 202311L // freestanding, also in #define __cpp_lib_span_initializer_list 202311L // freestanding, also in #define __cpp_lib_spanstream 202106L // also in <spanstream> #define __cpp_lib_ssize 201902L // freestanding, also in <iterator> #define __cpp_lib_sstream_from_string_view 202306L // also in <sstream> #define __cpp_lib_stacktrace 202011L // also in <stacktrace> #define __cpp_lib_start_lifetime_as 202207L // freestanding, also in <memory> #define __cpp_lib_starts_ends_with 201711L // also in <string>, <string_view> #define __cpp_lib_stdatomic_h 202011L // also in <stdatomic.h> #define __cpp_lib_string_contains 202011L // also in <string>, <string_view> #define __cpp_lib_string_resize_and_overwrite 202110L // also in <string> #define __cpp_lib_string_subview 202506L // also in <string>, <string_view> #define __cpp_lib_string_udls 201304L // also in <string> #define __cpp_lib_string_view 202403L // also in <string>, <string_view> #define __cpp_lib_submdspan 202411L // freestanding, also in <mdspan> #define __cpp_lib_syncbuf 201803L // also in <syncstream> #define __cpp_lib_task 202506L // also in <execution> #define __cpp_lib_text_encoding 202306L // also in <text_encoding> #define __cpp_lib_three_way_comparison 201907L // freestanding, also in <compare> #define __cpp_lib_to_address 201711L // freestanding, also in <memory> #define __cpp_lib_to_array 201907L // freestanding, also in <array> #define __cpp_lib_to_chars 202306L // also in <charconv> #define __cpp_lib_to_string 202306L // also in <string> #define __cpp_lib_to_underlying 202102L // freestanding, also in <utility> #define __cpp_lib_transformation_trait_aliases 201304L // freestanding, also in <type_traits> #define __cpp_lib_transparent_operators 201510L // freestanding, also in <memory>, <functional> #define __cpp_lib_trivially_relocatable 202502L // freestanding, also in <memory>, <type_traits> #define __cpp_lib_tuple_element_t 201402L // freestanding, also in <tuple> #define __cpp_lib_tuple_like 202311L // also in <utility>, <tuple>, <map>, <unordered_map> #define __cpp_lib_tuples_by_type 201304L // freestanding, also in <utility>, <tuple> #define __cpp_lib_type_identity 201806L // freestanding, also in <type_traits> #define __cpp_lib_type_order 202506L // also in <compare> #define __cpp_lib_type_trait_variable_templates 201510L // freestanding, also in <type_traits> #define __cpp_lib_uncaught_exceptions 201411L // freestanding, also in <exception> #define __cpp_lib_unordered_map_try_emplace 201411L // also in <unordered_map> #define __cpp_lib_unreachable 202202L // freestanding, also in <utility> #define __cpp_lib_unwrap_ref 201811L // freestanding, also in <type_traits> #define __cpp_lib_variant 202306L // also in <variant> #define __cpp_lib_void_t 201411L // freestanding, also in <type_traits>

Additionally, each of the following macros is defined in a hardened implementation: #define __cpp_lib_hardened_array 202502L // also in <array> #define __cpp_lib_hardened_basic_stacktrace 202506L // also in <stacktrace> #define __cpp_lib_hardened_basic_string 202502L // also in <string> #define __cpp_lib_hardened_basic_string_view 202502L // also in <string_view> #define __cpp_lib_hardened_bitset 202502L // also in <bitset> #define __cpp_lib_hardened_common_iterator 202506L // also in <iterator> #define __cpp_lib_hardened_counted_iterator 202506L // also in <iterator> #define __cpp_lib_hardened_deque 202502L // also in <deque> #define __cpp_lib_hardened_expected 202502L // also in <expected> #define __cpp_lib_hardened_forward_list 202502L // also in <forward_list> #define __cpp_lib_hardened_inplace_vector 202502L // also in <inplace_vector> #define __cpp_lib_hardened_list 202502L // also in <list> #define __cpp_lib_hardened_mdspan 202502L // also in <mdspan> #define __cpp_lib_hardened_optional 202502L // also in <optional> #define __cpp_lib_hardened_shared_ptr_array 202506L // also in <memory> #define __cpp_lib_hardened_span 202502L // also in #define __cpp_lib_hardened_valarray 202502L // also in <valarray> #define __cpp_lib_hardened_vector 202502L // also in <vector> #define __cpp_lib_hardened_view_interface 202506L // also in <ranges>

The macro __cpp_lib_freestanding_operator_new is defined to the integer literal 202306L if all the default versions of the replaceable global allocation functions meet the requirements of a hosted implementation, and to the integer literal 0 otherwise ([new.delete]).

Recommended practice: Freestanding implementations should only define a macro from <version> if the implementation provides the corresponding facility in its entirety.

Recommended practice: A non-hardened implementation should not define macros from <version> required for hardened implementations.

17.3.3 Header <limits> synopsis [limits.syn]

// all freestanding namespace std { // [round.style], enumeration float_round_style enum float_round_style; // [numeric.limits], class template numeric_limits template<class T> class numeric_limits; template<class T> class numeric_limits<const T>; template<class T> class numeric_limits<volatile T>; template<class T> class numeric_limits<const volatile T>; template<> class numeric_limits<bool>; template<> class numeric_limits<char>; template<> class numeric_limits<signed char>; template<> class numeric_limits<unsigned char>; template<> class numeric_limits<char8_t>; template<> class numeric_limits<char16_t>; template<> class numeric_limits<char32_t>; template<> class numeric_limits<wchar_t>; template<> class numeric_limits<short>; template<> class numeric_limits<int>; template<> class numeric_limits<long>; template<> class numeric_limits<long long>; template<> class numeric_limits<unsigned short>; template<> class numeric_limits<unsigned int>; template<> class numeric_limits<unsigned long>; template<> class numeric_limits<unsigned long long>; template<> class numeric_limits<float>; template<> class numeric_limits<double>; template<> class numeric_limits<long double>; }

17.3.4 Enum float_round_style [round.style]

🔗

namespace std { enum float_round_style { round_indeterminate = -1, round_toward_zero = 0, round_to_nearest = 1, round_toward_infinity = 2, round_toward_neg_infinity = 3 }; }

The rounding mode for floating-point arithmetic is characterized by the values:

(1.1)
round_indeterminate if the rounding style is indeterminable
(1.2)
round_toward_zero if the rounding style is toward zero
(1.3)
round_to_nearest if the rounding style is to the nearest representable value
(1.4)
round_toward_infinity if the rounding style is toward infinity
(1.5)
round_toward_neg_infinity if the rounding style is toward negative infinity

17.3.5 Class template numeric_limits [numeric.limits]

17.3.5.1 General [numeric.limits.general]

The numeric_limits class template provides a C++ program with information about various properties of the implementation's representation of the arithmetic types.

🔗

namespace std { template<class T> class numeric_limits { public: static constexpr bool is_specialized = false; static constexpr T min() noexcept { return T(); } static constexpr T max() noexcept { return T(); } static constexpr T lowest() noexcept { return T(); } static constexpr int digits = 0; static constexpr int digits10 = 0; static constexpr int max_digits10 = 0; static constexpr bool is_signed = false; static constexpr bool is_integer = false; static constexpr bool is_exact = false; static constexpr int radix = 0; static constexpr T epsilon() noexcept { return T(); } static constexpr T round_error() noexcept { return T(); } 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 T infinity() noexcept { return T(); } static constexpr T quiet_NaN() noexcept { return T(); } static constexpr T signaling_NaN() noexcept { return T(); } static constexpr T denorm_min() noexcept { return T(); } static constexpr bool is_iec559 = false; static constexpr bool is_bounded = false; 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; }; }

For all members declared static constexpr in the numeric_limits template, specializations shall define these values in such a way that they are usable as constant expressions.

For the numeric_limits primary template, all data members are value-initialized and all member functions return a value-initialized object.

[Note 1:

This means all members have zero or false values unless numeric_limits is specialized for a type.

— end note]

Specializations shall be provided for each arithmetic type, both floating-point and integer, including bool.

The member is_specialized shall be true for all such specializations of numeric_limits.

The value of each member of a specialization of numeric_limits on a cv-qualified type cv T shall be equal to the value of the corresponding member of the specialization on the unqualified type T.

Non-arithmetic standard types, such as complex<T>, shall not have specializations.

17.3.5.2 numeric_limits members [numeric.limits.members]

Each member function defined in this subclause is signal-safe ([support.signal]).

[Note 1:

The arithmetic specification described in ISO/IEC 10967-1:2012 is commonly termed LIA-1.

— end note]

🔗

static constexpr T min() noexcept;

Minimum finite value.161

For floating-point types with subnormal numbers, returns the minimum positive normalized value.

Meaningful for all specializations in which is_bounded != false, or is_bounded == false && is_signed == false.

🔗

static constexpr T max() noexcept;

Maximum finite value.162

Meaningful for all specializations in which is_bounded != false.

🔗

static constexpr T lowest() noexcept;

A finite value x such that there is no other finite value y where y < x.163

Meaningful for all specializations in which is_bounded != false.

🔗

static constexpr int digits;

Number of radix digits that can be represented without change.

For integer types, the number of non-sign bits in the representation.

For floating-point types, the number of radix digits in the significand.164

🔗

static constexpr int digits10;

Number of base 10 digits that can be represented without change.165

Meaningful for all specializations in which is_bounded != false.

🔗

static constexpr int max_digits10;

Number of base 10 digits required to ensure that values which differ are always differentiated.

Meaningful for all floating-point types.

🔗

static constexpr bool is_signed;

true if the type is signed.

Meaningful for all specializations.

🔗

static constexpr bool is_integer;

true if the type is integer.

Meaningful for all specializations.

🔗

static constexpr bool is_exact;

true if the type uses an exact representation.

All integer types are exact, but not all exact types are integer.

For example, rational and fixed-exponent representations are exact but not integer.

Meaningful for all specializations.

🔗

static constexpr int radix;

For floating-point types, specifies the base or radix of the exponent representation (often 2).166

For integer types, specifies the base of the representation.167

Meaningful for all specializations.

🔗

static constexpr T epsilon() noexcept;

Machine epsilon: the difference between 1 and the least value greater than 1 that is representable.168

Meaningful for all floating-point types.

🔗

static constexpr T round_error() noexcept;

Measure of the maximum rounding error.169

🔗

static constexpr int min_exponent;

Minimum negative integer such that radix raised to the power of one less than that integer is a normalized floating-point number.170

Meaningful for all floating-point types.

🔗

static constexpr int min_exponent10;

Minimum negative integer such that 10 raised to that power is in the range of normalized floating-point numbers.171

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

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

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

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

Meaningful for all floating-point types.

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

🔗

static constexpr T infinity() noexcept;

Representation of positive infinity, if available.176

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

Meaningful for all specializations for which has_quiet_NaN != false.

Required in specializations for which is_iec559 != false.

🔗

static constexpr T signaling_NaN() noexcept;

Representation of a signaling “Not a Number”, if available.178

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, if available.179

Otherwise, minimum positive normalized value.

Meaningful for all floating-point types.

🔗

static constexpr bool is_iec559;

true if and only if the type adheres to ISO/IEC 60559.180

[Note 2:

The value is true for any of the types float16_t, float32_t, float64_t, or float128_t, if present ([basic.extended.fp]).

— end note]

Meaningful for all floating-point types.

🔗

static constexpr bool is_bounded;

true if the set of values representable by the type is finite.181

[Note 3:

All fundamental types ([basic.fundamental]) 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.182

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

is_modulo is false for signed integer types ([basic.fundamental]) 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 the start of the program, there exists a value of the type that would cause an arithmetic operation using that value to trap.183

Meaningful for all specializations.

🔗

static constexpr bool tinyness_before;

true if tinyness is detected before rounding.184

Meaningful for all floating-point types.

🔗

static constexpr float_round_style round_style;

The rounding style for the type.185

Meaningful for all floating-point types.

Specializations for integer types shall return round_toward_zero.

161)161)

Equivalent to CHAR_MIN, SHRT_MIN, FLT_MIN, DBL_MIN, etc.

162)162)

Equivalent to CHAR_MAX, SHRT_MAX, FLT_MAX, DBL_MAX, etc.

163)163)

lowest() is necessary because not all floating-point representations have a smallest (most negative) value that is the negative of the largest (most positive) finite value.

164)164)

Equivalent to FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG.

165)165)

Equivalent to FLT_DIG, DBL_DIG, LDBL_DIG.

166)166)

Equivalent to FLT_RADIX.

167)167)

Distinguishes types with bases other than 2 (e.g., BCD).

168)168)

Equivalent to FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON.

169)169)

Rounding error is described in ISO/IEC 10967-1:2012 Section 5.2.4 and Annex C Rationale Section C.5.2.4 — Rounding and rounding constants.

170)170)

Equivalent to FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP.

171)171)

Equivalent to FLT_MIN_10_EXP, DBL_MIN_10_EXP, LDBL_MIN_10_EXP.

172)172)

Equivalent to FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP.

173)173)

Equivalent to FLT_MAX_10_EXP, DBL_MAX_10_EXP, LDBL_MAX_10_EXP.

174)174)

Required by ISO/IEC 10967-1:2012.

175)175)

Required by ISO/IEC 10967-1:2012.

176)176)

Required by ISO/IEC 10967-1:2012.

177)177)

Required by ISO/IEC 10967-1:2012.

178)178)

Required by ISO/IEC 10967-1:2012.

179)179)

Required by ISO/IEC 10967-1:2012.

180)180)

ISO/IEC 60559:2020 is the same as IEEE 754-2019.

181)181)

Required by ISO/IEC 10967-1:2012.

182)182)

Required by ISO/IEC 10967-1:2012.

183)183)

Required by ISO/IEC 10967-1:2012.

184)184)

Refer to ISO/IEC 60559.

Required by ISO/IEC 10967-1:2012.

185)185)

Equivalent to FLT_ROUNDS.

Required by ISO/IEC 10967-1:2012.

17.3.5.3 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 1: 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 = 6; static constexpr int max_digits10 = 9; 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 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; 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 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; }; }

17.3.6 Header <climits> synopsis [climits.syn]

🔗

// all freestanding #define BOOL_WIDTH see below #define CHAR_BIT see below #define CHAR_WIDTH see below #define SCHAR_WIDTH see below #define UCHAR_WIDTH see below #define USHRT_WIDTH see below #define SHRT_WIDTH see below #define UINT_WIDTH see below #define INT_WIDTH see below #define ULONG_WIDTH see below #define LONG_WIDTH see below #define ULLONG_WIDTH see below #define LLONG_WIDTH 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>, except that it does not define the macro BITINT_MAXWIDTH.

[Note 1:

Except for the WIDTH macros, CHAR_BIT, and MB_LEN_MAX, a macro referring to an integer type T defines a constant whose type is the promoted type of T ([conv.prom]).

— end note]

17.3.7 Header <cfloat> synopsis [cfloat.syn]

🔗

// all freestanding #define __STDC_VERSION_FLOAT_H__ 202311L #define FLT_ROUNDS see below #define FLT_EVAL_METHOD see below #define FLT_RADIX see below #define INFINITY see below #define NAN see below #define FLT_SNAN see below #define DBL_SNAN see below #define LDBL_SNAN see below #define FLT_MANT_DIG see below #define DBL_MANT_DIG see below #define LDBL_MANT_DIG see below #define FLT_DECIMAL_DIG see below #define DBL_DECIMAL_DIG see below #define LDBL_DECIMAL_DIG see below #define FLT_DIG see below #define DBL_DIG see below #define LDBL_DIG see below #define FLT_MIN_EXP see below #define DBL_MIN_EXP see below #define LDBL_MIN_EXP see below #define FLT_MIN_10_EXP see below #define DBL_MIN_10_EXP see below #define LDBL_MIN_10_EXP see below #define FLT_MAX_EXP see below #define DBL_MAX_EXP see below #define LDBL_MAX_EXP see below #define FLT_MAX_10_EXP see below #define DBL_MAX_10_EXP see below #define LDBL_MAX_10_EXP see below #define FLT_MAX see below #define DBL_MAX see below #define LDBL_MAX see below #define FLT_EPSILON see below #define DBL_EPSILON see below #define LDBL_EPSILON see below #define FLT_MIN see below #define DBL_MIN see below #define LDBL_MIN see below #define FLT_TRUE_MIN see below #define DBL_TRUE_MIN see below #define LDBL_TRUE_MIN see below

The header <cfloat> defines all macros the same as the C standard library header <float.h>.

17.4 Arithmetic types [support.arith.types]

17.4.1 Header <cstdint> synopsis [cstdint.syn]

The header <cstdint> supplies integer types having specified widths, and macros that specify limits of integer types.

🔗

// all freestanding #define __STDC_VERSION_STDINT_H__ 202311L namespace std { using int8_t = signed integer type; // optional using int16_t = signed integer type; // optional using int32_t = signed integer type; // optional using int64_t = signed integer type; // optional using intN_t = see below; // optional using int_fast8_t = signed integer type; using int_fast16_t = signed integer type; using int_fast32_t = signed integer type; using int_fast64_t = signed integer type; using int_fastN_t = see below; // optional using int_least8_t = signed integer type; using int_least16_t = signed integer type; using int_least32_t = signed integer type; using int_least64_t = signed integer type; using int_leastN_t = see below; // optional using intmax_t = signed integer type; using intptr_t = signed integer type; // optional using uint8_t = unsigned integer type; // optional using uint16_t = unsigned integer type; // optional using uint32_t = unsigned integer type; // optional using uint64_t = unsigned integer type; // optional using uintN_t = see below; // optional using uint_fast8_t = unsigned integer type; using uint_fast16_t = unsigned integer type; using uint_fast32_t = unsigned integer type; using uint_fast64_t = unsigned integer type; using uint_fastN_t = see below; // optional using uint_least8_t = unsigned integer type; using uint_least16_t = unsigned integer type; using uint_least32_t = unsigned integer type; using uint_least64_t = unsigned integer type; using uint_leastN_t = see below; // optional using uintmax_t = unsigned integer type; using uintptr_t = unsigned integer type; // optional } #define INTN_MIN see below #define INTN_MAX see below #define UINTN_MAX see below #define INTN_WIDTH see below #define UINTN_WIDTH see below #define INT_FASTN_MIN see below #define INT_FASTN_MAX see below #define UINT_FASTN_MAX see below #define INT_FASTN_WIDTH see below #define UINT_FASTN_WIDTH see below #define INT_LEASTN_MIN see below #define INT_LEASTN_MAX see below #define UINT_LEASTN_MAX see below #define INT_LEASTN_WIDTH see below #define UINT_LEASTN_WIDTH see below #define INTMAX_MIN see below #define INTMAX_MAX see below #define UINTMAX_MAX see below #define INTMAX_WIDTH see below #define UINTMAX_WIDTH see below #define INTPTR_MIN see below // optional #define INTPTR_MAX see below // optional #define UINTPTR_MAX see below // optional #define INTPTR_WIDTH see below // optional #define UINTPTR_WIDTH see below // optional #define PTRDIFF_MIN see below #define PTRDIFF_MAX see below #define PTRDIFF_WIDTH see below #define SIZE_MAX see below #define SIZE_WIDTH see below #define SIG_ATOMIC_MIN see below #define SIG_ATOMIC_MAX see below #define SIG_ATOMIC_WIDTH see below #define WCHAR_MIN see below #define WCHAR_MAX see below #define WCHAR_WIDTH see below #define WINT_MIN see below #define WINT_MAX see below #define WINT_WIDTH see below #define INTN_C(value) see below #define UINTN_C(value) see below #define INTMAX_C(value) see below #define UINTMAX_C(value) see below

The header defines all types and macros the same as the C standard library header <stdint.h>.

The types denoted by intmax_t and uintmax_t are not required to be able to represent all values of extended integer types wider than long long and unsigned long long, respectively.

See also: ISO/IEC 9899:2024, 7.22

All types that use the placeholder N are optional when N is not 8, 16, 32, or 64.

The exact-width types intN_t and uintN_t for N = 8, 16, 32, and 64 are also optional; however, if an implementation defines integer types with the corresponding width and no padding bits, it defines the corresponding typedef-names.

Each of the macros listed in this subclause is defined if and only if the implementation defines the corresponding typedef-name.

[Note 1:

The macros INTN_C and UINTN_C correspond to the typedef-names int_leastN_t and uint_leastN_t, respectively.

— end note]

17.4.2 Header <stdfloat> synopsis [stdfloat.syn]

The header <stdfloat> defines type aliases for the optional extended floating-point types that are specified in [basic.extended.fp].

🔗

namespace std { #if defined(__STDCPP_FLOAT16_T__) using float16_t = implementation-defined; // see [basic.extended.fp] #endif #if defined(__STDCPP_FLOAT32_T__) using float32_t = implementation-defined; // see [basic.extended.fp] #endif #if defined(__STDCPP_FLOAT64_T__) using float64_t = implementation-defined; // see [basic.extended.fp] #endif #if defined(__STDCPP_FLOAT128_T__) using float128_t = implementation-defined; // see [basic.extended.fp] #endif #if defined(__STDCPP_BFLOAT16_T__) using bfloat16_t = implementation-defined; // see [basic.extended.fp] #endif }

17.5 Startup and termination [support.start.term]

[Note 1:

The header <cstdlib> declares the functions described in this subclause.

— end note]

🔗

[[noreturn]] void _Exit(int status) noexcept;

Effects: This function has the semantics specified in the C standard library.

Remarks: The program is terminated without executing destructors for objects with automatic, thread, or static storage duration and without calling functions passed to atexit() ([basic.start.term]).

The function _Exit is signal-safe .

🔗

[[noreturn]] void abort() noexcept;

Effects: This function has the semantics specified in the C standard library.

Remarks: The program is terminated without executing destructors for objects of automatic, thread, or static storage duration and without calling functions passed to atexit() ([basic.start.term]).

The function abort is signal-safe .

🔗

int atexit(c-atexit-handler* f) noexcept;
int atexit(atexit-handler* f) noexcept;

Effects: The atexit() functions register the function pointed to by f to be called without arguments at normal program termination.

It is unspecified whether a call to atexit() that does not happen before a call to exit() will succeed.

[Note 2:

The atexit() functions do not introduce a data race ([res.on.data.races]).

— end note]

Implementation limits: The implementation shall support the registration of at least 32 functions.

Returns: The atexit() function returns zero if the registration succeeds, nonzero if it fails.

🔗

[[noreturn]] void exit(int status);

Effects:

(9.1)
First, objects with thread storage duration and associated with the current thread are destroyed.

Next, objects with static storage duration are destroyed and functions registered by calling atexit are called.186

See [basic.start.term] for the order of destructions and calls.

(Objects with automatic storage duration are not destroyed as a result of calling exit().)187
If a registered function invoked by exit exits via an exception, the function std::terminate is invoked ([except.terminate]).
(9.2)
Next, all open C streams (as mediated by the function signatures declared in <cstdio>) with unwritten buffered data are flushed, all open C streams are closed, and all files created by calling tmpfile() are removed.
(9.3)
Finally, control is returned to the host environment.

If status is zero or EXIT_SUCCESS, an implementation-defined form of the status successful termination is returned.

If status is EXIT_FAILURE, an implementation-defined form of the status unsuccessful termination is returned.

Otherwise the status returned is implementation-defined.188

🔗

int at_quick_exit(c-atexit-handler* f) noexcept;
int at_quick_exit(atexit-handler* f) noexcept;

Effects: The at_quick_exit() functions register the function pointed to by f to be called without arguments when quick_exit is called.

It is unspecified whether a call to at_quick_exit() that does not happen before all calls to quick_exit will succeed.

[Note 3:

The at_quick_exit() functions do not introduce a data race ([res.on.data.races]).

— end note]

[Note 4:

The order of registration could be indeterminate if at_quick_exit was called from more than one thread.

— end note]

[Note 5:

The at_quick_exit registrations are distinct from the atexit registrations, and applications might need to call both registration functions with the same argument.

— end note]

Implementation limits: The implementation shall support the registration of at least 32 functions.

Returns: Zero if the registration succeeds, nonzero if it fails.

🔗

[[noreturn]] void quick_exit(int status) noexcept;

Effects: Functions registered by calls to at_quick_exit are called in the reverse order of their registration, except that a function shall be called after any previously registered functions that had already been called at the time it was registered.

Objects shall not be destroyed as a result of calling quick_exit.

If a registered function invoked by quick_exit exits via an exception, the function std::terminate is invoked ([except.terminate]).

[Note 6:

A function registered via at_quick_exit is invoked by the thread that calls quick_exit, which can be a different thread than the one that registered it, so registered functions cannot rely on the identity of objects with thread storage duration.

— end note]

After calling registered functions, quick_exit shall call _Exit(status).

Remarks: The function quick_exit is signal-safe when the functions registered with at_quick_exit are.

17.6 Dynamic memory management [support.dynamic]

17.6.1 General [support.dynamic.general]

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

It also defines components for reporting storage management errors.

17.6.2 Header <new> synopsis [new.syn]

// all freestanding namespace std { // [alloc.errors], storage allocation errors class bad_alloc; class bad_array_new_length; struct destroying_delete_t { explicit destroying_delete_t() = default; }; inline constexpr destroying_delete_t destroying_delete{}; // global operator new control enum class align_val_t : size_t {}; struct nothrow_t { explicit nothrow_t() = default; }; extern const nothrow_t nothrow; using new_handler = void (*)(); new_handler get_new_handler() noexcept; new_handler set_new_handler(new_handler new_p) noexcept; // [ptr.launder], pointer optimization barrier template<class T> constexpr T* launder(T* p) noexcept; // [hardware.interference], hardware interference size inline constexpr size_t hardware_destructive_interference_size = implementation-defined; inline constexpr size_t hardware_constructive_interference_size = implementation-defined; } // [new.delete], storage allocation and deallocation void* operator new(std::size_t size); void* operator new(std::size_t size, std::align_val_t alignment); void* operator new(std::size_t size, const std::nothrow_t&) noexcept; 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; void* operator new[](std::size_t size); void* operator new[](std::size_t size, std::align_val_t alignment); void* operator new[](std::size_t size, const std::nothrow_t&) noexcept; 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; constexpr void* operator new (std::size_t size, void* ptr) noexcept; constexpr void* operator new[](std::size_t size, void* ptr) noexcept; void operator delete (void* ptr, void*) noexcept; void operator delete[](void* ptr, void*) noexcept;

17.6.3 Storage allocation and deallocation [new.delete]

17.6.3.1 General [new.delete.general]

Except where otherwise specified, the provisions of [basic.stc.dynamic] 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.

On freestanding implementations, it is implementation-defined whether the default versions of the replaceable global allocation functions satisfy the required behaviors described in [new.delete.single] and [new.delete.array].

[Note 1:

A freestanding implementation's default versions of the replaceable global allocation functions can cause undefined behavior when invoked.

During constant evaluation, the behaviors of those default versions are irrelevant, as those calls are omitted ([expr.new]).

— end note]

Recommended practice: If any of the default versions of the replaceable global allocation functions meet the requirements of a hosted implementation, they all should.

17.6.3.2 Single-object forms [new.delete.single]

🔗

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

Effects: The allocation functions called by a new-expression ([expr.new]) to allocate size bytes of storage.

The second form is called for a type with new-extended alignment, and the first form is called otherwise.

Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), or else throw a bad_alloc exception.

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

Default behavior:

(3.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.
(3.2)
Returns a pointer to the allocated storage if the attempt is successful.

Otherwise, if the current new_handler ([get.new.handler]) is a null pointer value, throws bad_alloc.
(3.3)
Otherwise, the function calls the current new_handler function.

If the called function returns, the loop repeats.
(3.4)
The loop terminates when an attempt to allocate the requested storage is successful or when a called new_handler function does not return.

Remarks: This function is replaceable ([dcl.fct.def.replace]).

🔗

void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
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.

Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), 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 1: T* p1 = new T; // throws bad_alloc if it fails T* p2 = new(nothrow) T; // returns nullptr if it fails — end example]

Remarks: This function is replaceable ([dcl.fct.def.replace]).

🔗

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;

Preconditions: ptr is a null pointer or its value represents 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.

If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

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

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

Effects: The deallocation functions ([basic.stc.dynamic.deallocation]) called by a delete-expression ([expr.delete]) to render the value of ptr invalid.

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

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.

[Note 2:

See the note in the below Remarks: 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>.

This function is replaceable ([dcl.fct.def.replace]).

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

If a replacement function with a size parameter is defined by the program, the program shall also define the corresponding version without the size parameter.

[Note 3:

The default behavior above might change in the future, which will require replacing both deallocation functions when replacing the allocation function.

— end note]

🔗

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;

If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

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

Effects: The deallocation functions ([basic.stc.dynamic.deallocation]) 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.

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

Remarks: This function is replaceable ([dcl.fct.def.replace]).

17.6.3.3 Array forms [new.delete.array]

🔗

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

Effects: The allocation functions called by the array form of a new-expression ([expr.new]) to allocate size bytes of storage.

The second form is called for a type with new-extended alignment, and the first form is called otherwise.189

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.

Remarks: This function is replaceable ([dcl.fct.def.replace]).

🔗

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

Required behavior: Return a non-null pointer to suitably aligned storage ([basic.stc.dynamic]), 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.

Remarks: This function is replaceable ([dcl.fct.def.replace]).

🔗

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;

Preconditions: ptr is a null pointer or its value represents 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[].

If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

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

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

Effects: The deallocation functions ([basic.stc.dynamic.deallocation]) called by the array form of a delete-expression to render the value of ptr invalid.

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

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.

Remarks: This function is replaceable ([dcl.fct.def.replace]).

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

If a replacement function with a size parameter is defined by the program, the program shall also define the corresponding version without the size parameter.

[Note 2:

The default behavior above might change in the future, which will require replacing both deallocation functions when replacing the allocation function.

— end note]

🔗

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;

If the alignment parameter is not present, ptr was returned by an allocation function without an alignment parameter.

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

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

Remarks: This function is replaceable ([dcl.fct.def.replace]).

189)189)

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, can, however, increase the size argument to operator new[] to obtain space to store supplemental information.

17.6.3.4 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 ([constraints]).

The provisions of [basic.stc.dynamic] do not apply to these reserved placement forms of operator new and operator delete.

🔗

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

Returns: ptr.

Remarks: Intentionally performs no other action.

[Example 1:

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]

🔗

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

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 ([expr.new]).

🔗

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

Effects: Intentionally performs no action.

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 ([expr.new]).

17.6.3.5 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 ([res.on.data.races]).

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 the next allocation (if any) in this order.

17.6.4 Storage allocation errors [alloc.errors]

17.6.4.1 Class bad_alloc [bad.alloc]

🔗

namespace std { class bad_alloc : public exception { public: // see [exception] for the specification of the special member functions constexpr 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.

🔗

constexpr const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

17.6.4.2 Class bad_array_new_length [new.badlength]

namespace std { class bad_array_new_length : public bad_alloc { public: // see [exception] for the specification of the special member functions constexpr 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 ([expr.new]).

🔗

constexpr const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

17.6.4.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[]() ([new.delete]) 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.

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

17.6.4.5 get_new_handler [get.new.handler]

🔗

new_handler get_new_handler() noexcept;

Returns: The current new_handler.

[Note 1:

This can be a null pointer value.

— end note]

17.6.5 Pointer optimization barrier [ptr.launder]

🔗

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

Mandates: !is_function_v<T> && !is_void_v<T> is true.

Preconditions: p represents the address A of a byte in memory.

An object X that is within its lifetime and whose type is similar to T is located at the address A.

All bytes of storage that would be reachable through ([basic.compound]) the result are reachable through p.

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

Remarks: An invocation of this function may be used in a core constant expression if and only if the (converted) value of its argument may be used in place of the function invocation.

[Note 1:

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 its complete object is a const object or it is a base class subobject; in the latter cases, this function can be used to obtain a usable pointer to the new object.

See [basic.life].

— end note]

[Example 1: struct X { int n; }; const X *p = new const X{3}; const int a = p->n; new (const_cast<X*>(p)) const X{5}; // p does not point to new object ([basic.life]) because its type is const const int b = p->n; // undefined behavior const int c = std::launder(p)->n; // OK — end example]

17.6.6 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 1: 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 2: 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]

17.7 Type identification [support.rtti]

17.7.1 General [support.rtti.general]

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.

The header <typeindex> defines a wrapper type for use as an index type in associative containers ([associative]) and in unordered associative containers ([unord]).

17.7.2 Header <typeinfo> synopsis [typeinfo.syn]

17.7.3 Class type_info [type.info]

🔗

namespace std { class type_info { public: virtual ~type_info(); constexpr 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&) = delete; type_info& operator=(const type_info&) = delete; }; }

The class type_info describes type information generated by the implementation ([expr.typeid]).

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.

🔗

constexpr 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 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, suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).

17.7.4 Class bad_cast [bad.cast]

🔗

namespace std { class bad_cast : public exception { public: // see [exception] for the specification of the special member functions constexpr 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 ([expr.dynamic.cast]).

🔗

constexpr const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

17.7.5 Class bad_typeid [bad.typeid]

🔗

namespace std { class bad_typeid : public exception { public: // see [exception] for the specification of the special member functions constexpr 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 ([expr.typeid]).

🔗

constexpr const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

17.7.6 Header <typeindex> synopsis [type.index.synopsis]

17.7.7 Class type_index [type.index]

🔗

namespace std { class type_index { public: type_index(const type_info& rhs) noexcept; bool operator==(const type_index& rhs) const noexcept; bool operator< (const type_index& rhs) const noexcept; bool operator> (const type_index& rhs) const noexcept; bool operator<=(const type_index& rhs) const noexcept; bool operator>=(const type_index& rhs) const noexcept; strong_ordering operator<=>(const type_index& rhs) const noexcept; size_t hash_code() const noexcept; const char* name() const noexcept; private: const type_info* target; // exposition only // Note that the use of a pointer here, rather than a reference, // means that the default copy/move constructor and assignment // operators will be provided and work as expected. }; }

The class type_index provides a simple wrapper for type_info which can be used as an index type in associative containers ([associative]) and in unordered associative containers ([unord]).

🔗

type_index(const type_info& rhs) noexcept;

Effects: Constructs a type_index object, the equivalent of target = &rhs.

🔗

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

Returns: *target == *rhs.target.

🔗

bool operator<(const type_index& rhs) const noexcept;

Returns: target->before(*rhs.target).

🔗

bool operator>(const type_index& rhs) const noexcept;

Returns: rhs.target->before(*target).

🔗

bool operator<=(const type_index& rhs) const noexcept;

Returns: !rhs.target->before(*target).

🔗

bool operator>=(const type_index& rhs) const noexcept;

Returns: !target->before(*rhs.target).

🔗

strong_ordering operator<=>(const type_index& rhs) const noexcept;

Effects: Equivalent to: if (*target == *rhs.target) return strong_ordering::equal; if (target->before(*rhs.target)) return strong_ordering::less; return strong_ordering::greater;

🔗

size_t hash_code() const noexcept;

Returns: target->hash_code().

🔗

const char* name() const noexcept;

Returns: target->name().

🔗

template<> struct hash<type_index>;

For an object index of type type_index, hash<type_index>()(index) shall evaluate to the same result as index.hash_code().

17.8 Source location [support.srcloc]

17.8.1 Header <source_location> synopsis [source.location.syn]

The header defines the class source_location that provides a means to obtain source location information.

// all freestanding namespace std { struct source_location; }

17.8.2 Class source_location [support.srcloc.class]

17.8.2.1 General [support.srcloc.class.general]

🔗

namespace std { struct source_location { // source location construction static consteval source_location current() noexcept; constexpr source_location() noexcept; // source location field access constexpr uint_least32_t line() const noexcept; constexpr uint_least32_t column() const noexcept; constexpr const char* file_name() const noexcept; constexpr const char* function_name() const noexcept; private: uint_least32_t line_; // exposition only uint_least32_t column_; // exposition only const char* file_name_; // exposition only const char* function_name_; // exposition only }; }

The type source_location meets the Cpp17DefaultConstructible, Cpp17CopyConstructible, Cpp17CopyAssignable, Cpp17Swappable, and Cpp17Destructible requirements ([utility.arg.requirements], [swappable.requirements]).

All of the following conditions are true:

(1.1)
is_nothrow_move_constructible_v<source_location>
(1.2)
is_nothrow_move_assignable_v<source_location>
(1.3)
is_nothrow_swappable_v<source_location>

[Note 1:

The intent of source_location is to have a small size and efficient copying.

It is unspecified whether the copy/move constructors and the copy/move assignment operators are trivial and/or constexpr.

— end note]

The data members file_name_ and function_name_ always each refer to an ntbs.

The copy/move constructors and the copy/move assignment operators of source_location meet the following postconditions: Given two objects lhs and rhs of type source_location, where lhs is a copy/move result of rhs, and where rhs_p is a value denoting the state of rhs before the corresponding copy/move operation, then each of the following conditions is true:

(3.1)
strcmp(lhs.file_name(), rhs_p.file_name()) == 0
(3.2)
strcmp(lhs.function_name(), rhs_p.function_name()) == 0
(3.3)
lhs.line() == rhs_p.line()
(3.4)
lhs.column() == rhs_p.column()

17.8.2.2 Creation [support.srcloc.cons]

🔗

static consteval source_location current() noexcept;

Returns:

(1.1)

When invoked by a function call whose postfix-expression is a (possibly parenthesized) id-expression naming current, returns a source_location with an implementation-defined value.

The value should be affected by #line ([cpp.line]) in the same manner as for __LINE__ and __FILE__.

The values of the exposition-only data members of the returned source_location object are indicated in Table 43 .

Table 43 — Value of object returned by current [tab:support.srcloc.current]

🔗 Element	Value
🔗 line_	A presumed line number ([cpp.predefined]). Line numbers are presumed to be 1-indexed; however, an implementation is encouraged to use 0 when the line number is unknown.
🔗 column_	An implementation-defined value denoting some offset from the start of the line denoted by line_. Column numbers are presumed to be 1-indexed; however, an implementation is encouraged to use 0 when the column number is unknown.
🔗 file_name_	A presumed name of the current source file ([cpp.predefined]) as an ntbs.
🔗 function_name_	A name of the current function such as in __func__ ([dcl.fct.def.general]) if any, an empty string otherwise.

(1.2)
Otherwise, when invoked in some other way, returns a source_location whose data members are initialized with valid but unspecified values.

Remarks: Any call to current that appears as a default member initializer ([class.mem.general]), or as a subexpression thereof, should correspond to the location of the constructor definition or aggregate initialization that uses the default member initializer.

Any call to current that appears as a default argument ([dcl.fct.default]), or as a subexpression thereof, should correspond to the location of the invocation of the function that uses the default argument ([expr.call]).

[Example 1: struct s { source_location member = source_location::current(); int other_member; s(source_location loc = source_location::current()) : member(loc) // values of member refer to the location of the calling function ([dcl.fct.default]) {} s(int blather) : // values of member refer to this location other_member(blather) {} s(double) // values of member refer to this location {} }; void f(source_location a = source_location::current()) { source_location b = source_location::current(); // values in b refer to this line } void g() { f(); // f's first argument corresponds to this line of code source_location c = source_location::current(); f(c); // f's first argument gets the same values as c, above } — end example]

🔗

constexpr source_location() noexcept;

Effects: The data members are initialized with valid but unspecified values.

17.8.2.3 Observers [support.srcloc.obs]

🔗

constexpr uint_least32_t line() const noexcept;

Returns: line_.

🔗

constexpr uint_least32_t column() const noexcept;

Returns: column_.

🔗

constexpr const char* file_name() const noexcept;

Returns: file_name_.

🔗

constexpr const char* function_name() const noexcept;

Returns: function_name_.

17.9 Exception handling [support.exception]

17.9.1 General [support.exception.general]

The header defines several types and functions related to the handling of exceptions in a C++ program.

17.9.2 Header <exception> synopsis [exception.syn]

// all freestanding 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; constexpr int uncaught_exceptions() noexcept; using exception_ptr = unspecified; constexpr exception_ptr current_exception() noexcept; [[noreturn]] constexpr void rethrow_exception(exception_ptr p); template<class E> constexpr exception_ptr make_exception_ptr(E e) noexcept; template<class E> constexpr const E* exception_ptr_cast(const exception_ptr& p) noexcept; template<class E> void exception_ptr_cast(const exception_ptr&&) = delete; template<class T> [[noreturn]] constexpr void throw_with_nested(T&& t); template<class E> constexpr void rethrow_if_nested(const E& e); }

17.9.3 Class exception [exception]

🔗

namespace std { class exception { public: constexpr exception() noexcept; constexpr exception(const exception&) noexcept; constexpr exception& operator=(const exception&) noexcept; constexpr virtual ~exception(); constexpr 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.

Except where explicitly specified otherwise, each standard library class T that derives from class exception has the following publicly accessible member functions, each of them having a non-throwing exception specification ([except.spec]):

(2.1)
default constructor (unless the class synopsis shows other constructors)
(2.2)
copy constructor
(2.3)
copy assignment operator

The copy constructor and the copy assignment operator 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()) is equal to 0.

The what() member function of each such T satisfies the constraints specified for exception::what() (see below).

🔗

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

Postconditions: If *this and rhs both have dynamic type exception then the value of the expression strcmp(what(), rhs.what()) shall equal 0.

🔗

constexpr virtual ~exception();

Effects: Destroys an object of class exception.

🔗

constexpr virtual const char* what() const noexcept;

Returns: An implementation-defined ntbs, which during constant evaluation is encoded with the ordinary literal encoding ([lex.ccon]).

Remarks: The message may be a null-terminated multibyte string, suitable for conversion and display as a wstring ([string.classes], [locale.codecvt]).

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.

17.9.4 Class bad_exception [bad.exception]

🔗

namespace std { class bad_exception : public exception { public: // see [exception] for the specification of the special member functions constexpr 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 ([propagation]) when the currently active exception object fails to copy.

🔗

constexpr const char* what() const noexcept override;

Returns: An implementation-defined ntbs.

17.9.5 Abnormal termination [exception.terminate]

17.9.5.1 Type terminate_handler [terminate.handler]

🔗

using terminate_handler = void (*)();

The type of a handler function to be invoked by terminate when terminating exception processing.

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

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

Returns: The previous terminate_handler.

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

17.9.5.3 get_terminate [get.terminate]

🔗

terminate_handler get_terminate() noexcept;

Returns: The current terminate_handler.

[Note 1:

This can be a null pointer value.

— end note]

17.9.5.4 terminate [terminate]

🔗

[[noreturn]] void terminate() noexcept;

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

A default terminate_handler is always considered a callable handler in this context.

— end note]

Remarks: Called by the implementation when exception handling must be abandoned for any of several reasons ([except.terminate]).

May also be called directly by the program.

17.9.6 uncaught_exceptions [uncaught.exceptions]

🔗

constexpr int uncaught_exceptions() noexcept;

Returns: The number of uncaught exceptions ([except.throw]) in the current thread.

Remarks: When uncaught_exceptions() > 0, throwing an exception can result in a call of the function std::terminate .

17.9.7 Exception propagation [propagation]

🔗

using exception_ptr = unspecified;

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

exception_ptr meets the requirements of Cpp17NullablePointer (Table 36).

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

An implementation can use a reference-counted smart pointer as exception_ptr.

— end note]

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 or exception_ptr_cast on exception_ptr objects that refer to the same exception object shall not introduce a data race.

[Note 2:

If rethrow_exception rethrows the same exception object (rather than a copy), concurrent access to that rethrown exception object can 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]

All member functions are marked constexpr.

🔗

constexpr exception_ptr current_exception() noexcept;

Returns: An exception_ptr object that refers to the currently handled exception 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 3:

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

The copy constructor of the thrown exception can also fail, so the implementation can substitute a bad_exception object to avoid infinite recursion.

— end note]

🔗

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

Preconditions: p is not a null pointer.

Effects: Let u be the exception object to which p refers, or a copy of that exception object.

It is unspecified whether a copy is made, and memory for the copy is allocated in an unspecified way.

(11.1)
If allocating memory to form u fails, throws an instance of bad_alloc;
(11.2)
otherwise, if copying the exception to which p refers to form u throws an exception, throws that exception;
(11.3)
otherwise, throws u.

🔗

template<class E> constexpr 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 5:

This function is provided for convenience and efficiency reasons.

— end note]

🔗

template<class E> constexpr const E* exception_ptr_cast(const exception_ptr& p) noexcept;

Mandates: E is a cv-unqualified complete object type.

E is not an array type.

E is not a pointer or pointer-to-member type.

[Note 6:

When E is a pointer or pointer-to-member type, a handler of type const E& can match without binding to the exception object itself.

— end note]

Returns: A pointer to the exception object referred to by p, if p is not null and a handler of type const E& would be a match ([except.handle]) for that exception object.

Otherwise, nullptr.

17.9.8 nested_exception [except.nested]

🔗

namespace std { class nested_exception { public: constexpr nested_exception() noexcept; constexpr nested_exception(const nested_exception&) noexcept = default; constexpr nested_exception& operator=(const nested_exception&) noexcept = default; constexpr virtual ~nested_exception() = default; // access functions [[noreturn]] constexpr void rethrow_nested() const; constexpr exception_ptr nested_ptr() const noexcept; }; template<class T> [[noreturn]] constexpr void throw_with_nested(T&& t); template<class E> constexpr 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 1:

nested_exception has a virtual destructor to make it a polymorphic class.

Its presence can be tested for with dynamic_cast.

— end note]

🔗

constexpr nested_exception() noexcept;

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

🔗

[[noreturn]] constexpr void rethrow_nested() const;

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

Otherwise, it throws the stored exception captured by *this.

🔗

constexpr exception_ptr nested_ptr() const noexcept;

Returns: The stored exception captured by this nested_exception object.

🔗

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

Let U be decay_t<T>.

Preconditions: U meets the Cpp17CopyConstructible requirements.

Throws: If is_class_v && !is_final_v && !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> constexpr 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();

17.10 Contract-violation handling [support.contract]

17.10.1 Header <contracts> synopsis [contracts.syn]

The header <contracts> defines types for reporting information about contract violations ([basic.contract.eval]).

🔗

// all freestanding namespace std::contracts { enum class assertion_kind : unspecified { pre = 1, post = 2, assert = 3 }; enum class evaluation_semantic : unspecified { ignore = 1, observe = 2, enforce = 3, quick_enforce = 4 }; enum class detection_mode : unspecified { predicate_false = 1, evaluation_exception = 2 }; class contract_violation { // no user-accessible constructor public: contract_violation(const contract_violation&) = delete; contract_violation& operator=(const contract_violation&) = delete; see below ~contract_violation(); const char* comment() const noexcept; contracts::detection_mode detection_mode() const noexcept; exception_ptr evaluation_exception() const noexcept; bool is_terminating() const noexcept; assertion_kind kind() const noexcept; source_location location() const noexcept; evaluation_semantic semantic() const noexcept; }; void invoke_default_contract_violation_handler(const contract_violation&); }

17.10.2 Enumerations [support.contract.enum]

Recommended practice: For all enumerations in [support.contract.enum], if implementation-defined enumerators are provided, they should have a minimum value of 1000.

The enumerators of assertion_kind correspond to the syntactic forms of a contract assertion ([basic.contract.general]), with meanings listed in Table 44 .

Table 44 — Enum assertion_kind [tab:support.contract.enum.kind]

🔗 Name	Meaning
🔗 pre	A precondition assertion
🔗 post	A postcondition assertion
🔗 assert	An assertion-statement
🔗

The enumerators of evaluation_semantic correspond to the evaluation semantics with which a contract assertion may be evaluated ([basic.contract.eval]), with meanings listed in Table 45 .

Table 45 — Enum evaluation_semantic [tab:support.contract.enum.semantic]

🔗 Name	Meaning
🔗 ignore	Ignore evaluation semantic
🔗 observe	Observe evaluation semantic
🔗 enforce	Enforce evaluation semantic
🔗 quick_enforce	Quick-enforce evaluation semantic
🔗

The enumerators of detection_mode correspond to the manners in which a contract violation can be identified ([basic.contract.eval]), with meanings listed in Table 46.

Table 46 — Enum detection_mode [tab:support.contract.enum.detection]

🔗 Name	Meaning
🔗 predicate_false	The predicate of the contract assertion evaluated to false or would have evaluated to false.
🔗 evaluation_exception	An uncaught exception occurred during evaluation of the contract assertion.
🔗

17.10.3 Class contract_violation [support.contract.violation]

The class contract_violation defines the type of objects used to represent a contract violation that has been detected during the evaluation of a contract assertion with a particular evaluation semantic ([basic.contract.eval]).

Objects of this type can be created only by the implementation.

It is implementation-defined whether the destructor is virtual.

🔗

const char* comment() const noexcept;

Returns: An implementation-defined ntmbs in the ordinary literal encoding ([lex.charset]).

Recommended practice: The string returned should contain a textual representation of the predicate of the violated contract assertion or an empty string if storing a textual representation is undesired.

[Note 1:

The string can represent a truncated, reformatted, or summarized rendering of the predicate, before or after preprocessing.

— end note]

🔗

contracts::detection_mode detection_mode() const noexcept;

Returns: The enumerator value corresponding to the manner in which the contract violation was identified.

🔗

exception_ptr evaluation_exception() const noexcept;

Returns: If the contract violation occurred because the evaluation of the predicate exited via an exception, an exception_ptr object that refers to that exception or a copy of that exception; otherwise, a null exception_ptr object.

🔗

bool is_terminating() const noexcept;

Returns: true if the evaluation semantic is a terminating semantic ([basic.contract.eval]); otherwise, false.

🔗

assertion_kind kind() const noexcept;

Returns: The enumerator value corresponding to the syntactic form of the violated contract assertion.

🔗

source_location location() const noexcept;

Returns: A source_location object with implementation-defined value.

Recommended practice: The value returned should be a default constructed source_location object or a value identifying the violated contract assertion:

(9.1)
When possible, if the violated contract assertion was a precondition, the source location of the function invocation should be returned.
(9.2)
Otherwise, the source location of the contract assertion should be returned.

🔗

evaluation_semantic semantic() const noexcept;

Returns: The enumerator value corresponding to the evaluation semantic with which the violated contract assertion was evaluated.

17.10.4 Invoke default handler [support.contract.invoke]

🔗

void invoke_default_contract_violation_handler(const contract_violation& v);

Effects: Invokes the default contract-violation handler ([basic.contract.handler]) with the argument v.

17.11 Initializer lists [support.initlist]

17.11.1 General [support.initlist.general]

The header defines a class template and several support functions related to list-initialization (see [dcl.init.list]).

All functions specified in [support.initlist] are signal-safe ([support.signal]).

17.11.2 Header <initializer_list> synopsis [initializer.list.syn]

// all freestanding 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 }; // [support.initlist.range], 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 1:

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 [dcl.init.list].

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.

17.11.3 Initializer list constructors [support.initlist.cons]

🔗

constexpr initializer_list() noexcept;

Postconditions: size() == 0.

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

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

17.12 Comparisons [cmp]

17.12.1 Header <compare> synopsis [compare.syn]

The header specifies types, objects, and functions for use primarily in connection with the three-way comparison operator .

🔗

// all freestanding namespace std { // [cmp.categories], comparison category types class partial_ordering; class weak_ordering; class strong_ordering; // named comparison functions constexpr bool is_eq (partial_ordering cmp) noexcept { return cmp == 0; } constexpr bool is_neq (partial_ordering 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; } // [cmp.common], 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; // [cmp.concept], concept three_way_comparable template<class T, class Cat = partial_ordering> concept three_way_comparable = see below; template<class T, class U, class Cat = partial_ordering> concept three_way_comparable_with = see below; // [cmp.result], result of three-way comparison template<class T, class U = T> struct compare_three_way_result; template<class T, class U = T> using compare_three_way_result_t = typename compare_three_way_result<T, U>::type; // [comparisons.three.way], class compare_three_way struct compare_three_way; // [cmp.alg], comparison algorithms inline namespace unspecified { inline constexpr unspecified strong_order = unspecified; inline constexpr unspecified weak_order = unspecified; inline constexpr unspecified partial_order = unspecified; inline constexpr unspecified compare_strong_order_fallback = unspecified; inline constexpr unspecified compare_weak_order_fallback = unspecified; inline constexpr unspecified compare_partial_order_fallback = unspecified; } // [compare.type], type ordering template<class T, class U> struct type_order; template<class T, class U> constexpr strong_ordering type_order_v = type_order<T, U>::value; }

17.12.2 Comparison category types [cmp.categories]

17.12.2.1 Preamble [cmp.categories.pre]

The types 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 ord { equal = 0, equivalent = equal, less = -1, greater = 1 }; // exposition only enum class ncmp { unordered = -127 }; // exposition only

[Note 1:

The type strong_ordering corresponds to the term total ordering 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 1:

nullptr_t meets 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 [cmp.categories], 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.

17.12.2.2 Class partial_ordering [cmp.partialord]

The partial_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]), for which equality need not imply substitutability, and that permits two values to be incomparable.190

🔗

namespace std { class partial_ordering { int value; // exposition only bool is-ordered; // exposition only // exposition-only constructors constexpr explicit partial_ordering(ord v) noexcept : value(int(v)), is-ordered(true) {} // exposition only constexpr explicit partial_ordering(ncmp v) noexcept : value(int(v)), is-ordered(false) {} // exposition only public: // valid values static const partial_ordering less; static const partial_ordering equivalent; static const partial_ordering greater; static const partial_ordering unordered; // comparisons friend constexpr bool operator==(partial_ordering v, unspecified) noexcept; friend constexpr bool operator==(partial_ordering v, partial_ordering w) noexcept = default; 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 partial_ordering operator<=>(partial_ordering v, unspecified) noexcept; friend constexpr partial_ordering 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(ord::equivalent); inline constexpr partial_ordering partial_ordering::greater(ord::greater); inline constexpr partial_ordering partial_ordering::unordered(ncmp::unordered); }

🔗

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;

Returns: For operator@, v.is-ordered && 0 @ v.value.

🔗

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

Returns: v.

🔗

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

Returns: v < 0 ? partial_ordering::greater : v > 0 ? partial_ordering::less : v.

190)190)

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

17.12.2.3 Class weak_ordering [cmp.weakord]

The weak_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]) and for which equality need not imply substitutability.

🔗

namespace std { class weak_ordering { int value; // exposition only // exposition-only constructors constexpr explicit 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 partial_ordering() const noexcept; // comparisons friend constexpr bool operator==(weak_ordering v, unspecified) noexcept; friend constexpr bool operator==(weak_ordering v, weak_ordering w) noexcept = default; 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 weak_ordering operator<=>(weak_ordering v, unspecified) noexcept; friend constexpr weak_ordering 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(ord::equivalent); inline constexpr weak_ordering weak_ordering::greater(ord::greater); }

🔗

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;

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;

Returns: 0 @ v.value for operator@.

🔗

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

Returns: v.

🔗

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

Returns: v < 0 ? weak_ordering::greater : v > 0 ? weak_ordering::less : v.

17.12.2.4 Class strong_ordering [cmp.strongord]

The strong_ordering type is typically used as the result type of a three-way comparison operator ([expr.spaceship]) for a type that admits all of the six two-way comparison operators ([expr.rel], [expr.eq]) and for which equality does imply substitutability.

🔗

namespace std { class strong_ordering { int value; // exposition only // exposition-only constructors constexpr explicit 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 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, strong_ordering w) noexcept = default; 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 strong_ordering operator<=>(strong_ordering v, unspecified) noexcept; friend constexpr strong_ordering 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(ord::equal); inline constexpr strong_ordering strong_ordering::equivalent(ord::equivalent); inline constexpr strong_ordering strong_ordering::greater(ord::greater); }

🔗

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

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;

Returns: 0 @ v.value for operator@.

🔗

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

Returns: v.

🔗

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

Returns: v < 0 ? strong_ordering::greater : v > 0 ? strong_ordering::less : v.

17.12.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 1:

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 ([class.spaceship]) of Ts..., the expanded parameter pack, or void if any element of Ts is not a comparison category type.

[Note 2:

This is std::strong_ordering if the expansion is empty.

— end note]

17.12.4 Concept three_way_comparable [cmp.concept]

template<class T, class Cat> concept compares-as = // exposition only same_as<common_comparison_category_t<T, Cat>, Cat>; template<class T, class U> concept partially-ordered-with = // exposition only requires(const remove_reference_t<T>& t, const remove_reference_t& u) { { t boolean-testable; { t > u } -> boolean-testable; { t <= u } -> boolean-testable; { t >= u } -> boolean-testable; { u < t } -> boolean-testable; { u > t } -> boolean-testable; { u <= t } -> boolean-testable; { u >= t } -> boolean-testable; };

Let t and u be lvalues of types const remove_reference_t<T> and const remove_reference_t, respectively.

T and U model partially-ordered-with<T, U> only if

(1.1)
t < u, t <= u, t > u, t >= u, u < t, u <= t, u > t, and u >= t have the same domain,
(1.2)
bool(t < u) == bool(u > t) is true,
(1.3)
bool(u < t) == bool(t > u) is true,
(1.4)
bool(t <= u) == bool(u >= t) is true, and
(1.5)
bool(u <= t) == bool(t >= u) is true.

template<class T, class Cat = partial_ordering> concept three_way_comparable = weakly-equality-comparable-with<T, T> && partially-ordered-with<T, T> && requires(const remove_reference_t<T>& a, const remove_reference_t<T>& b) { { a <=> b } -> compares-as<Cat>; };

Let a and b be lvalues of type const remove_reference_t<T>.

T and Cat model three_way_comparable<T, Cat> only if

(2.1)
(a <=> b == 0) == bool(a == b) is true,
(2.2)
(a <=> b != 0) == bool(a != b) is true,
(2.3)
((a <=> b) <=> 0) and (0 <=> (b <=> a)) are equal,
(2.4)
(a <=> b < 0) == bool(a < b) is true,
(2.5)
(a <=> b > 0) == bool(a > b) is true,
(2.6)
(a <=> b <= 0) == bool(a <= b) is true,
(2.7)
(a <=> b >= 0) == bool(a >= b) is true, and
(2.8)
if Cat is convertible to strong_ordering, T models totally_ordered ([concept.totallyordered]).

template<class T, class U, class Cat = partial_ordering> concept three_way_comparable_with = three_way_comparable<T, Cat> && three_way_comparable<U, Cat> && comparison-common-type-with<T, U> && three_way_comparable< common_reference_t<const remove_reference_t<T>&, const remove_reference_t&>, Cat> && weakly-equality-comparable-with<T, U> && partially-ordered-with<T, U> && requires(const remove_reference_t<T>& t, const remove_reference_t& u) { { t <=> u } -> compares-as<Cat>; { u <=> t } -> compares-as<Cat>; };

Let t and t2 be lvalues denoting distinct equal objects of types const remove_reference_t<T> and remove_cvref_t<T>, respectively, and let u and u2 be lvalues denoting distinct equal objects of types const remove_reference_t and remove_cvref_t, respectively.

Let C be common_reference_t<const remove_reference_t<T>&, const remove_reference_t&>.

Let CONVERT_TO_LVALUE<C>(E) be defined as in [concepts.compare.general].

T, U, and Cat model three_way_comparable_with<T, U, Cat> only if

(3.1)
t <=> u and u <=> t have the same domain,
(3.2)
((t <=> u) <=> 0) and (0 <=> (u <=> t)) are equal,
(3.3)
(t <=> u == 0) == bool(t == u) is true,
(3.4)
(t <=> u != 0) == bool(t != u) is true,
(3.5)
Cat(t <=> u) == Cat(CONVERT_TO_LVALUE<C>(t2) <=> CONVERT_TO_LVALUE<C>(u2)) is true,
(3.6)
(t <=> u < 0) == bool(t < u) is true,
(3.7)
(t <=> u > 0) == bool(t > u) is true,
(3.8)
(t <=> u <= 0) == bool(t <= u) is true,
(3.9)
(t <=> u >= 0) == bool(t >= u) is true, and
(3.10)
if Cat is convertible to strong_ordering, T and U model totally_ordered_with<T, U> ([concept.totallyordered]).

17.12.5 Result of three-way comparison [cmp.result]

The behavior of a program that adds specializations for the compare_three_way_result template defined in this subclause is undefined.

For the compare_three_way_result type trait applied to the types T and U, let t and u denote lvalues of types const remove_reference_t<T> and const remove_reference_t, respectively.

If the expression t <=> u is well-formed when treated as an unevaluated operand ([expr.context]), the member typedef-name type denotes the type decltype(t <=> u).

Otherwise, there is no member type.

17.12.6 Comparison algorithms [cmp.alg]

The name strong_order denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression strong_order(E, F) is expression-equivalent ([defns.expression.equivalent]) to the following:

(1.1)
If the decayed types of E and F differ, strong_order(E, F) is ill-formed.
(1.2)
Otherwise, strong_ordering(strong_order(E, F)) if it is a well-formed expression where the meaning of strong_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
(1.3)
Otherwise, if the decayed type T of E is a floating-point type, yields a value of type strong_ordering that is consistent with the ordering observed by T's comparison operators, and if numeric_limits<T>::is_iec559 is true, is additionally consistent with the totalOrder operation as specified in ISO/IEC 60559.
(1.4)
Otherwise, strong_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
(1.5)
Otherwise, strong_order(E, F) is ill-formed.

[Note 1:

Ill-formed cases above result in substitution failure when strong_order(E, F) appears in the immediate context of a template instantiation.

— end note]

The name weak_order denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression weak_order(E, F) is expression-equivalent ([defns.expression.equivalent]) to the following:

(2.1)
If the decayed types of E and F differ, weak_order(E, F) is ill-formed.
(2.2)
Otherwise, weak_ordering(weak_order(E, F)) if it is a well-formed expression where the meaning of weak_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
(2.3)
Otherwise, if the decayed type T of E is a floating-point type, yields a value of type weak_ordering that is consistent with the ordering observed by T's comparison operators and strong_order, and if numeric_limits<T>::is_iec559 is true, is additionally consistent with the following equivalence classes, ordered from lesser to greater:
- (2.3.1)
 together, all negative NaN values;
- (2.3.2)
 negative infinity;
- (2.3.3)
 each normal negative value;
- (2.3.4)
 each subnormal negative value;
- (2.3.5)
 together, both zero values;
- (2.3.6)
 each subnormal positive value;
- (2.3.7)
 each normal positive value;
- (2.3.8)
 positive infinity;
- (2.3.9)
 together, all positive NaN values.
(2.4)
Otherwise, weak_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
(2.5)
Otherwise, weak_ordering(strong_order(E, F)) if it is a well-formed expression.
(2.6)
Otherwise, weak_order(E, F) is ill-formed.

[Note 2:

Ill-formed cases above result in substitution failure when weak_order(E, F) appears in the immediate context of a template instantiation.

— end note]

The name partial_order denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression partial_order(E, F) is expression-equivalent ([defns.expression.equivalent]) to the following:

(3.1)
If the decayed types of E and F differ, partial_order(E, F) is ill-formed.
(3.2)
Otherwise, partial_ordering(partial_order(E, F)) if it is a well-formed expression where the meaning of partial_order is established as-if by performing argument-dependent lookup only ([basic.lookup.argdep]).
(3.3)
Otherwise, partial_ordering(compare_three_way()(E, F)) if it is a well-formed expression.
(3.4)
Otherwise, partial_ordering(weak_order(E, F)) if it is a well-formed expression.
(3.5)
Otherwise, partial_order(E, F) is ill-formed.

[Note 3:

Ill-formed cases above result in substitution failure when partial_order(E, F) appears in the immediate context of a template instantiation.

— end note]

The name compare_strong_order_fallback denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression compare_strong_order_fallback(E, F) is expression-equivalent ([defns.expression.equivalent]) to:

(4.1)
If the decayed types of E and F differ, compare_strong_order_fallback(E, F) is ill-formed.
(4.2)
Otherwise, strong_order(E, F) if it is a well-formed expression.
(4.3)
Otherwise, if the expressions E == F and E < F are both well-formed and each of decltype(E == F) and decltype(E < F) models boolean-testable, E == F ? strong_ordering::equal : E < F ? strong_ordering::less : strong_ordering::greater except that E and F are evaluated only once.
(4.4)
Otherwise, compare_strong_order_fallback(E, F) is ill-formed.

[Note 4:

Ill-formed cases above result in substitution failure when compare_strong_order_fallback(E, F) appears in the immediate context of a template instantiation.

— end note]

The name compare_weak_order_fallback denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression compare_weak_order_fallback(E, F) is expression-equivalent ([defns.expression.equivalent]) to:

(5.1)
If the decayed types of E and F differ, compare_weak_order_fallback(E, F) is ill-formed.
(5.2)
Otherwise, weak_order(E, F) if it is a well-formed expression.
(5.3)
Otherwise, if the expressions E == F and E < F are both well-formed and each of decltype(E == F) and decltype(E < F) models boolean-testable, E == F ? weak_ordering::equivalent : E < F ? weak_ordering::less : weak_ordering::greater except that E and F are evaluated only once.
(5.4)
Otherwise, compare_weak_order_fallback(E, F) is ill-formed.

[Note 5:

Ill-formed cases above result in substitution failure when compare_weak_order_fallback(E, F) appears in the immediate context of a template instantiation.

— end note]

The name compare_partial_order_fallback denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expression compare_partial_order_fallback(E, F) is expression-equivalent ([defns.expression.equivalent]) to:

(6.1)
If the decayed types of E and F differ, compare_partial_order_fallback(E, F) is ill-formed.
(6.2)
Otherwise, partial_order(E, F) if it is a well-formed expression.
(6.3)
Otherwise, if the expressions E == F, E < F, and F < E are all well-formed and each of decltype(E == F), decltype(E < F), and decltype(F < E) models boolean-testable, E == F ? partial_ordering::equivalent : E < F ? partial_ordering::less : F < E ? partial_ordering::greater : partial_ordering::unordered except that E and F are evaluated only once.
(6.4)
Otherwise, compare_partial_order_fallback(E, F) is ill-formed.

[Note 6:

Ill-formed cases above result in substitution failure when compare_partial_order_fallback(E, F) appears in the immediate context of a template instantiation.

— end note]

17.12.7 Type Ordering [compare.type]

There is an implementation-defined total ordering of all types.

For any (possibly incomplete) types X and Y, the expression TYPE-ORDER(X, Y) is a constant expression ([expr.const]) of type strong_ordering ([cmp.strongord]).

Its value is strong_ordering::less if X precedes Y in this implementation-defined total order, strong_ordering::greater if Y precedes X, and strong_ordering::equal if they are the same type.

[Note 1:

int, const int and int& are different types.

— end note]

[Note 2:

This ordering need not be consistent with the one induced by type_info::before.

— end note]

[Note 3:

The ordering of TU-local types from different translation units is not observable, because the necessary specialization of type_order is impossible to name.

— end note]

🔗

template<class T, class U>
  struct type_order;

The name type_order denotes a Cpp17BinaryTypeTrait ([meta.rqmts]) with a base characteristic of integral_constant<strong_ordering, TYPE-ORDER(T, U)>.

Recommended practice: The order should be lexicographical on parameter-type-lists and template argument lists.

17.13 Coroutines [support.coroutine]

17.13.1 General [support.coroutine.general]

The header defines several types providing compile and run-time support for coroutines in a C++ program.

17.13.2 Header <coroutine> synopsis [coroutine.syn]

🔗

// all freestanding #include <compare> // see [compare.syn] namespace std { // [coroutine.traits], coroutine traits template<class R, class... ArgTypes> struct coroutine_traits; // [coroutine.handle], coroutine handle template<class Promise = void> struct coroutine_handle; // [coroutine.handle.compare], comparison operators constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept; constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept; // [coroutine.handle.hash], hash support template<class T> struct hash; template<class P> struct hash<coroutine_handle>; // [coroutine.noop], no-op coroutines struct noop_coroutine_promise; template<> struct coroutine_handle<noop_coroutine_promise>; using noop_coroutine_handle = coroutine_handle<noop_coroutine_promise>; noop_coroutine_handle noop_coroutine() noexcept; // [coroutine.trivial.awaitables], trivial awaitables struct suspend_never; struct suspend_always; }

17.13.3 Coroutine traits [coroutine.traits]

17.13.3.1 General [coroutine.traits.general]

Subclause [coroutine.traits] defines requirements on classes representing coroutine traits, and defines the class template coroutine_traits that meets those requirements.

17.13.3.2 Class template coroutine_traits [coroutine.traits.primary]

The header <coroutine> defines the primary template coroutine_traits such that if ArgTypes is a parameter pack of types and if the qualified-id R::promise_type is valid and denotes a type ([temp.deduct]), then coroutine_traits<R, ArgTypes...> has the following publicly accessible member: using promise_type = typename R::promise_type;

Otherwise, coroutine_traits<R, ArgTypes...> has no members.

Program-defined specializations of this template shall define a publicly accessible nested type named promise_type.

17.13.4 Class template coroutine_handle [coroutine.handle]

17.13.4.1 General [coroutine.handle.general]

🔗

namespace std { template<> struct coroutine_handle<void> { // [coroutine.handle.con], construct/reset constexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept; coroutine_handle& operator=(nullptr_t) noexcept; // [coroutine.handle.export.import], export/import constexpr void* address() const noexcept; static constexpr coroutine_handle from_address(void* addr); // [coroutine.handle.observers], observers constexpr explicit operator bool() const noexcept; bool done() const; // [coroutine.handle.resumption], resumption void operator()() const; void resume() const; void destroy() const; private: void* ptr; // exposition only }; template<class Promise> struct coroutine_handle { // [coroutine.handle.con], construct/reset constexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept; static coroutine_handle from_promise(Promise&); coroutine_handle& operator=(nullptr_t) noexcept; // [coroutine.handle.export.import], export/import constexpr void* address() const noexcept; static constexpr coroutine_handle from_address(void* addr); // [coroutine.handle.conv], conversion constexpr operator coroutine_handle<>() const noexcept; // [coroutine.handle.observers], observers constexpr explicit operator bool() const noexcept; bool done() const; // [coroutine.handle.resumption], resumption void operator()() const; void resume() const; void destroy() const; // [coroutine.handle.promise], promise access Promise& promise() const; private: void* ptr; // exposition only }; }

An object of type coroutine_handle<T> is called a coroutine handle and can be used to refer to a suspended or executing coroutine.

A coroutine_handle object whose member address() returns a null pointer value does not refer to any coroutine.

Two coroutine_handle objects refer to the same coroutine if and only if their member address() returns the same non-null value.

If a program declares an explicit or partial specialization of coroutine_handle, the behavior is undefined.

17.13.4.2 Construct/reset [coroutine.handle.con]

🔗

constexpr coroutine_handle() noexcept;
constexpr coroutine_handle(nullptr_t) noexcept;

Postconditions: address() == nullptr.

🔗

static coroutine_handle from_promise(Promise& p);

Preconditions: p is a reference to a promise object of a coroutine.

Postconditions: addressof(h.promise()) == addressof(p).

Returns: A coroutine handle h referring to the coroutine.

🔗

coroutine_handle& operator=(nullptr_t) noexcept;

Postconditions: address() == nullptr.

Returns: *this.

17.13.4.3 Conversion [coroutine.handle.conv]

🔗

constexpr operator coroutine_handle<>() const noexcept;

Effects: Equivalent to: return coroutine_handle<>::from_address(address());

17.13.4.4 Export/import [coroutine.handle.export.import]

🔗

constexpr void* address() const noexcept;

Returns: ptr.

🔗

static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr);

Preconditions: addr was obtained via a prior call to address on an object whose type is a specialization of coroutine_handle.

Postconditions: from_address(address()) == *this.

🔗

static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);

Preconditions: addr was obtained via a prior call to address on an object of type cv coroutine_handle<Promise>.

Postconditions: from_address(address()) == *this.

17.13.4.5 Observers [coroutine.handle.observers]

🔗

constexpr explicit operator bool() const noexcept;

Returns: address() != nullptr.

🔗

bool done() const;

Preconditions: *this refers to a suspended coroutine.

Returns: true if the coroutine is suspended at its final suspend point, otherwise false.

17.13.4.6 Resumption [coroutine.handle.resumption]

Resuming a coroutine via resume, operator(), or destroy on an execution agent other than the one on which it was suspended has implementation-defined behavior unless each execution agent either is an instance of std::thread or std::jthread, or is the thread that executes main.

[Note 1:

A coroutine that is resumed on a different execution agent should avoid relying on consistent thread identity throughout, such as holding a mutex object across a suspend point.

— end note]

[Note 2:

A concurrent resumption of the coroutine can result in a data race.

— end note]

🔗

void operator()() const;
void resume() const;

Preconditions: *this refers to a suspended coroutine.

The coroutine is not suspended at its final suspend point.

Effects: Resumes the execution of the coroutine.

🔗

void destroy() const;

Preconditions: *this refers to a suspended coroutine.

Effects: Destroys the coroutine ([dcl.fct.def.coroutine]).

17.13.4.7 Promise access [coroutine.handle.promise]

🔗

Promise& promise() const;

Preconditions: *this refers to a coroutine.

Returns: A reference to the promise of the coroutine.

17.13.4.8 Comparison operators [coroutine.handle.compare]

🔗

constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;

Returns: x.address() == y.address().

🔗

constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;

Returns: compare_three_way()(x.address(), y.address()).

17.13.4.9 Hash support [coroutine.handle.hash]

🔗

template<class P> struct hash<coroutine_handle<P>>;

The specialization is enabled ([unord.hash]).

17.13.5 No-op coroutines [coroutine.noop]

17.13.5.1 Class noop_coroutine_promise [coroutine.promise.noop]

🔗

struct noop_coroutine_promise {};

The class noop_coroutine_promise defines the promise type for the coroutine referred to by noop_coroutine_handle ([coroutine.syn]).

17.13.5.2 Class coroutine_handle<noop_coroutine_promise> [coroutine.handle.noop]

17.13.5.2.1 General [coroutine.handle.noop.general]

🔗

namespace std { template<> struct coroutine_handle<noop_coroutine_promise> { // [coroutine.handle.noop.conv], conversion constexpr operator coroutine_handle<>() const noexcept; // [coroutine.handle.noop.observers], observers constexpr explicit operator bool() const noexcept; constexpr bool done() const noexcept; // [coroutine.handle.noop.resumption], resumption constexpr void operator()() const noexcept; constexpr void resume() const noexcept; constexpr void destroy() const noexcept; // [coroutine.handle.noop.promise], promise access noop_coroutine_promise& promise() const noexcept; // [coroutine.handle.noop.address], address constexpr void* address() const noexcept; private: coroutine_handle(unspecified); void* ptr; // exposition only }; }

17.13.5.2.2 Conversion [coroutine.handle.noop.conv]

🔗

constexpr operator coroutine_handle<>() const noexcept;

Effects: Equivalent to: return coroutine_handle<>::from_address(address());

17.13.5.2.3 Observers [coroutine.handle.noop.observers]

🔗

constexpr explicit operator bool() const noexcept;

Returns: true.

🔗

constexpr bool done() const noexcept;

Returns: false.

17.13.5.2.4 Resumption [coroutine.handle.noop.resumption]

🔗

constexpr void operator()() const noexcept;
constexpr void resume() const noexcept;
constexpr void destroy() const noexcept;

Effects: None.

Remarks: If noop_coroutine_handle is converted to coroutine_handle<>, calls to operator(), resume and destroy on that handle will also have no observable effects.

17.13.5.2.5 Promise access [coroutine.handle.noop.promise]

🔗

noop_coroutine_promise& promise() const noexcept;

Returns: A reference to the promise object associated with this coroutine handle.

17.13.5.2.6 Address [coroutine.handle.noop.address]

🔗

constexpr void* address() const noexcept;

Returns: ptr.

Remarks: A noop_coroutine_handle's ptr is always a non-null pointer value.

17.13.5.3 Function noop_coroutine [coroutine.noop.coroutine]

🔗

noop_coroutine_handle noop_coroutine() noexcept;

Returns: A handle to a coroutine that has no observable effects when resumed or destroyed.

Remarks: A handle returned from noop_coroutine may or may not compare equal to a handle returned from another invocation of noop_coroutine.

17.13.6 Trivial awaitables [coroutine.trivial.awaitables]

🔗

namespace std { struct suspend_never { constexpr bool await_ready() const noexcept { return true; } constexpr void await_suspend(coroutine_handle<>) const noexcept {} constexpr void await_resume() const noexcept {} }; struct suspend_always { constexpr bool await_ready() const noexcept { return false; } constexpr void await_suspend(coroutine_handle<>) const noexcept {} constexpr void await_resume() const noexcept {} }; }

[Note 1:

The types suspend_never and suspend_always can be used to indicate that an await-expression either never suspends or always suspends, and in either case does not produce a value.

— end note]

17.14 Other runtime support [support.runtime]

17.14.1 General [support.runtime.general]

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 ([cstdlib.syn]) shall not introduce a data race ([res.on.data.races]) provided that nothing modifies the environment.

[Note 1:

Calls to the POSIX functions setenv and putenv modify the environment.

— end note]

A call to the setlocale function 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.

17.14.2 Header <cstdarg> synopsis [cstdarg.syn]

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

(1.1)
In lieu of the default argument promotions specified in ISO/IEC 9899:2024 6.5.2.2, the definition in [expr.call] applies.
(1.2)
The preprocessing tokens comprising the second and subsequent arguments to va_start (if any) are discarded.

[Note 1:
va_start accepts a second argument for compatibility with prior revisions of C++.
— end note]

17.14.3 Header <csetjmp> synopsis [csetjmp.syn]

🔗

#define __STDC_VERSION_SETJMP_H__ 202311L namespace std { using jmp_buf = see below; [[noreturn]] void longjmp(jmp_buf env, int val); } #define setjmp(env) see below

The contents of the header are the same as the C standard library header <setjmp.h>.

The function signature longjmp(jmp_buf jbuf, int val) has more restricted behavior in this document.

A setjmp/longjmp call pair has undefined behavior if replacing the setjmp and longjmp by catch and throw would invoke any non-trivial destructors for any objects with automatic storage duration.

A call to setjmp or longjmp has undefined behavior if invoked in a suspension context of a coroutine ([expr.await]).

17.14.4 Header <csignal> synopsis [csignal.syn]

🔗

namespace std { using sig_atomic_t = see below; // [support.signal], signal handlers extern "C" using signal-handler = void(int); // exposition only signal-handler* signal(int sig, signal-handler* func); int raise(int sig); } #define SIG_DFL see below #define SIG_ERR see below #define SIG_IGN see below #define SIGABRT see below #define SIGFPE see below #define SIGILL see below #define SIGINT see below #define SIGSEGV see below #define SIGTERM see below

The contents of the header are the same as the C standard library header <signal.h>.

17.14.5 Signal handlers [support.signal]

A call to the function signal synchronizes with any resulting invocation of the signal handler so installed.

A plain lock-free atomic operation is an invocation of a function f from [atomics], such that:

(2.1)
f is the function atomic_is_lock_free(), or
(2.2)
f is the member function is_lock_free(), or
(2.3)
f is a non-static member function of class atomic_flag, or
(2.4)
f is a non-member function, and the first parameter of f has type cv atomic_flag*, or
(2.5)
f is a non-static member function invoked on an object A, such that A.is_lock_free() yields true, or
(2.6)
f is a non-member function, and for every pointer-to-atomic argument A passed to f, atomic_is_lock_free(A) yields true.

An evaluation is signal-safe unless it includes one of the following:

(3.1)
a call to any standard library function, except for plain lock-free atomic operations and functions explicitly identified as signal-safe;
[Note 1:
This implicitly excludes the use of new and delete expressions that rely on a library-provided memory allocator.
— end note]
(3.2)
an access to an object with thread storage duration;
(3.3)
a dynamic_cast expression;
(3.4)
throwing of an exception;
(3.5)
control entering a try-block or function-try-block;
(3.6)
initialization of a variable with static storage duration requiring dynamic initialization ([basic.start.dynamic], [stmt.dcl])191 ; or
(3.7)
waiting for the completion of the initialization of a variable with static storage duration ([stmt.dcl]).

A signal handler invocation has undefined behavior if it includes an evaluation that is not signal-safe.

The function signal is signal-safe if it is invoked with the first argument equal to the signal number corresponding to the signal that caused the invocation of the handler.

17.15 C headers [support.c.headers]

17.15.1 General [support.c.headers.general]

For compatibility with the C standard library, the C++ standard library provides the C headers shown in Table 47 .

The intended use of these headers is for interoperability only.

It is possible that C++ source files need to include one of these headers in order to be valid C. Source files that are not intended to also be valid C should not use any of the C headers.

[Note 1:

The C headers either have no effect, such as <stdbool.h> and <stdalign.h>, or otherwise the corresponding header of the form <cname> provides the same facilities and assuredly defines them in namespace std.

— end note]

[Example 1:

The following source file is both valid C++ and valid C. Viewed as C++, it declares a function with C language linkage; viewed as C it simply declares a function (and provides a prototype).

#include <uchar.h> // for char8_t in C, not necessary in C++ #include <stddef.h> // for size_t #ifdef __cplusplus // see [cpp.predefined] extern "C" // see [dcl.link] #endif void f(char8_t s[], size_t n); — end example]

Table 47 — C headers [tab:c.headers]

🔗 <assert.h>	<inttypes.h>	<signal.h>	<stdckdint.h>	<tgmath.h>
🔗 <complex.h>	<iso646.h>	<stdalign.h>	<stddef.h>	<time.h>
🔗 <ctype.h>	<limits.h>	<stdarg.h>	<stdint.h>	<uchar.h>
🔗 <errno.h>	<locale.h>	<stdatomic.h>	<stdio.h>	<wchar.h>
🔗 <fenv.h>	<math.h>	<stdbit.h>	<stdlib.h>	<wctype.h>
🔗 <float.h>	<setjmp.h>	<stdbool.h>	<string.h>

17.15.2 Header <complex.h> synopsis [complex.h.syn]

The header <complex.h> behaves as if it simply includes the header <complex>.

[Note 1:

Names introduced by <complex> in namespace std are not placed into the global namespace scope by <complex.h>.

— end note]

17.15.3 Header <iso646.h> synopsis [iso646.h.syn]

The C++ header <iso646.h> is empty.

[Note 1:

and, and_eq, bitand, bitor, compl, not_eq, not, or, or_eq, xor, and xor_eq are keywords in C++ ([lex.key]).

— end note]

17.15.4 Header <stdalign.h> synopsis [stdalign.h.syn]

The contents of the C++ header <stdalign.h> are the same as the C standard library header <stdalign.h>.

17.15.5 Header <stdbool.h> synopsis [stdbool.h.syn]

The contents of the C++ header <stdbool.h> are the same as the C standard library header <stdbool.h>.

17.15.6 Header <tgmath.h> synopsis [tgmath.h.syn]

The header <tgmath.h> behaves as if it simply includes the headers <cmath> and <complex>.

[Note 1:

The overloads provided in C by type-generic macros are already provided in <complex> and <cmath> by “sufficient” additional overloads.

— end note]

[Note 2:

Names introduced by <cmath> or <complex> in namespace std are not placed into the global namespace scope by <tgmath.h>.

— end note]

17.15.7 Other C headers [support.c.headers.other]

Every C header other than <complex.h>, <iso646.h>, <stdalign.h>,
<stdatomic.h>, <stdbit.h>, <stdbool.h>, <stdckdint.h>, and
<tgmath.h>, each of which has a name of the form <name.h>, behaves as if each name placed in the standard library namespace by the corresponding <cname> header is placed within the global namespace scope, except for the functions described in [sf.cmath], the std::lerp function overloads ([c.math.lerp]), the declaration of std::byte ([cstddef.syn]), and the functions and function templates described in [support.types.byteops].

It is unspecified whether these names are first declared or defined within namespace scope ([basic.scope.namespace]) of the namespace std and are then injected into the global namespace scope by explicit using-declarations ([namespace.udecl]).

[Example 1:

The header <cstdlib> assuredly provides its declarations and definitions within the namespace std.

It may also provide these names within the global namespace.

The header <stdlib.h> assuredly provides the same declarations and definitions within the global namespace, much as in ISO/IEC 9899.

It may also provide these names within the namespace std.

— end example]