[diagnostics] - C++20 → C++23

Files changed (1) hide show

tmp/tmppgi93ym6/{from.md → to.md} +635 -42

tmp/tmppgi93ym6/{from.md → to.md} RENAMED Viewed

@@ -4,26 +4,29 @@
 This Clause describes components that C++ programs may use to detect and
 report error conditions.
 The following subclauses describe components for reporting several kinds
-of exceptional conditions, documenting program assertions, and a global
-variable for error number codes, as summarized in
-[[diagnostics.summary]].
 **Table: Diagnostics library summary** <a id="diagnostics.summary">[diagnostics.summary]</a>
 | Subclause          |                      | Header           |
 | ------------------ | -------------------- | ---------------- |
 | [[std.exceptions]] | Exception classes    | `<stdexcept>`    |
 | [[assertions]]     | Assertions           | `<cassert>`      |
 | [[errno]]          | Error numbers        | `<cerrno>`       |
 | [[syserr]]         | System error support | `<system_error>` |
 ## Exception classes <a id="std.exceptions">[[std.exceptions]]</a>
 The C++ standard library provides classes to be used to report certain
 errors [[res.on.exception.handling]] in C++ programs. In the error model
 reflected in these classes, errors are divided into two broad
 categories: *logic* errors and *runtime* errors.
@@ -299,10 +302,12 @@ underflow_error(const char* what_arg);
 *Ensures:* `strcmp(what(), what_arg) == 0`.
 ## Assertions <a id="assertions">[[assertions]]</a>
 The header `<cassert>` provides a macro for documenting C++ program
 assertions and a mechanism for disabling the assertion checks.
 ### Header `<cassert>` synopsis <a id="cassert.syn">[[cassert.syn]]</a>
@@ -325,17 +330,19 @@ An expression `assert(E)` is a constant subexpression
 - `E` contextually converted to `bool` [[conv]] is a constant
   subexpression that evaluates to the value `true`.
 ## Error numbers <a id="errno">[[errno]]</a>
 The contents of the header `<cerrno>` are the same as the POSIX header
 `<errno.h>`, except that `errno` shall be defined as a macro.
 [*Note 1*: The intent is to remain in close alignment with the POSIX
 standard. — *end note*]
-A separate `errno` value shall be provided for each thread.
 ### Header `<cerrno>` synopsis <a id="cerrno.syn">[[cerrno.syn]]</a>
 ``` cpp
 #define errno see below
@@ -378,22 +385,19 @@ A separate `errno` value shall be provided for each thread.
 #define ENETDOWN see below
 #define ENETRESET see below
 #define ENETUNREACH see below
 #define ENFILE see below
 #define ENOBUFS see below
-#define ENODATA see below
 #define ENODEV see below
 #define ENOENT see below
 #define ENOEXEC see below
 #define ENOLCK see below
 #define ENOLINK see below
 #define ENOMEM see below
 #define ENOMSG see below
 #define ENOPROTOOPT see below
 #define ENOSPC see below
-#define ENOSR see below
-#define ENOSTR see below
 #define ENOSYS see below
 #define ENOTCONN see below
 #define ENOTDIR see below
 #define ENOTEMPTY see below
 #define ENOTRECOVERABLE see below
@@ -411,11 +415,10 @@ A separate `errno` value shall be provided for each thread.
 #define EPROTOTYPE see below
 #define ERANGE see below
 #define EROFS see below
 #define ESPIPE see below
 #define ESRCH see below
-#define ETIME see below
 #define ETIMEDOUT see below
 #define ETXTBSY see below
 #define EWOULDBLOCK see below
 #define EXDEV see below
 ```
@@ -425,16 +428,20 @@ standard.
 See also: ISO C 7.5
 ## System error support <a id="syserr">[[syserr]]</a>
-This subclause describes components that the standard library and C++
-programs may use to report error conditions originating from the
 operating system or other low-level application program interfaces.
-Components described in this subclause shall not change the value of
-`errno` [[errno]]. Implementations should leave the error states
 provided by other libraries unchanged.
 ### Header `<system_error>` synopsis <a id="system.error.syn">[[system.error.syn]]</a>
 ``` cpp
@@ -494,22 +501,19 @@ namespace std {
     network_unreachable,                // ENETUNREACH
     no_buffer_space,                    // ENOBUFS
     no_child_process,                   // ECHILD
     no_link,                            // ENOLINK
     no_lock_available,                  // ENOLCK
-    no_message_available,               // ENODATA
     no_message,                         // ENOMSG
     no_protocol_option,                 // ENOPROTOOPT
     no_space_on_device,                 // ENOSPC
-    no_stream_resources,                // ENOSR
     no_such_device_or_address,          // ENXIO
     no_such_device,                     // ENODEV
     no_such_file_or_directory,          // ENOENT
     no_such_process,                    // ESRCH
     not_a_directory,                    // ENOTDIR
     not_a_socket,                       // ENOTSOCK
-    not_a_stream,                       // ENOSTR
     not_connected,                      // ENOTCONN
     not_enough_memory,                  // ENOMEM
     not_supported,                      // ENOTSUP
     operation_canceled,                 // ECANCELED
     operation_in_progress,              // EINPROGRESS
@@ -523,11 +527,10 @@ namespace std {
     read_only_file_system,              // EROFS
     resource_deadlock_would_occur,      // EDEADLK
     resource_unavailable_try_again,     // EAGAIN
     result_out_of_range,                // ERANGE
     state_not_recoverable,              // ENOTRECOVERABLE
-    stream_timeout,                     // ETIME
     text_file_busy,                     // ETXTBSY
     timed_out,                          // ETIMEDOUT
     too_many_files_open_in_system,      // ENFILE
     too_many_files_open,                // EMFILE
     too_many_links,                     // EMLINK
@@ -546,11 +549,11 @@ namespace std {
       operator<<(basic_ostream<charT, traits>& os, const error_code& ec);
   // [syserr.errcondition.nonmembers], non-member functions
   error_condition make_error_condition(errc e) noexcept;
-  // [syserr.compare], comparison functions
   bool operator==(const error_code& lhs, const error_code& rhs) noexcept;
   bool operator==(const error_code& lhs, const error_condition& rhs) noexcept;
   bool operator==(const error_condition& lhs, const error_condition& rhs) noexcept;
   strong_ordering operator<=>(const error_code& lhs, const error_code& rhs) noexcept;
   strong_ordering operator<=>(const error_condition& lhs, const error_condition& rhs) noexcept;
@@ -560,24 +563,24 @@ namespace std {
   template<> struct hash<error_code>;
   template<> struct hash<error_condition>;
   // [syserr], system error support
   template<class T>
- inline constexpr bool is_error_code_enum_v = is_error_code_enum<T>::value;
   template<class T>
- inline constexpr bool is_error_condition_enum_v = is_error_condition_enum<T>::value;
 }
 ```
