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

Files changed (1) hide show

tmp/tmp0prulzxk/{from.md → to.md} +617 -0

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

	@@ -0,0 +1,617 @@

+## 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.errcat.nonvirtuals]: #syserr.errcat.nonvirtuals
+[syserr.errcat.objects]: #syserr.errcat.objects
+[syserr.errcat.overview]: #syserr.errcat.overview
+[syserr.errcat.virtuals]: #syserr.errcat.virtuals
+[syserr.errcode]: #syserr.errcode
+[syserr.errcode.constructors]: #syserr.errcode.constructors
+[syserr.errcode.modifiers]: #syserr.errcode.modifiers
+[syserr.errcode.nonmembers]: #syserr.errcode.nonmembers
+[syserr.errcode.observers]: #syserr.errcode.observers
+[syserr.errcode.overview]: #syserr.errcode.overview
+[syserr.errcondition]: #syserr.errcondition
+[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
+[underflow.error]: #underflow.error
+[unord.hash]: utilities.md#unord.hash

Diff to HTML by rtfpessoa