[stacktrace.basic]

# 19 Diagnostics library [[diagnostics]](./#diagnostics)

## 19.6 Stacktrace [[stacktrace]](stacktrace#basic)

### 19.6.4 Class template basic_stacktrace [stacktrace.basic]

#### [19.6.4.1](#overview) Overview [[stacktrace.basic.overview]](stacktrace.basic.overview)

namespace std {template<class Allocator>class [basic_stacktrace](#lib:basic_stacktrace "19.6.4.1 Overview [stacktrace.basic.overview]") {public:using value_type = stacktrace_entry; using const_reference = const value_type&; using reference = value_type&; using const_iterator = *implementation-defined*; // see [[stacktrace.basic.obs]](#obs "19.6.4.3 Observers")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*; using size_type = *implementation-defined*; using allocator_type = Allocator; // [[stacktrace.basic.cons]](#cons "19.6.4.2 Creation and assignment"), creation and assignmentstatic 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]](#obs "19.6.4.3 Observers"), 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; 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]](#cmp "19.6.4.4 Comparisons"), comparisonstemplate<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]](#mod "19.6.4.5 Modifiers"), modifiersvoid 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*};}

[1](#overview-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L1958)

The class template basic_stacktrace satisfies
the requirements
of a reversible container ([[container.rev.reqmts]](container.rev.reqmts "23.2.2.3 Reversible container requirements")),
of an allocator-aware container ([[container.alloc.reqmts]](container.alloc.reqmts "23.2.2.5 Allocator-aware containers")), and
of a sequence container ([[sequence.reqmts]](sequence.reqmts "23.2.4 Sequence containers")),
except that

- [(1.1)](#overview-1.1)

only move, assignment, swap, and
operations defined for const-qualified sequence containers are supported and,

- [(1.2)](#overview-1.2)

the semantics of comparison functions
are different from those required for a container[.](#overview-1.sentence-1)

#### [19.6.4.2](#cons) Creation and assignment [[stacktrace.basic.cons]](stacktrace.basic.cons)

[🔗](#lib:current,basic_stacktrace)

`static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;
`

[1](#cons-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L1982)

*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[.](#cons-1.sentence-1)

alloc is passed to the constructor of the *frames_* object[.](#cons-1.sentence-2)

[*Note [1](#cons-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[.](#cons-1.sentence-3)

— *end note*]

[🔗](#lib:current,basic_stacktrace_)

`static basic_stacktrace current(size_type skip,
                                const allocator_type& alloc = allocator_type()) noexcept;
`

[2](#cons-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2008)

Let t be a stacktrace
as-if obtained via basic_stacktrace​::​current(alloc)[.](#cons-2.sentence-1)

Let n be t.size()[.](#cons-2.sentence-2)

[3](#cons-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2013)

*Returns*: A basic_stacktrace object
where *frames_* is direct-non-list-initialized from argumentst.begin() + min(n, skip), t.end(), and alloc,
or an empty basic_stacktrace object
if the initialization of *frames_* failed[.](#cons-3.sentence-1)

[🔗](#lib:current,basic_stacktrace__)

`static basic_stacktrace current(size_type skip, size_type max_depth,
                                const allocator_type& alloc = allocator_type()) noexcept;
`

[4](#cons-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2029)

Let t be a stacktrace
as-if obtained via basic_stacktrace​::​current(alloc)[.](#cons-4.sentence-1)

Let n be t.size()[.](#cons-4.sentence-2)

[5](#cons-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2034)

*Hardened preconditions*: skip <= skip + max_depth is true[.](#cons-5.sentence-1)

[6](#cons-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2038)

*Returns*: A basic_stacktrace object
where *frames_* is direct-non-list-initialized from argumentst.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[.](#cons-6.sentence-1)

[🔗](#lib:basic_stacktrace,constructor)

`basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);
`

[7](#cons-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2054)

*Postconditions*: empty() is true[.](#cons-7.sentence-1)

[🔗](#lib:basic_stacktrace,constructor_)

`explicit basic_stacktrace(const allocator_type& alloc) noexcept;
`

[8](#cons-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2065)

*Effects*: alloc is passed to the *frames_* constructor[.](#cons-8.sentence-1)

[9](#cons-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2069)

*Postconditions*: empty() is true[.](#cons-9.sentence-1)

[🔗](#lib:basic_stacktrace,constructor__)

`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);
`

[10](#cons-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2087)

*Remarks*: Implementations may strengthen the exception specification
for these functions ([[res.on.exception.handling]](res.on.exception.handling "16.4.6.14 Restrictions on exception handling"))
by ensuring that empty() is true on failed allocation[.](#cons-10.sentence-1)

#### [19.6.4.3](#obs) Observers [[stacktrace.basic.obs]](stacktrace.basic.obs)

[🔗](#lib:const_iterator,basic_stacktrace)

`using const_iterator = implementation-defined;
`

[1](#obs-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2102)

The type models[random_access_iterator](iterator.concept.random.access#concept:random_access_iterator "24.3.4.13 Concept random_­access_­iterator [iterator.concept.random.access]") ([[iterator.concept.random.access]](iterator.concept.random.access "24.3.4.13 Concept random_­access_­iterator")) and
meets the*Cpp17RandomAccessIterator* requirements ([[random.access.iterators]](random.access.iterators "24.3.5.7 Random access iterators"))[.](#obs-1.sentence-1)

[🔗](#lib:get_allocator,basic_stacktrace)

`allocator_type get_allocator() const noexcept;
`

[2](#obs-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2115)

*Returns*: *frames_*.get_allocator()[.](#obs-2.sentence-1)

[🔗](#lib:begin,basic_stacktrace)

`const_iterator begin() const noexcept;
const_iterator cbegin() const noexcept;
`

[3](#obs-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2128)

*Returns*: An iterator referring to the first element in *frames_*[.](#obs-3.sentence-1)

If empty() is true,
then it returns the same value as end()[.](#obs-3.sentence-2)

[🔗](#lib:end,basic_stacktrace)

`const_iterator end() const noexcept;
const_iterator cend() const noexcept;
`

[4](#obs-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2143)

*Returns*: The end iterator[.](#obs-4.sentence-1)

[🔗](#lib:rbegin,basic_stacktrace)

`const_reverse_iterator rbegin() const noexcept;
const_reverse_iterator crbegin() const noexcept;
`

[5](#obs-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2156)

*Returns*: reverse_iterator(cend())[.](#obs-5.sentence-1)

[🔗](#lib:rend,basic_stacktrace)

`const_reverse_iterator rend() const noexcept;
const_reverse_iterator crend() const noexcept;
`

[6](#obs-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2169)

*Returns*: reverse_iterator(cbegin())[.](#obs-6.sentence-1)

[🔗](#lib:empty,basic_stacktrace)

`bool empty() const noexcept;
`

[7](#obs-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2180)

*Returns*: *frames_*.empty()[.](#obs-7.sentence-1)

[🔗](#lib:size,basic_stacktrace)

`size_type size() const noexcept;
`

[8](#obs-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2191)

*Returns*: *frames_*.size()[.](#obs-8.sentence-1)

[🔗](#lib:max_size,basic_stacktrace)

`size_type max_size() const noexcept;
`

[9](#obs-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2202)

*Returns*: *frames_*.max_size()[.](#obs-9.sentence-1)

[🔗](#lib:operator%5b%5d,basic_stacktrace)

`const_reference operator[](size_type frame_no) const;
`

[10](#obs-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2213)

*Hardened preconditions*: frame_no < size() is true[.](#obs-10.sentence-1)

[11](#obs-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2217)

*Returns*: *frames_*[frame_no][.](#obs-11.sentence-1)

[12](#obs-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2221)

*Throws*: Nothing[.](#obs-12.sentence-1)

[🔗](#lib:at,basic_stacktrace)

`const_reference at(size_type frame_no) const;
`

[13](#obs-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2232)

*Returns*: *frames_*[frame_no][.](#obs-13.sentence-1)

[14](#obs-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2236)

*Throws*: out_of_range if frame_no >= size()[.](#obs-14.sentence-1)

#### [19.6.4.4](#cmp) Comparisons [[stacktrace.basic.cmp]](stacktrace.basic.cmp)

[🔗](#lib:operator==,basic_stacktrace)

`template<class Allocator2>
friend bool operator==(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
`

[1](#cmp-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2250)

*Returns*: equal(x.begin(), x.end(), y.begin(), y.end())[.](#cmp-1.sentence-1)

[🔗](#lib:operator%3c=%3e,basic_stacktrace)

`template<class Allocator2>
friend strong_ordering
  operator<=>(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
`

[2](#cmp-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2263)

*Returns*: x.size() <=> y.size() if x.size() != y.size();lexicographical_compare_three_way(x.begin(), x.end(), y.begin(), y.end()) otherwise[.](#cmp-2.sentence-1)

#### [19.6.4.5](#mod) Modifiers [[stacktrace.basic.mod]](stacktrace.basic.mod)

[🔗](#lib:swap,basic_stacktrace)

`void swap(basic_stacktrace& other)
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
    allocator_traits<Allocator>::is_always_equal::value);
`

[1](#mod-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2280)

*Effects*: Exchanges the contents of *this and other[.](#mod-1.sentence-1)

#### [19.6.4.6](#nonmem) Non-member functions [[stacktrace.basic.nonmem]](stacktrace.basic.nonmem)

[🔗](#lib:swap,basic_stacktrace_)

`template<class Allocator>
void swap(basic_stacktrace<Allocator>& a, basic_stacktrace<Allocator>& b)
  noexcept(noexcept(a.swap(b)));
`

[1](#nonmem-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2295)

*Effects*: Equivalent to a.swap(b)[.](#nonmem-1.sentence-1)

[🔗](#lib:to_string,basic_stacktrace)

`string to_string(const stacktrace_entry& f);
`

[2](#nonmem-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2306)

*Returns*: A string with a description of f[.](#nonmem-2.sentence-1)

[3](#nonmem-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2310)

*Recommended practice*: The description should provide information about the contained evaluation,
including information fromf.source_file() and f.source_line()[.](#nonmem-3.sentence-1)

[🔗](#lib:to_string,basic_stacktrace_)

`template<class Allocator>
string to_string(const basic_stacktrace<Allocator>& st);
`

[4](#nonmem-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2324)

*Returns*: A string with a description of st[.](#nonmem-4.sentence-1)

[*Note [1](#nonmem-note-1)*:

The number of lines is not guaranteed to be equal to st.size()[.](#nonmem-4.sentence-2)

— *end note*]

[🔗](#lib:operator%3c%3c,stacktrace_entry)

`ostream& operator<<(ostream& os, const stacktrace_entry& f);
`

[5](#nonmem-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2338)

*Effects*: Equivalent to: return os << to_string(f);

[🔗](#lib:operator%3c%3c,basic_stacktrace)

`template<class Allocator>
  ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);
`

[6](#nonmem-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/diagnostics.tex#L2350)

*Effects*: Equivalent to: return os << to_string(st);