-The value of each `enum errc` constant shall be the same as the value of
-the `<cerrno>` macro shown in the above synopsis. Whether or not the
 `<system_error>` implementation exposes the `<cerrno>` macros is
 unspecified.
-The `is_error_code_enum` and `is_error_condition_enum` may be
 specialized for program-defined types to indicate that such types are
-eligible for `class error_code` and `class error_condition` automatic
 conversions, respectively.
 ### Class `error_category` <a id="syserr.errcat">[[syserr.errcat]]</a>
 #### Overview <a id="syserr.errcat.overview">[[syserr.errcat.overview]]</a>
@@ -587,13 +590,14 @@ identify the source and encoding of a particular category of error code.
 Classes may be derived from `error_category` to support categories of
 errors in addition to those defined in this document. Such classes shall
 behave as specified in subclause  [[syserr.errcat]].
 [*Note 1*: `error_category` objects are passed by reference, and two
-such objects are equal if they have the same address. This means that
-applications using custom `error_category` types should create a single
-object of each such type. — *end note*]
 ``` cpp
 namespace std {
   class error_category {
   public:
@@ -719,19 +723,20 @@ the same object.
 *Remarks:* The object’s `equivalent` virtual functions shall behave as
 specified for class `error_category`. The object’s `name` virtual
 function shall return a pointer to the string `"system"`. The object’s
 `default_error_condition` virtual function shall behave as follows:
-If the argument `ev` corresponds to a POSIX `errno` value `posv`, the
-function shall return `error_condition(posv, generic_category())`.
-Otherwise, the function shall return
-`error_condition(ev, system_category())`. What constitutes
 correspondence for any given operating system is unspecified.
 [*Note 1*: The number of potential system error codes is large and
-unbounded, and some may not correspond to any POSIX `errno` value. Thus
-implementations are given latitude in determining
 correspondence. — *end note*]
 ### Class `error_code` <a id="syserr.errcode">[[syserr.errcode]]</a>
 #### Overview <a id="syserr.errcode.overview">[[syserr.errcode.overview]]</a>
@@ -784,26 +789,32 @@ namespace std {
 ``` cpp
 error_code() noexcept;
 ```
-*Ensures:* `val_ == 0` and `cat_ == &system_category()`.
 ``` cpp
 error_code(int val, const error_category& cat) noexcept;
 ```
-*Ensures:* `val_ == val` and `cat_ == &cat`.
 ``` cpp
 template<class ErrorCodeEnum>
   error_code(ErrorCodeEnum e) noexcept;
 ```
 *Constraints:* `is_error_code_enum_v<ErrorCodeEnum>` is `true`.
-*Ensures:* `*this == make_error_code(e)`.
 #### Modifiers <a id="syserr.errcode.modifiers">[[syserr.errcode.modifiers]]</a>
 ``` cpp
 void assign(int val, const error_category& cat) noexcept;
@@ -816,11 +827,16 @@ template<class ErrorCodeEnum>
   error_code& operator=(ErrorCodeEnum e) noexcept;
 ```
 *Constraints:* `is_error_code_enum_v<ErrorCodeEnum>` is `true`.
-*Ensures:* `*this == make_error_code(e)`.
 *Returns:* `*this`.
 ``` cpp
 void clear() noexcept;
