From Jason Turner

[stacktrace.basic]

C++20 → C++23 15.5 KB 443 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp_3gf0qum/{from.md → to.md} +440 -0
tmp/tmp_3gf0qum/{from.md → to.md} RENAMED
@@ -0,0 +1,440 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class template `basic_stacktrace` <a id="stacktrace.basic">[[stacktrace.basic]]</a>
2
+
3
+ #### Overview <a id="stacktrace.basic.overview">[[stacktrace.basic.overview]]</a>
4
+
5
+ ``` cpp
6
+ namespace std {
7
+ template<class Allocator>
8
+ class basic_stacktrace {
9
+ public:
10
+ using value_type = stacktrace_entry;
11
+ using const_reference = const value_type&;
12
+ using reference = value_type&;
13
+ using const_iterator = implementation-defined // type of basic_stacktrace::const_iterator; // see [stacktrace.basic.obs]
14
+ using iterator = const_iterator;
15
+ using reverse_iterator = std::reverse_iterator<iterator>;
16
+ using const_reverse_iterator = std::reverse_iterator<const_iterator>;
17
+ using difference_type = implementation-defined // type of basic_stacktrace::difference_type;
18
+ using size_type = implementation-defined // type of basic_stacktrace::size_type;
19
+ using allocator_type = Allocator;
20
+
21
+ // [stacktrace.basic.cons], creation and assignment
22
+ static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;
23
+ static basic_stacktrace current(size_type skip,
24
+ const allocator_type& alloc = allocator_type()) noexcept;
25
+ static basic_stacktrace current(size_type skip, size_type max_depth,
26
+ const allocator_type& alloc = allocator_type()) noexcept;
27
+
28
+ basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);
29
+ explicit basic_stacktrace(const allocator_type& alloc) noexcept;
30
+
31
+ basic_stacktrace(const basic_stacktrace& other);
32
+ basic_stacktrace(basic_stacktrace&& other) noexcept;
33
+ basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc);
34
+ basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc);
35
+ basic_stacktrace& operator=(const basic_stacktrace& other);
36
+ basic_stacktrace& operator=(basic_stacktrace&& other)
37
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
38
+ allocator_traits<Allocator>::is_always_equal::value);
39
+
40
+ ~basic_stacktrace();
41
+
42
+ // [stacktrace.basic.obs], observers
43
+ allocator_type get_allocator() const noexcept;
44
+
45
+ const_iterator begin() const noexcept;
46
+ const_iterator end() const noexcept;
47
+ const_reverse_iterator rbegin() const noexcept;
48
+ const_reverse_iterator rend() const noexcept;
49
+
50
+ const_iterator cbegin() const noexcept;
51
+ const_iterator cend() const noexcept;
52
+ const_reverse_iterator crbegin() const noexcept;
53
+ const_reverse_iterator crend() const noexcept;
54
+
55
+ [[nodiscard]] bool empty() const noexcept;
56
+ size_type size() const noexcept;
57
+ size_type max_size() const noexcept;
58
+
59
+ const_reference operator[](size_type) const;
60
+ const_reference at(size_type) const;
61
+
62
+ // [stacktrace.basic.cmp], comparisons
63
+ template<class Allocator2>
64
+ friend bool operator==(const basic_stacktrace& x,
65
+ const basic_stacktrace<Allocator2>& y) noexcept;
66
+ template<class Allocator2>
67
+ friend strong_ordering operator<=>(const basic_stacktrace& x,
68
+ const basic_stacktrace<Allocator2>& y) noexcept;
69
+
70
+ // [stacktrace.basic.mod], modifiers
71
+ void swap(basic_stacktrace& other)
72
+ noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
73
+ allocator_traits<Allocator>::is_always_equal::value);
74
+
75
+ private:
76
+ vector<value_type, allocator_type> frames_; // exposition only
77
+ };
78
+ }
79
+ ```
80
+
81
+ The class template `basic_stacktrace` satisfies the requirements of a
82
+ reversible container [[container.rev.reqmts]], of an allocator-aware
83
+ container [[container.alloc.reqmts]], and of a sequence container
84
+ [[sequence.reqmts]], except that
85
+
86
+ - only move, assignment, swap, and operations defined for
87
+ const-qualified sequence containers are supported and,
88
+ - the semantics of comparison functions are different from those
89
+ required for a container.
90
+
91
+ #### Creation and assignment <a id="stacktrace.basic.cons">[[stacktrace.basic.cons]]</a>
92
+
93
+ ``` cpp
94
+ static basic_stacktrace current(const allocator_type& alloc = allocator_type()) noexcept;
95
+ ```
96
+
97
+ *Returns:* A `basic_stacktrace` object with `frames_` storing the
98
+ stacktrace of the current evaluation in the current thread of execution,
99
+ or an empty `basic_stacktrace` object if the initialization of `frames_`
100
+ failed. `alloc` is passed to the constructor of the `frames_` object.
101
+
102
+ [*Note 1*: If the stacktrace was successfully obtained, then
103
+ `frames_.front()` is the `stacktrace_entry` representing approximately
104
+ the current evaluation, and `frames_.back()` is the `stacktrace_entry`
105
+ representing approximately the initial function of the current thread of
106
+ execution. — *end note*]
107
+
108
+ ``` cpp
109
+ static basic_stacktrace current(size_type skip,
110
+ const allocator_type& alloc = allocator_type()) noexcept;
111
+ ```
112
+
113
+ Let `t` be a stacktrace as-if obtained via
114
+ `basic_stacktrace::current(alloc)`. Let `n` be `t.size()`.
115
+
116
+ *Returns:* A `basic_stacktrace` object where `frames_` is
117
+ direct-non-list-initialized from arguments `t.begin() + min(n, skip)`,
118
+ `t.end()`, and `alloc`, or an empty `basic_stacktrace` object if the
119
+ initialization of `frames_` failed.
120
+
121
+ ``` cpp
122
+ static basic_stacktrace current(size_type skip, size_type max_depth,
123
+ const allocator_type& alloc = allocator_type()) noexcept;
124
+ ```
125
+
126
+ Let `t` be a stacktrace as-if obtained via
127
+ `basic_stacktrace::current(alloc)`. Let `n` be `t.size()`.
128
+
129
+ *Preconditions:* `skip <= skip + max_depth` is `true`.
130
+
131
+ *Returns:* A `basic_stacktrace` object where `frames_` is
132
+ direct-non-list-initialized from arguments `t.begin() + min(n, skip)`,
133
+ `t.begin() + min(n, skip + max_depth)`, and `alloc`, or an empty
134
+ `basic_stacktrace` object if the initialization of `frames_` failed.
135
+
136
+ ``` cpp
137
+ basic_stacktrace() noexcept(is_nothrow_default_constructible_v<allocator_type>);
138
+ ```
139
+
140
+ *Ensures:* `empty()` is `true`.
141
+
142
+ ``` cpp
143
+ explicit basic_stacktrace(const allocator_type& alloc) noexcept;
144
+ ```
145
+
146
+ *Effects:* `alloc` is passed to the `frames_` constructor.
147
+
148
+ *Ensures:* `empty()` is `true`.
149
+
150
+ ``` cpp
151
+ basic_stacktrace(const basic_stacktrace& other);
152
+ basic_stacktrace(const basic_stacktrace& other, const allocator_type& alloc);
153
+ basic_stacktrace(basic_stacktrace&& other, const allocator_type& alloc);
154
+ basic_stacktrace& operator=(const basic_stacktrace& other);
155
+ basic_stacktrace& operator=(basic_stacktrace&& other)
156
+ noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
157
+ allocator_traits<Allocator>::is_always_equal::value);
158
+ ```
159
+
160
+ *Remarks:* Implementations may strengthen the exception specification
161
+ for these functions [[res.on.exception.handling]] by ensuring that
162
+ `empty()` is `true` on failed allocation.
163
+
164
+ #### Observers <a id="stacktrace.basic.obs">[[stacktrace.basic.obs]]</a>
165
+
166
+ ``` cpp
167
+ using const_iterator = implementation-defined;
168
+ ```
169
+
170
+ The type models `random_access_iterator`
171
+ [[iterator.concept.random.access]] and meets the
172
+ *Cpp17RandomAccessIterator* requirements [[random.access.iterators]].
173
+
174
+ ``` cpp
175
+ allocator_type get_allocator() const noexcept;
176
+ ```
177
+
178
+ *Returns:* `frames_.get_allocator()`.
179
+
180
+ ``` cpp
181
+ const_iterator begin() const noexcept;
182
+ const_iterator cbegin() const noexcept;
183
+ ```
184
+
185
+ *Returns:* An iterator referring to the first element in `frames_`. If
186
+ `empty()` is `true`, then it returns the same value as `end()`.
187
+
188
+ ``` cpp
189
+ const_iterator end() const noexcept;
190
+ const_iterator cend() const noexcept;
191
+ ```
192
+
193
+ *Returns:* The end iterator.
194
+
195
+ ``` cpp
196
+ const_reverse_iterator rbegin() const noexcept;
197
+ const_reverse_iterator crbegin() const noexcept;
198
+ ```
199
+
200
+ *Returns:* `reverse_iterator(cend())`.
201
+
202
+ ``` cpp
203
+ const_reverse_iterator rend() const noexcept;
204
+ const_reverse_iterator crend() const noexcept;
205
+ ```
206
+
207
+ *Returns:* `reverse_iterator(cbegin())`.
208
+
209
+ ``` cpp
210
+ [[nodiscard]] bool empty() const noexcept;
211
+ ```
212
+
213
+ *Returns:* `frames_.empty()`.
214
+
215
+ ``` cpp
216
+ size_type size() const noexcept;
217
+ ```
218
+
219
+ *Returns:* `frames_.size()`.
220
+
221
+ ``` cpp
222
+ size_type max_size() const noexcept;
223
+ ```
224
+
225
+ *Returns:* `frames_.max_size()`.
226
+
227
+ ``` cpp
228
+ const_reference operator[](size_type frame_no) const;
229
+ ```
230
+
231
+ *Preconditions:* `frame_no < size()` is `true`.
232
+
233
+ *Returns:* `frames_[frame_no]`.
234
+
235
+ *Throws:* Nothing.
236
+
237
+ ``` cpp
238
+ const_reference at(size_type frame_no) const;
239
+ ```
240
+
241
+ *Returns:* `frames_[frame_no]`.
242
+
243
+ *Throws:* `out_of_range` if `frame_no >= size()`.
244
+
245
+ #### Comparisons <a id="stacktrace.basic.cmp">[[stacktrace.basic.cmp]]</a>
246
+
247
+ ``` cpp
248
+ template<class Allocator2>
249
+ friend bool operator==(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
250
+ ```
251
+
252
+ *Returns:* `equal(x.begin(), x.end(), y.begin(), y.end())`.
253
+
254
+ ``` cpp
255
+ template<class Allocator2>
256
+ friend strong_ordering
257
+ operator<=>(const basic_stacktrace& x, const basic_stacktrace<Allocator2>& y) noexcept;
258
+ ```
259
+
260
+ *Returns:* `x.size() <=> y.size()` if `x.size() != y.size()`;
261
+ `lexicographical_compare_three_way(x.begin(), x.end(), y.begin(), y.end())`
262
+ otherwise.
263
+
264
+ #### Modifiers <a id="stacktrace.basic.mod">[[stacktrace.basic.mod]]</a>
265
+
266
+ ``` cpp
267
+ void swap(basic_stacktrace& other)
268
+ noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
269
+ allocator_traits<Allocator>::is_always_equal::value);
270
+ ```
271
+
272
+ *Effects:* Exchanges the contents of `*this` and `other`.
273
+
274
+ #### Non-member functions <a id="stacktrace.basic.nonmem">[[stacktrace.basic.nonmem]]</a>
275
+
276
+ ``` cpp
277
+ template<class Allocator>
278
+ void swap(basic_stacktrace<Allocator>& a, basic_stacktrace<Allocator>& b)
279
+ noexcept(noexcept(a.swap(b)));
280
+ ```
281
+
282
+ *Effects:* Equivalent to `a.swap(b)`.
283
+
284
+ ``` cpp
285
+ string to_string(const stacktrace_entry& f);
286
+ ```
287
+
288
+ *Returns:* A string with a description of `f`.
289
+
290
+ *Recommended practice:* The description should provide information about
291
+ the contained evaluation, including information from `f.source_file()`
292
+ and `f.source_line()`.
293
+
294
+ ``` cpp
295
+ template<class Allocator>
296
+ string to_string(const basic_stacktrace<Allocator>& st);
297
+ ```
298
+
299
+ *Returns:* A string with a description of `st`.
300
+
301
+ [*Note 1*: The number of lines is not guaranteed to be equal to
302
+ `st.size()`. — *end note*]
303
+
304
+ ``` cpp
305
+ ostream& operator<<(ostream& os, const stacktrace_entry& f);
306
+ ```
307
+
308
+ *Effects:* Equivalent to: `return os << to_string(f);`
309
+
310
+ ``` cpp
311
+ template<class Allocator>
312
+ ostream& operator<<(ostream& os, const basic_stacktrace<Allocator>& st);
313
+ ```
314
+
315
+ *Effects:* Equivalent to: `return os << to_string(st);`
316
+
317
+ #### Formatting support <a id="stacktrace.format">[[stacktrace.format]]</a>
318
+
319
+ ``` cpp
320
+ template<> struct formatter<stacktrace_entry>;
321
+ ```
322
+
323
+ `formatter<stacktrace_entry>` interprets *format-spec* as a
324
+ *stacktrace-entry-format-spec*. The syntax of format specifications is
325
+ as follows:
326
+
327
+ ``` bnf
328
+ stacktrace-entry-format-spec
329
+ fill-and-alignₒₚₜ widthₒₚₜ
330
+ ```
331
+
332
+ [*Note 1*: The productions *fill-and-align* and *width* are described
333
+ in [[format.string.std]]. — *end note*]
334
+
335
+ A `stacktrace_entry` object `se` is formatted as if by copying
336
+ `to_string(se)` through the output iterator of the context with
337
+ additional padding and adjustments as specified by the format
338
+ specifiers.
339
+
340
+ ``` cpp
341
+ template<class Allocator> struct formatter<basic_stacktrace<Allocator>>;
342
+ ```
343
+
344
+ For `formatter<basic_stacktrace<Allocator>>`, *format-spec* is empty.
345
+
346
+ A `basic_stacktrace<Allocator>` object `s` is formatted as if by copying
347
+ `to_string(s)` through the output iterator of the context.
348
+
349
+ #### Hash support <a id="stacktrace.basic.hash">[[stacktrace.basic.hash]]</a>
350
+
351
+ ``` cpp
352
+ template<> struct hash<stacktrace_entry>;
353
+ template<class Allocator> struct hash<basic_stacktrace<Allocator>>;
354
+ ```
355
+
356
+ The specializations are enabled [[unord.hash]].
357
+
358
+ <!-- Link reference definitions -->
359
+ [assertions]: #assertions
360
+ [assertions.assert]: #assertions.assert
361
+ [assertions.general]: #assertions.general
362
+ [bad.alloc]: support.md#bad.alloc
363
+ [cassert.syn]: #cassert.syn
364
+ [cerrno.syn]: #cerrno.syn
365
+ [cmp.concept]: support.md#cmp.concept
366
+ [comparisons.three.way]: utilities.md#comparisons.three.way
367
+ [concepts.object]: concepts.md#concepts.object
368
+ [container.alloc.reqmts]: containers.md#container.alloc.reqmts
369
+ [container.rev.reqmts]: containers.md#container.rev.reqmts
370
+ [conv]: expr.md#conv
371
+ [cpp.predefined]: cpp.md#cpp.predefined
372
+ [defns.const.subexpr]: intro.md#defns.const.subexpr
373
+ [diagnostics]: #diagnostics
374
+ [diagnostics.general]: #diagnostics.general
375
+ [diagnostics.summary]: #diagnostics.summary
376
+ [domain.error]: #domain.error
377
+ [errno]: #errno
378
+ [errno.general]: #errno.general
379
+ [format.string.std]: utilities.md#format.string.std
380
+ [intro.execution]: basic.md#intro.execution
381
+ [invalid.argument]: #invalid.argument
382
+ [iterator.concept.random.access]: iterators.md#iterator.concept.random.access
383
+ [length.error]: #length.error
384
+ [logic.error]: #logic.error
385
+ [out.of.range]: #out.of.range
386
+ [overflow.error]: #overflow.error
387
+ [random.access.iterators]: iterators.md#random.access.iterators
388
+ [range.error]: #range.error
389
+ [res.on.exception.handling]: library.md#res.on.exception.handling
390
+ [runtime.error]: #runtime.error
391
+ [sequence.reqmts]: containers.md#sequence.reqmts
392
+ [stacktrace]: #stacktrace
393
+ [stacktrace.basic]: #stacktrace.basic
394
+ [stacktrace.basic.cmp]: #stacktrace.basic.cmp
395
+ [stacktrace.basic.cons]: #stacktrace.basic.cons
396
+ [stacktrace.basic.hash]: #stacktrace.basic.hash
397
+ [stacktrace.basic.mod]: #stacktrace.basic.mod
398
+ [stacktrace.basic.nonmem]: #stacktrace.basic.nonmem
399
+ [stacktrace.basic.obs]: #stacktrace.basic.obs
400
+ [stacktrace.basic.overview]: #stacktrace.basic.overview
401
+ [stacktrace.entry]: #stacktrace.entry
402
+ [stacktrace.entry.cmp]: #stacktrace.entry.cmp
403
+ [stacktrace.entry.cons]: #stacktrace.entry.cons
404
+ [stacktrace.entry.obs]: #stacktrace.entry.obs
405
+ [stacktrace.entry.overview]: #stacktrace.entry.overview
406
+ [stacktrace.entry.query]: #stacktrace.entry.query
407
+ [stacktrace.format]: #stacktrace.format
408
+ [stacktrace.general]: #stacktrace.general
409
+ [stacktrace.syn]: #stacktrace.syn
410
+ [std.exceptions]: #std.exceptions
411
+ [std.exceptions.general]: #std.exceptions.general
412
+ [stdexcept.syn]: #stdexcept.syn
413
+ [syserr]: #syserr
414
+ [syserr.compare]: #syserr.compare
415
+ [syserr.errcat]: #syserr.errcat
416
+ [syserr.errcat.derived]: #syserr.errcat.derived
417
+ [syserr.errcat.nonvirtuals]: #syserr.errcat.nonvirtuals
418
+ [syserr.errcat.objects]: #syserr.errcat.objects
419
+ [syserr.errcat.overview]: #syserr.errcat.overview
420
+ [syserr.errcat.virtuals]: #syserr.errcat.virtuals
421
+ [syserr.errcode]: #syserr.errcode
422
+ [syserr.errcode.constructors]: #syserr.errcode.constructors
423
+ [syserr.errcode.modifiers]: #syserr.errcode.modifiers
424
+ [syserr.errcode.nonmembers]: #syserr.errcode.nonmembers
425
+ [syserr.errcode.observers]: #syserr.errcode.observers
426
+ [syserr.errcode.overview]: #syserr.errcode.overview
427
+ [syserr.errcondition]: #syserr.errcondition
428
+ [syserr.errcondition.constructors]: #syserr.errcondition.constructors
429
+ [syserr.errcondition.modifiers]: #syserr.errcondition.modifiers
430
+ [syserr.errcondition.nonmembers]: #syserr.errcondition.nonmembers
431
+ [syserr.errcondition.observers]: #syserr.errcondition.observers
432
+ [syserr.errcondition.overview]: #syserr.errcondition.overview
433
+ [syserr.general]: #syserr.general
434
+ [syserr.hash]: #syserr.hash
435
+ [syserr.syserr]: #syserr.syserr
436
+ [syserr.syserr.members]: #syserr.syserr.members
437
+ [syserr.syserr.overview]: #syserr.syserr.overview
438
+ [system.error.syn]: #system.error.syn
439
+ [underflow.error]: #underflow.error
440
+ [unord.hash]: utilities.md#unord.hash