@@ -920,27 +936,33 @@ namespace std {
 ``` cpp
 error_condition() noexcept;
 ```
-*Ensures:* `val_ == 0` and `cat_ == &generic_category()`.
 ``` cpp
 error_condition(int val, const error_category& cat) noexcept;
 ```
-*Ensures:* `val_ == val` and `cat_ == &cat`.
 ``` cpp
 template<class ErrorConditionEnum>
   error_condition(ErrorConditionEnum e) noexcept;
 ```
 *Constraints:* `is_error_condition_enum_v<ErrorConditionEnum>` is
 `true`.
-*Ensures:* `*this == make_error_condition(e)`.
 #### Modifiers <a id="syserr.errcondition.modifiers">[[syserr.errcondition.modifiers]]</a>
 ``` cpp
 void assign(int val, const error_category& cat) noexcept;
@@ -954,11 +976,16 @@ template<class ErrorConditionEnum>
 ```
 *Constraints:* `is_error_condition_enum_v<ErrorConditionEnum>` is
 `true`.
-*Ensures:* `*this == make_error_condition(e)`.
 *Returns:* `*this`.
 ``` cpp
 void clear() noexcept;
@@ -998,11 +1025,11 @@ explicit operator bool() const noexcept;
 error_condition make_error_condition(errc e) noexcept;
 ```
 *Returns:* `error_condition(static_cast<int>(e), generic_category())`.
-### Comparison functions <a id="syserr.compare">[[syserr.compare]]</a>
 ``` cpp
 bool operator==(const error_code& lhs, const error_code& rhs) noexcept;
 ```
@@ -1153,33 +1180,598 @@ const char* what() const noexcept override;
 constructor.
 [*Note 1*: The returned NTBS might be the contents of
 `what_arg + ": " + code.message()`. — *end note*]
 <!-- Link reference definitions -->
 [assertions]: #assertions
 [assertions.assert]: #assertions.assert
 [bad.alloc]: support.md#bad.alloc
 [cassert.syn]: #cassert.syn
 [cerrno.syn]: #cerrno.syn
 [comparisons.three.way]: utilities.md#comparisons.three.way
 [conv]: expr.md#conv
-[defns.const.subexpr]: library.md#defns.const.subexpr
 [diagnostics]: #diagnostics
 [diagnostics.general]: #diagnostics.general
 [diagnostics.summary]: #diagnostics.summary
 [domain.error]: #domain.error
 [errno]: #errno
 [invalid.argument]: #invalid.argument
 [length.error]: #length.error
 [logic.error]: #logic.error
 [out.of.range]: #out.of.range
 [overflow.error]: #overflow.error
 [range.error]: #range.error
 [res.on.exception.handling]: library.md#res.on.exception.handling
 [runtime.error]: #runtime.error
 [std.exceptions]: #std.exceptions
 [stdexcept.syn]: #stdexcept.syn
 [syserr]: #syserr
 [syserr.compare]: #syserr.compare
 [syserr.errcat]: #syserr.errcat
 [syserr.errcat.derived]: #syserr.errcat.derived
@@ -1197,10 +1789,11 @@ constructor.
 [syserr.errcondition.constructors]: #syserr.errcondition.constructors
 [syserr.errcondition.modifiers]: #syserr.errcondition.modifiers
 [syserr.errcondition.nonmembers]: #syserr.errcondition.nonmembers
 [syserr.errcondition.observers]: #syserr.errcondition.observers
 [syserr.errcondition.overview]: #syserr.errcondition.overview
 [syserr.hash]: #syserr.hash
 [syserr.syserr]: #syserr.syserr
 [syserr.syserr.members]: #syserr.syserr.members
 [syserr.syserr.overview]: #syserr.syserr.overview
 [system.error.syn]: #system.error.syn

 This Clause describes components that C++ programs may use to detect and
 report error conditions.
 The following subclauses describe components for reporting several kinds
+of exceptional conditions, documenting program assertions, obtaining
+stacktraces, and a global variable for error number codes, as summarized
+in [[diagnostics.summary]].
 **Table: Diagnostics library summary** <a id="diagnostics.summary">[diagnostics.summary]</a>
 | Subclause          |                      | Header           |
 | ------------------ | -------------------- | ---------------- |
 | [[std.exceptions]] | Exception classes    | `<stdexcept>`    |
 | [[assertions]]     | Assertions           | `<cassert>`      |
 | [[errno]]          | Error numbers        | `<cerrno>`       |
 | [[syserr]]         | System error support | `<system_error>` |
+| [[stacktrace]]     | Stacktrace           | `<stacktrace>`   |
 ## Exception classes <a id="std.exceptions">[[std.exceptions]]</a>
+### General <a id="std.exceptions.general">[[std.exceptions.general]]</a>
 The C++ standard library provides classes to be used to report certain
 errors [[res.on.exception.handling]] in C++ programs. In the error model
 reflected in these classes, errors are divided into two broad
 categories: *logic* errors and *runtime* errors.
 *Ensures:* `strcmp(what(), what_arg) == 0`.
 ## Assertions <a id="assertions">[[assertions]]</a>
+### General <a id="assertions.general">[[assertions.general]]</a>
 The header `<cassert>` provides a macro for documenting C++ program
 assertions and a mechanism for disabling the assertion checks.
 ### Header `<cassert>` synopsis <a id="cassert.syn">[[cassert.syn]]</a>
 - `E` contextually converted to `bool` [[conv]] is a constant
   subexpression that evaluates to the value `true`.
 ## Error numbers <a id="errno">[[errno]]</a>
+### General <a id="errno.general">[[errno.general]]</a>
 The contents of the header `<cerrno>` are the same as the POSIX header
 `<errno.h>`, except that `errno` shall be defined as a macro.
 [*Note 1*: The intent is to remain in close alignment with the POSIX
 standard. — *end note*]
+A separate `errno` value is provided for each thread.
 ### Header `<cerrno>` synopsis <a id="cerrno.syn">[[cerrno.syn]]</a>
 ``` cpp
 #define errno see below
 #define ENETDOWN see below
 #define ENETRESET see below
 #define ENETUNREACH see below
 #define ENFILE see below
 #define ENOBUFS see below
 #define ENODEV see below
 #define ENOENT see below
 #define ENOEXEC see below
 #define ENOLCK see below
 #define ENOLINK see below
 #define ENOMEM see below
 #define ENOMSG see below
 #define ENOPROTOOPT see below
 #define ENOSPC see below
 #define ENOSYS see below
 #define ENOTCONN see below
 #define ENOTDIR see below
 #define ENOTEMPTY see below
 #define ENOTRECOVERABLE see below
 #define EPROTOTYPE see below
 #define ERANGE see below
 #define EROFS see below
 #define ESPIPE see below
 #define ESRCH see below
 #define ETIMEDOUT see below
 #define ETXTBSY see below
 #define EWOULDBLOCK see below
 #define EXDEV see below
 ```
 See also: ISO C 7.5
 ## System error support <a id="syserr">[[syserr]]</a>
+### General <a id="syserr.general">[[syserr.general]]</a>
+Subclause [[syserr]] describes components that the standard library and
+C++ programs may use to report error conditions originating from the
 operating system or other low-level application program interfaces.
+Components described in [[syserr]] do not change the value of `errno`
+[[errno]].
+*Recommended practice:* Implementations should leave the error states
 provided by other libraries unchanged.
 ### Header `<system_error>` synopsis <a id="system.error.syn">[[system.error.syn]]</a>
 ``` cpp
     network_unreachable,                // ENETUNREACH
     no_buffer_space,                    // ENOBUFS
     no_child_process,                   // ECHILD
     no_link,                            // ENOLINK
     no_lock_available,                  // ENOLCK
     no_message,                         // ENOMSG
     no_protocol_option,                 // ENOPROTOOPT
     no_space_on_device,                 // ENOSPC
     no_such_device_or_address,          // ENXIO
     no_such_device,                     // ENODEV
     no_such_file_or_directory,          // ENOENT
     no_such_process,                    // ESRCH
     not_a_directory,                    // ENOTDIR
     not_a_socket,                       // ENOTSOCK
     not_connected,                      // ENOTCONN
     not_enough_memory,                  // ENOMEM
     not_supported,                      // ENOTSUP
     operation_canceled,                 // ECANCELED
     operation_in_progress,              // EINPROGRESS
     read_only_file_system,              // EROFS
     resource_deadlock_would_occur,      // EDEADLK
     resource_unavailable_try_again,     // EAGAIN
     result_out_of_range,                // ERANGE
     state_not_recoverable,              // ENOTRECOVERABLE
     text_file_busy,                     // ETXTBSY
     timed_out,                          // ETIMEDOUT
     too_many_files_open_in_system,      // ENFILE
     too_many_files_open,                // EMFILE
     too_many_links,                     // EMLINK
       operator<<(basic_ostream<charT, traits>& os, const error_code& ec);
   // [syserr.errcondition.nonmembers], non-member functions
   error_condition make_error_condition(errc e) noexcept;
+  // [syserr.compare], comparison operator functions
   bool operator==(const error_code& lhs, const error_code& rhs) noexcept;
   bool operator==(const error_code& lhs, const error_condition& rhs) noexcept;
   bool operator==(const error_condition& lhs, const error_condition& rhs) noexcept;
   strong_ordering operator<=>(const error_code& lhs, const error_code& rhs) noexcept;
   strong_ordering operator<=>(const error_condition& lhs, const error_condition& rhs) noexcept;
   template<> struct hash<error_code>;
   template<> struct hash<error_condition>;
   // [syserr], system error support
   template<class T>
+    constexpr bool is_error_code_enum_v = is_error_code_enum<T>::value;
   template<class T>
+    constexpr bool is_error_condition_enum_v = is_error_condition_enum<T>::value;
 }
 ```
+The value of each `enum errc` enumerator is the same as the value of the
+`<cerrno>` macro shown in the above synopsis. Whether or not the
 `<system_error>` implementation exposes the `<cerrno>` macros is
 unspecified.
+The `is_error_code_enum` and `is_error_condition_enum` templates may be
 specialized for program-defined types to indicate that such types are
+eligible for `class error_code` and `class error_condition` implicit
 conversions, respectively.
 ### Class `error_category` <a id="syserr.errcat">[[syserr.errcat]]</a>
 #### Overview <a id="syserr.errcat.overview">[[syserr.errcat.overview]]</a>
 Classes may be derived from `error_category` to support categories of
 errors in addition to those defined in this document. Such classes shall
 behave as specified in subclause  [[syserr.errcat]].
 [*Note 1*: `error_category` objects are passed by reference, and two
+such objects are equal if they have the same address. If there is more
+than a single object of a custom `error_category` type, such equality
+comparisons can evaluate to `false` even for objects holding the same
+value. — *end note*]
 ``` cpp
 namespace std {
   class error_category {
   public:
 *Remarks:* The object’s `equivalent` virtual functions shall behave as
 specified for class `error_category`. The object’s `name` virtual
 function shall return a pointer to the string `"system"`. The object’s
 `default_error_condition` virtual function shall behave as follows:
+If the argument `ev` is equal to 0, the function returns
+`error_condition(0, generic_category())`. Otherwise, if `ev` corresponds
+to a POSIX `errno` value `pxv`, the function returns
+`error_condition(pxv, generic_category())`. Otherwise, the function
+returns `error_condition(ev, system_category())`. What constitutes
 correspondence for any given operating system is unspecified.
 [*Note 1*: The number of potential system error codes is large and
+unbounded, and some might not correspond to any POSIX `errno` value.
+Thus implementations are given latitude in determining
 correspondence. — *end note*]
 ### Class `error_code` <a id="syserr.errcode">[[syserr.errcode]]</a>
 #### Overview <a id="syserr.errcode.overview">[[syserr.errcode.overview]]</a>
 ``` cpp
 error_code() noexcept;
 ```
+*Effects:* Initializes `val_` with `0` and `cat_` with
+`&system_category()`.
 ``` cpp
 error_code(int val, const error_category& cat) noexcept;
 ```
+*Effects:* Initializes `val_` with `val` and `cat_` with `&cat`.
 ``` cpp
 template<class ErrorCodeEnum>
   error_code(ErrorCodeEnum e) noexcept;
 ```
 *Constraints:* `is_error_code_enum_v<ErrorCodeEnum>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+error_code ec = make_error_code(e);
+assign(ec.value(), ec.category());
+```
 #### Modifiers <a id="syserr.errcode.modifiers">[[syserr.errcode.modifiers]]</a>
 ``` cpp
 void assign(int val, const error_category& cat) noexcept;
   error_code& operator=(ErrorCodeEnum e) noexcept;
 ```
 *Constraints:* `is_error_code_enum_v<ErrorCodeEnum>` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+error_code ec = make_error_code(e);
+assign(ec.value(), ec.category());
+```
 *Returns:* `*this`.
 ``` cpp
 void clear() noexcept;
 ``` cpp
 error_condition() noexcept;
 ```
+*Effects:* Initializes `val_` with `0` and `cat_` with
+`&generic_category()`.
 ``` cpp
 error_condition(int val, const error_category& cat) noexcept;
 ```
+*Effects:* Initializes `val_` with `val` and `cat_` with `&cat`.
 ``` cpp
 template<class ErrorConditionEnum>
   error_condition(ErrorConditionEnum e) noexcept;
 ```
 *Constraints:* `is_error_condition_enum_v<ErrorConditionEnum>` is
 `true`.
+*Effects:* Equivalent to:
+``` cpp
+error_condition ec = make_error_condition(e);
+assign(ec.value(), ec.category());
+```
 #### Modifiers <a id="syserr.errcondition.modifiers">[[syserr.errcondition.modifiers]]</a>
 ``` cpp
 void assign(int val, const error_category& cat) noexcept;
 ```
 *Constraints:* `is_error_condition_enum_v<ErrorConditionEnum>` is
 `true`.
+*Effects:* Equivalent to:
+``` cpp
+error_condition ec = make_error_condition(e);
+assign(ec.value(), ec.category());
+```
 *Returns:* `*this`.
 ``` cpp
 void clear() noexcept;
 error_condition make_error_condition(errc e) noexcept;
 ```
 *Returns:* `error_condition(static_cast<int>(e), generic_category())`.
+### Comparison operator functions <a id="syserr.compare">[[syserr.compare]]</a>
 ``` cpp
 bool operator==(const error_code& lhs, const error_code& rhs) noexcept;
 ```
 constructor.
 [*Note 1*: The returned NTBS might be the contents of
 `what_arg + ": " + code.message()`. — *end note*]
+## Stacktrace <a id="stacktrace">[[stacktrace]]</a>
+### General <a id="stacktrace.general">[[stacktrace.general]]</a>
+Subclause [[stacktrace]] describes components that C++ programs may use
+to store the stacktrace of the current thread of execution and query
+information about the stored stacktrace at runtime.
+The *invocation sequence* of the current evaluation x₀ in the current
+thread of execution is a sequence (x₀, …, xₙ) of evaluations such that,
+for i ≥ 0, xᵢ is within the function invocation xᵢ₊₁
+[[intro.execution]].
+A *stacktrace* is an approximate representation of an invocation
+sequence and consists of stacktrace entries. A *stacktrace entry*
+represents an evaluation in a stacktrace.
+### Header `<stacktrace>` synopsis <a id="stacktrace.syn">[[stacktrace.syn]]</a>
+``` cpp
+#include <compare>              // see [compare.syn]
+namespace std {
+  // [stacktrace.entry], class stacktrace_entry
+  class stacktrace_entry;
+  // [stacktrace.basic], class template basic_stacktrace
+  template<class Allocator>
+    class basic_stacktrace;
+  // basic_stacktrace typedef-names
+  using stacktrace = basic_stacktrace<allocator<stacktrace_entry>>;
+  // [stacktrace.basic.nonmem], non-member functions
+  template<class Allocator>
+    void swap(basic_stacktrace<Allocator>& a, basic_stacktrace<Allocator>& b)
+      noexcept(noexcept(a.swap(b)));
+  string to_string(const stacktrace_entry& f);
+  template<class Allocator>
+    string to_string(const basic_stacktrace<Allocator>& st);
+  ostream& operator<<(ostream& os, const stacktrace_entry& f);
+  template<class Allocator>
+    ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);
+  // [stacktrace.format], formatting support
+  template<> struct formatter<stacktrace_entry>;
+  template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;
+  namespace pmr {
+    using stacktrace = basic_stacktrace<polymorphic_allocator<stacktrace_entry>>;
+  }
+  // [stacktrace.basic.hash], hash support
+  template<class T> struct hash;
+  template<> struct hash<stacktrace_entry>;
+  template<class Allocator> struct hash<basic_stacktrace<Allocator>>;
+}
+```
+### Class `stacktrace_entry` <a id="stacktrace.entry">[[stacktrace.entry]]</a>
+#### Overview <a id="stacktrace.entry.overview">[[stacktrace.entry.overview]]</a>
+``` cpp
+namespace std {
+  class stacktrace_entry {
+  public:
+    using native_handle_type = implementation-defined  // stacktrace_entry::native_handle_type;
+    // [stacktrace.entry.cons], constructors
+    constexpr stacktrace_entry() noexcept;
+    constexpr stacktrace_entry(const stacktrace_entry& other) noexcept;
+    constexpr stacktrace_entry& operator=(const stacktrace_entry& other) noexcept;
+    ~stacktrace_entry();
+    // [stacktrace.entry.obs], observers
+    constexpr native_handle_type native_handle() const noexcept;
+    constexpr explicit operator bool() const noexcept;
+    // [stacktrace.entry.query], query
+    string description() const;
+    string source_file() const;
+    uint_least32_t source_line() const;
+    // [stacktrace.entry.cmp], comparison
+    friend constexpr bool operator==(const stacktrace_entry& x,
+                                     const stacktrace_entry& y) noexcept;
+    friend constexpr strong_ordering operator<=>(const stacktrace_entry& x,
+                                                 const stacktrace_entry& y) noexcept;
+  };
+}
+```
+An object of type `stacktrace_entry` is either empty, or represents a
+stacktrace entry and provides operations for querying information about
+it. The class `stacktrace_entry` models `regular` [[concepts.object]]
+and `three_way_comparable<strong_ordering>` [[cmp.concept]].
+#### Constructors <a id="stacktrace.entry.cons">[[stacktrace.entry.cons]]</a>
+``` cpp
+constexpr stacktrace_entry() noexcept;
+```
+*Ensures:* `*this` is empty.
+#### Observers <a id="stacktrace.entry.obs">[[stacktrace.entry.obs]]</a>
+``` cpp
+constexpr native_handle_type native_handle() const noexcept;
+```
+The semantics of this function are *implementation-defined*.
+*Remarks:* Successive invocations of the `native_handle` function for an
+unchanged `stacktrace_entry` object return identical values.
+``` cpp
+constexpr explicit operator bool() const noexcept;
+```
+*Returns:* `false` if and only if `*this` is empty.
+#### Query <a id="stacktrace.entry.query">[[stacktrace.entry.query]]</a>
+[*Note 1*: All the `stacktrace_entry` query functions treat errors
+other than memory allocation errors as “no information available” and do
+not throw in that case. — *end note*]
+``` cpp
+string description() const;
+```
+*Returns:* A description of the evaluation represented by `*this`, or an
+empty string.
+*Throws:* `bad_alloc` if memory for the internal data structures or the
+resulting string cannot be allocated.
+``` cpp
+string source_file() const;
+```
+*Returns:* The presumed or actual name of the source
+file [[cpp.predefined]] that lexically contains the expression or
+statement whose evaluation is represented by `*this`, or an empty
+string.
+*Throws:* `bad_alloc` if memory for the internal data structures or the
+resulting string cannot be allocated.
+``` cpp
+uint_least32_t source_line() const;
+```
+*Returns:* `0`, or a 1-based line number that lexically relates to the
+evaluation represented by `*this`. If `source_file` returns the presumed
+name of the source file, returns the presumed line number; if
+`source_file` returns the actual name of the source file, returns the
+actual line number.
+*Throws:* `bad_alloc` if memory for the internal data structures cannot
+be allocated.
+#### Comparison <a id="stacktrace.entry.cmp">[[stacktrace.entry.cmp]]</a>
+``` cpp
+friend constexpr bool operator==(const stacktrace_entry& x, const stacktrace_entry& y) noexcept;
+```
+*Returns:* `true` if and only if `x` and `y` represent the same
+stacktrace entry or both `x` and `y` are empty.
+### Class template `basic_stacktrace` <a id="stacktrace.basic">[[stacktrace.basic]]</a>
+#### Overview <a id="stacktrace.basic.overview">[[stacktrace.basic.overview]]</a>
+``` cpp
+namespace std {
+  template<class Allocator>
+  class basic_stacktrace {
+  public:
+    using value_type = stacktrace_entry;
+    using const_reference = const value_type&;
+    using reference = value_type&;
+    using const_iterator = implementation-defined  // type of basic_stacktrace::const_iterator;  // see [stacktrace.basic.obs]
+    using iterator = const_iterator;
+    using reverse_iterator = std::reverse_iterator<iterator>;
+    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
+    using difference_type = implementation-defined  // type of basic_stacktrace::difference_type;
+    using size_type = implementation-defined  // type of basic_stacktrace::size_type;
+    using allocator_type = Allocator;
+    // [stacktrace.basic.cons], creation and assignment
+    static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;
+    static basic_stacktrace current(size_type skip,
+                                    const allocator_type& alloc = allocator_type()) noexcept;
+    static basic_stacktrace current(size_type skip, size_type max_depth,
+                                    const allocator_type& alloc = allocator_type()) noexcept;
+    basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);
+    explicit basic_stacktrace(const allocator_type& alloc) noexcept;
+    basic_stacktrace(const basic_stacktrace& other);
+    basic_stacktrace(basic_stacktrace&& other) noexcept;
+    basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc);
+    basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc);
+    basic_stacktrace& operator=(const basic_stacktrace& other);
+    basic_stacktrace& operator=(basic_stacktrace&& other)
+      noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
+        allocator_traits<Allocator>::is_always_equal::value);
+    ~basic_stacktrace();
+    // [stacktrace.basic.obs], observers
+    allocator_type get_allocator() const noexcept;
+    const_iterator begin() const noexcept;
+    const_iterator end() const noexcept;
+    const_reverse_iterator rbegin() const noexcept;
+    const_reverse_iterator rend() const noexcept;
+    const_iterator cbegin() const noexcept;
+    const_iterator cend() const noexcept;
+    const_reverse_iterator crbegin() const noexcept;
+    const_reverse_iterator crend() const noexcept;
+    [[nodiscard]] bool empty() const noexcept;
+    size_type size() const noexcept;
+    size_type max_size() const noexcept;
+    const_reference operator[](size_type) const;
+    const_reference at(size_type) const;
+    // [stacktrace.basic.cmp], comparisons
+    template<class Allocator2>
+    friend bool operator==(const basic_stacktrace& x,
+                           const basic_stacktrace<Allocator2>& y) noexcept;
+    template<class Allocator2>
+    friend strong_ordering operator<=>(const basic_stacktrace& x,
+                                       const basic_stacktrace<Allocator2>& y) noexcept;
+    // [stacktrace.basic.mod], modifiers
+    void swap(basic_stacktrace& other)
+      noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
+        allocator_traits<Allocator>::is_always_equal::value);
+  private:
+    vector<value_type, allocator_type> frames_;         // exposition only
+  };
+}
+```
+The class template `basic_stacktrace` satisfies the requirements of a
+reversible container [[container.rev.reqmts]], of an allocator-aware
+container [[container.alloc.reqmts]], and of a sequence container
+[[sequence.reqmts]], except that
+- only move, assignment, swap, and operations defined for
+  const-qualified sequence containers are supported and,
+- the semantics of comparison functions are different from those
+  required for a container.
+#### Creation and assignment <a id="stacktrace.basic.cons">[[stacktrace.basic.cons]]</a>
+``` cpp
+static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;
+```
+*Returns:* A `basic_stacktrace` object with `frames_` storing the
+stacktrace of the current evaluation in the current thread of execution,
+or an empty `basic_stacktrace` object if the initialization of `frames_`
+failed. `alloc` is passed to the constructor of the `frames_` object.
+[*Note 1*: If the stacktrace was successfully obtained, then
+`frames_.front()` is the `stacktrace_entry` representing approximately
+the current evaluation, and `frames_.back()` is the `stacktrace_entry`
+representing approximately the initial function of the current thread of
+execution. — *end note*]
+``` cpp
+static basic_stacktrace current(size_type skip,
+                                const allocator_type& alloc = allocator_type()) noexcept;
+```
+Let `t` be a stacktrace as-if obtained via
+`basic_stacktrace::current(alloc)`. Let `n` be `t.size()`.
+*Returns:* A `basic_stacktrace` object where `frames_` is
+direct-non-list-initialized from arguments `t.begin() + min(n, skip)`,
+`t.end()`, and `alloc`, or an empty `basic_stacktrace` object if the
+initialization of `frames_` failed.
+``` cpp
+static basic_stacktrace current(size_type skip, size_type max_depth,
+                                const allocator_type& alloc = allocator_type()) noexcept;
+```
+Let `t` be a stacktrace as-if obtained via
+`basic_stacktrace::current(alloc)`. Let `n` be `t.size()`.
+*Preconditions:* `skip <= skip + max_depth` is `true`.
+*Returns:* A `basic_stacktrace` object where `frames_` is
+direct-non-list-initialized from arguments `t.begin() + min(n, skip)`,
+`t.begin() + min(n, skip + max_depth)`, and `alloc`, or an empty
+`basic_stacktrace` object if the initialization of `frames_` failed.
+``` cpp
+basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);
+```
+*Ensures:* `empty()` is `true`.
+``` cpp
+explicit basic_stacktrace(const allocator_type& alloc) noexcept;
+```
+*Effects:* `alloc` is passed to the `frames_` constructor.
+*Ensures:* `empty()` is `true`.
+``` cpp
+basic_stacktrace(const basic_stacktrace& other);
+basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc);
+basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc);
+basic_stacktrace& operator=(const basic_stacktrace& other);
+basic_stacktrace& operator=(basic_stacktrace&& other)
+  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
+    allocator_traits<Allocator>::is_always_equal::value);
+```
+*Remarks:* Implementations may strengthen the exception specification
+for these functions [[res.on.exception.handling]] by ensuring that
+`empty()` is `true` on failed allocation.
+#### Observers <a id="stacktrace.basic.obs">[[stacktrace.basic.obs]]</a>
+``` cpp
+using const_iterator = implementation-defined;
+```
+The type models `random_access_iterator`
+[[iterator.concept.random.access]] and meets the
+*Cpp17RandomAccessIterator* requirements [[random.access.iterators]].
+``` cpp
+allocator_type get_allocator() const noexcept;
+```
+*Returns:* `frames_.get_allocator()`.
+``` cpp
+const_iterator begin() const noexcept;
+const_iterator cbegin() const noexcept;
+```
+*Returns:* An iterator referring to the first element in `frames_`. If
+`empty()` is `true`, then it returns the same value as `end()`.
+``` cpp
+const_iterator end() const noexcept;
+const_iterator cend() const noexcept;
+```
+*Returns:* The end iterator.
+``` cpp
+const_reverse_iterator rbegin() const noexcept;
+const_reverse_iterator crbegin() const noexcept;
+```
+*Returns:* `reverse_iterator(cend())`.
+``` cpp
+const_reverse_iterator rend() const noexcept;
+const_reverse_iterator crend() const noexcept;
+```
+*Returns:* `reverse_iterator(cbegin())`.
+``` cpp
+[[nodiscard]] bool empty() const noexcept;
+```
+*Returns:* `frames_.empty()`.
+``` cpp
+size_type size() const noexcept;
+```
+*Returns:* `frames_.size()`.
+``` cpp
+size_type max_size() const noexcept;
+```
+*Returns:* `frames_.max_size()`.
+``` cpp
+const_reference operator[](size_type frame_no) const;
+```
+*Preconditions:* `frame_no < size()` is `true`.
+*Returns:* `frames_[frame_no]`.
+*Throws:* Nothing.
+``` cpp
+const_reference at(size_type frame_no) const;
+```
+*Returns:* `frames_[frame_no]`.
+*Throws:* `out_of_range` if `frame_no >= size()`.
+#### Comparisons <a id="stacktrace.basic.cmp">[[stacktrace.basic.cmp]]</a>
+``` cpp
+template<class Allocator2>
+friend bool operator==(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
+```
+*Returns:* `equal(x.begin(), x.end(), y.begin(), y.end())`.
+``` cpp
+template<class Allocator2>
+friend strong_ordering
+  operator<=>(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
+```
+*Returns:* `x.size() <=> y.size()` if `x.size() != y.size()`;
+`lexicographical_compare_three_way(x.begin(), x.end(), y.begin(), y.end())`
+otherwise.
+#### Modifiers <a id="stacktrace.basic.mod">[[stacktrace.basic.mod]]</a>
+``` cpp
+void swap(basic_stacktrace& other)
+  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
+    allocator_traits<Allocator>::is_always_equal::value);
+```
+*Effects:* Exchanges the contents of `*this` and `other`.
+#### Non-member functions <a id="stacktrace.basic.nonmem">[[stacktrace.basic.nonmem]]</a>
+``` cpp
+template<class Allocator>
+void swap(basic_stacktrace<Allocator>& a, basic_stacktrace<Allocator>& b)
+  noexcept(noexcept(a.swap(b)));
+```
+*Effects:* Equivalent to `a.swap(b)`.
+``` cpp
+string to_string(const stacktrace_entry& f);
+```
+*Returns:* A string with a description of `f`.
+*Recommended practice:* The description should provide information about
+the contained evaluation, including information from `f.source_file()`
+and `f.source_line()`.
+``` cpp
+template<class Allocator>
+string to_string(const basic_stacktrace<Allocator>& st);
+```
+*Returns:* A string with a description of `st`.
+[*Note 1*: The number of lines is not guaranteed to be equal to
+`st.size()`. — *end note*]
+``` cpp
+ostream& operator<<(ostream& os, const stacktrace_entry& f);
+```
+*Effects:* Equivalent to: `return os << to_string(f);`
+``` cpp
+template<class Allocator>
+  ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);
+```
+*Effects:* Equivalent to: `return os << to_string(st);`
+#### Formatting support <a id="stacktrace.format">[[stacktrace.format]]</a>
+``` cpp
+template<> struct formatter<stacktrace_entry>;
+```
+`formatter<stacktrace_entry>` interprets *format-spec* as a
+*stacktrace-entry-format-spec*. The syntax of format specifications is
+as follows:
+``` bnf
+stacktrace-entry-format-spec
+    fill-and-alignₒₚₜ widthₒₚₜ
+```
+[*Note 1*: The productions *fill-and-align* and *width* are described
+in [[format.string.std]]. — *end note*]
+A `stacktrace_entry` object `se` is formatted as if by copying
+`to_string(se)` through the output iterator of the context with
+additional padding and adjustments as specified by the format
+specifiers.
+``` cpp
+template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;
+```
+For `formatter<basic_stacktrace<Allocator>>`, *format-spec* is empty.
+A `basic_stacktrace<Allocator>` object `s` is formatted as if by copying
+`to_string(s)` through the output iterator of the context.
+#### Hash support <a id="stacktrace.basic.hash">[[stacktrace.basic.hash]]</a>
+``` cpp
+template<> struct hash<stacktrace_entry>;
+template<class Allocator> struct hash<basic_stacktrace<Allocator>>;
+```
+The specializations are enabled [[unord.hash]].
 <!-- Link reference definitions -->
 [assertions]: #assertions
 [assertions.assert]: #assertions.assert
+[assertions.general]: #assertions.general
 [bad.alloc]: support.md#bad.alloc
 [cassert.syn]: #cassert.syn
 [cerrno.syn]: #cerrno.syn
+[cmp.concept]: support.md#cmp.concept
 [comparisons.three.way]: utilities.md#comparisons.three.way
+[concepts.object]: concepts.md#concepts.object
+[container.alloc.reqmts]: containers.md#container.alloc.reqmts
+[container.rev.reqmts]: containers.md#container.rev.reqmts
 [conv]: expr.md#conv
+[cpp.predefined]: cpp.md#cpp.predefined
+[defns.const.subexpr]: intro.md#defns.const.subexpr
 [diagnostics]: #diagnostics
 [diagnostics.general]: #diagnostics.general
 [diagnostics.summary]: #diagnostics.summary
 [domain.error]: #domain.error
 [errno]: #errno
+[errno.general]: #errno.general
+[format.string.std]: utilities.md#format.string.std
+[intro.execution]: basic.md#intro.execution
 [invalid.argument]: #invalid.argument
+[iterator.concept.random.access]: iterators.md#iterator.concept.random.access
 [length.error]: #length.error
 [logic.error]: #logic.error
 [out.of.range]: #out.of.range
 [overflow.error]: #overflow.error
+[random.access.iterators]: iterators.md#random.access.iterators
 [range.error]: #range.error
 [res.on.exception.handling]: library.md#res.on.exception.handling
 [runtime.error]: #runtime.error
+[sequence.reqmts]: containers.md#sequence.reqmts
+[stacktrace]: #stacktrace
+[stacktrace.basic]: #stacktrace.basic
+[stacktrace.basic.cmp]: #stacktrace.basic.cmp
+[stacktrace.basic.cons]: #stacktrace.basic.cons
+[stacktrace.basic.hash]: #stacktrace.basic.hash
+[stacktrace.basic.mod]: #stacktrace.basic.mod
+[stacktrace.basic.nonmem]: #stacktrace.basic.nonmem
+[stacktrace.basic.obs]: #stacktrace.basic.obs
+[stacktrace.basic.overview]: #stacktrace.basic.overview
+[stacktrace.entry]: #stacktrace.entry
+[stacktrace.entry.cmp]: #stacktrace.entry.cmp
+[stacktrace.entry.cons]: #stacktrace.entry.cons
+[stacktrace.entry.obs]: #stacktrace.entry.obs
+[stacktrace.entry.overview]: #stacktrace.entry.overview
+[stacktrace.entry.query]: #stacktrace.entry.query
+[stacktrace.format]: #stacktrace.format
+[stacktrace.general]: #stacktrace.general
+[stacktrace.syn]: #stacktrace.syn
 [std.exceptions]: #std.exceptions
+[std.exceptions.general]: #std.exceptions.general
 [stdexcept.syn]: #stdexcept.syn
 [syserr]: #syserr
 [syserr.compare]: #syserr.compare
 [syserr.errcat]: #syserr.errcat
 [syserr.errcat.derived]: #syserr.errcat.derived
 [syserr.errcondition.constructors]: #syserr.errcondition.constructors
 [syserr.errcondition.modifiers]: #syserr.errcondition.modifiers
 [syserr.errcondition.nonmembers]: #syserr.errcondition.nonmembers
 [syserr.errcondition.observers]: #syserr.errcondition.observers
 [syserr.errcondition.overview]: #syserr.errcondition.overview
+[syserr.general]: #syserr.general
 [syserr.hash]: #syserr.hash
 [syserr.syserr]: #syserr.syserr
 [syserr.syserr.members]: #syserr.syserr.members
 [syserr.syserr.overview]: #syserr.syserr.overview
 [system.error.syn]: #system.error.syn

Diff to HTML by rtfpessoa