From Jason Turner

[requirements]

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpq15opv7l/{from.md → to.md} +502 -359
tmp/tmpq15opv7l/{from.md → to.md} RENAMED
@@ -15,59 +15,65 @@ constraints on types and functions used with the C++standard library,
15
  [[constraints]] describes constraints on well-formed C++programs, and
16
  [[conforming]] describes constraints on conforming implementations.
17
 
18
  ### Library contents and organization <a id="organization">[[organization]]</a>
19
 
20
- [[contents]] describes the entities defined in the C++standard library.
21
- [[headers]] lists the standard library headers and some constraints on
22
- those headers. [[compliance]] lists requirements for a freestanding
23
- implementation of the C++ standard library.
24
 
25
  #### Library contents <a id="contents">[[contents]]</a>
26
 
27
- The C++standard library provides definitions for the following types of
28
- entities: macros, values, types, templates, classes, functions, objects.
 
29
 
30
- All library entities except macros, `operator new` and `operator delete`
31
- are defined within the namespace `std` or namespaces nested within
32
- namespace `std`.[^14] It is unspecified whether names declared in a
33
- specific namespace are declared directly in that namespace or in an
34
- inline namespace inside that namespace.[^15]
35
 
36
  Whenever a name `x` defined in the standard library is mentioned, the
37
  name `x` is assumed to be fully qualified as `::std::x`, unless
38
- explicitly described otherwise. For example, if the Effects section for
39
- library function `F` is described as calling library function `G`, the
40
- function `::std::G` is meant.
41
 
42
  #### Headers <a id="headers">[[headers]]</a>
43
 
44
  Each element of the C++standard library is declared or defined (as
45
- appropriate) in a *header*.[^16]
46
 
47
- The C++standard library provides 53 *C++library headers*, as shown in
48
  Table  [[tab:cpp.library.headers]].
49
 
50
  **Table: C++library headers** <a id="tab:cpp.library.headers">[tab:cpp.library.headers]</a>
51
 
52
- | | | | | |
53
- | ---------------------- | -------------------- | ----------- | -------------------- | ----------------- |
54
- | `<algorithm>` | `<fstream>` | `<list>` | `<regex>` | `<tuple>` |
55
- | `<array>` | `<functional>` | `<locale>` | `<scoped_allocator>` | `<type_traits>` |
56
- | `<atomic>` | `<future>` | `<map>` | `<set>` | `<typeindex>` |
57
- | `<bitset>` | `<initializer_list>` | `<memory>` | `<sstream>` | `<typeinfo>` |
58
- | `<chrono>` | `<iomanip>` | `<mutex>` | `<stack>` | `<unordered_map>` |
59
- | `<codecvt>` | `<ios>` | `<new>` | `<stdexcept>` | `<unordered_set>` |
60
- | `<complex>` | `<iosfwd>` | `<numeric>` | `<streambuf>` | `<utility>` |
61
- | `<condition_variable>` | `<iostream>` | `<ostream>` | `<string>` | `<valarray>` |
62
- | `<deque>` | `<istream>` | `<queue>` | `<strstream>` | `<vector>` |
63
- | `<exception>` | `<iterator>` | `<random>` | `<system_error>` | |
64
- | `<forward_list>` | `<limits>` | `<ratio>` | `<thread>` | |
 
 
 
 
 
65
 
66
 
67
- The facilities of the C standard Library are provided in 26 additional
68
- headers, as shown in Table  [[tab:cpp.c.headers]].
69
 
70
  **Table: C++headers for C library facilities** <a id="tab:cpp.c.headers">[tab:cpp.c.headers]</a>
71
 
72
  | | | | | |
73
  | ------------ | ------------- | ------------- | ----------- | ----------- |
@@ -77,34 +83,77 @@ headers, as shown in Table  [[tab:cpp.c.headers]].
77
  | `<cerrno>` | `<clocale>` | `<cstdbool>` | `<ctgmath>` | |
78
  | `<cfenv>` | `<cmath>` | `<cstddef>` | `<ctime>` | |
79
  | `<cfloat>` | `<csetjmp>` | `<cstdint>` | `<cuchar>` | |
80
 
81
 
82
- Except as noted in Clauses  [[language.support]] through  [[thread]] and
83
- Annex  [[depr]], the contents of each header `cname` shall be the same
84
- as that of the corresponding header `name.h`, as specified in the C
85
- standard library ([[intro.refs]]) or the C Unicode TR, as appropriate,
86
- as if by inclusion. In the C++standard library, however, the
87
  declarations (except for names which are defined as macros in C) are
88
  within namespace scope ([[basic.scope.namespace]]) of the namespace
89
- `std.` It is unspecified whether these names are first declared within
90
- the global namespace scope and are then injected into namespace `std` by
91
- explicit *using-declaration*s ([[namespace.udecl]]).
 
 
92
 
93
  Names which are defined as macros in C shall be defined as macros in the
94
  C++ standard library, even if C grants license for implementation as
95
- functions. The names defined as macros in C include the following:
96
- `assert`, `offsetof`, `setjmp`, `va_arg`, `va_end`, and `va_start`.
 
 
 
97
 
98
  Names that are defined as functions in C shall be defined as functions
99
- in the C++standard library.[^17]
100
 
101
  Identifiers that are keywords or operators in C++shall not be defined as
102
- macros in C++standard library headers.[^18]
103
 
104
  [[depr.c.headers]], C standard library headers, describes the effects of
105
- using the `name.h` (C header) form in a C++program.[^19]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
106
 
107
  #### Freestanding implementations <a id="compliance">[[compliance]]</a>
108
 
109
  Two kinds of implementations are defined: *hosted* and *freestanding* (
110
  [[intro.compliance]]). For a hosted implementation, this International
@@ -115,23 +164,24 @@ headers. This set shall include at least the headers shown in Table 
115
  [[tab:cpp.headers.freestanding]].
116
 
117
  **Table: C++headers for freestanding implementations** <a id="tab:cpp.headers.freestanding">[tab:cpp.headers.freestanding]</a>
118
 
119
  | Subclause | | Header |
120
- | ---------------------- | ------------------------- | -------------------------------------- |
121
  | | | `<ciso646>` |
122
  | [[support.types]] | Types | `<cstddef>` |
123
  | [[support.limits]] | Implementation properties | `<cfloat>` `<limits>` `<climits>` |
124
  | [[cstdint]] | Integer types | `<cstdint>` |
125
  | [[support.start.term]] | Start and termination | `<cstdlib>` |
126
  | [[support.dynamic]] | Dynamic memory management | `<new>` |
127
  | [[support.rtti]] | Type identification | `<typeinfo>` |
128
  | [[support.exception]] | Exception handling | `<exception>` |
129
  | [[support.initlist]] | Initializer lists | `<initializer_list>` |
130
- | [[support.runtime]] | Other runtime support | `<cstdalign>` `<cstdarg>` `<cstdbool>` |
131
  | [[meta]] | Type traits | `<type_traits>` |
132
  | [[atomics]] | Atomics | `<atomic>` |
 
133
 
134
 
135
  The supplied version of the header `<cstdlib>` shall declare at least
136
  the functions `abort`, `atexit`, `at_quick_exit`, `exit`, and
137
  `quick_exit` ([[support.start.term]]). The other headers listed in this
@@ -154,13 +204,13 @@ appropriate `#include` preprocessing directive ([[cpp.include]]).
154
 
155
  A translation unit may include library headers in any order (Clause 
156
  [[lex]]). Each may be included more than once, with no effect different
157
  from being included exactly once, except that the effect of including
158
  either `<cassert>` or `<assert.h>` depends each time on the lexically
159
- current definition of `NDEBUG`.[^20]
160
 
161
- A translation unit shall include a header only outside of any external
162
  declaration or definition, and shall include the header lexically before
163
  the first reference in that translation unit to any of the entities
164
  declared in that header. No diagnostic is required.
165
 
166
  #### Linkage <a id="using.linkage">[[using.linkage]]</a>
@@ -170,17 +220,17 @@ Entities in the C++standard library have external linkage (
170
  the default `extern "C++"` linkage ([[dcl.link]]).
171
 
172
  Whether a name from the C standard library declared with external
173
  linkage has `extern "C"` or `extern "C++"` linkage is
174
  *implementation-defined*. It is recommended that an implementation use
175
- `extern "C++"` linkage for this purpose.[^21]
176
 
177
  Objects and functions defined in the library and required by a
178
  C++program are included in the program prior to program startup.
179
 
180
- replacement functions ([[replacement.functions]]), run-time changes (
181
- [[handler.functions]]).
182
 
183
  ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
184
 
185
  [[utility.arg.requirements]] describes requirements on types and
186
  expressions used to instantiate templates defined in the C++standard
@@ -193,77 +243,71 @@ describes the requirements on hash function objects.
193
  allocators.
194
 
195
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
196
 
197
  The template definitions in the C++standard library refer to various
198
- named requirements whose details are set out in tables 
199
- [[equalitycomparable]]– [[destructible]]. In these tables, `T` is an
200
- object or reference type to be supplied by a C++program instantiating a
201
- template; `a`, `b`, and `c` are values of type (possibly `const`) `T`;
202
- `s` and `t` are modifiable lvalues of type `T`; `u` denotes an
203
- identifier; `rv` is an rvalue of type `T`; and `v` is an lvalue of type
204
- (possibly `const`) `T` or an rvalue of type `const T`.
205
 
206
  In general, a default constructor is not required. Certain container
207
  class member function signatures specify `T()` as a default argument.
208
  `T()` shall be a well-defined expression ([[dcl.init]]) if one of those
209
  signatures is called using the default argument ([[dcl.fct.default]]).
210
 
211
  **Table: `EqualityComparable` requirements** <a id="equalitycomparable">[equalitycomparable]</a>
212
 
213
- | | | |
214
- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
215
  | `a == b` | convertible to `bool` | `==` is an equivalence relation, that is, it has the following properties: For all `a`, `a == a`.; If `a == b`, then `b == a`.; If `a == b` and `b == c`, then `a == c`. |
216
 
217
  **Table: `LessThanComparable` requirements** <a id="lessthancomparable">[lessthancomparable]</a>
218
 
219
- | | | |
220
- | ------- | --------------------- | --------------------------------------------------------- |
221
  | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation~([[alg.sorting]]) |
222
 
223
  **Table: `DefaultConstructible` requirements** <a id="defaultconstructible">[defaultconstructible]</a>
224
 
225
- | | |
226
- | -------- | --------------------------------------------------- |
227
  | `T t;` | object `t` is default-initialized |
228
- | `T u{};` | object `u` is value-initialized |
229
- | `T()` | a temporary object of type `T` is value-initialized |
230
- | `T{}` | |
231
 
232
- **Table: `MoveConstructible` requirements** <a id="moveconstructible">[moveconstructible]</a>
233
-
234
- | | |
235
- | ----------- | ------------------------------------------------------------------ |
236
- | `T u = rv;` | `u` is equivalent to the value of `rv` before the construction |
237
- | `T(rv)` | `T(rv)` is equivalent to the value of `rv` before the construction |
238
- | *[spans 2 columns]* `rv`'s state is unspecified \enternote `rv` must still meet the requirements of the library component that is using it. The operations listed in those requirements must work as specified whether `rv` has been moved from or not. \exitnote |
239
 
240
  **Table: `CopyConstructible` requirements (in addition to `MoveConstructible`)** <a id="copyconstructible">[copyconstructible]</a>
241
 
242
- | | |
243
  | ---------- | --------------------------------------------------------- |
244
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
245
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
246
 
247
- **Table: `MoveAssignable` requirements** <a id="moveassignable">[moveassignable]</a>
248
-
249
- | | | | |
250
- | -------- | ---- | --- | ------------------------------------------------------------ |
251
- | `t = rv` | `T&` | `t` | `t` is equivalent to the value of `rv` before the assignment |
252
- | *[spans 4 columns]* `rv`'s state is unspecified. \enternote\ `rv` must still meet the requirements of the library component that is using it. The operations listed in those requirements must work as specified whether `rv` has been moved from or not. \exitnote |
253
 
254
  **Table: `CopyAssignable` requirements (in addition to `MoveAssignable`)** <a id="copyassignable">[copyassignable]</a>
255
 
256
- | | | | |
257
- | ------- | ---- | --- | ------------------------------------------------------- |
258
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
259
 
260
 
261
  **Table: `Destructible` requirements** <a id="destructible">[destructible]</a>
262
 
263
- | | |
264
- | -------- | --------------------------------------------------------------------- |
265
  | `u.~T()` | All resources owned by `u` are reclaimed, no exception is propagated. |
266
 
267
 
268
  #### `Swappable` requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
269
 
@@ -287,28 +331,30 @@ overload resolution ([[over.match]]) on a candidate set that includes:
287
  - the two `swap` function templates defined in `<utility>` (
288
  [[utility]]) and
289
  - the lookup set produced by argument-dependent lookup (
290
  [[basic.lookup.argdep]]).
291
 
292
- If `T` and `U` are both fundamental types or arrays of fundamental types
293
- and the declarations from the header `<utility>` are in scope, the
294
- overall lookup set described above is equivalent to that of the
295
- qualified name lookup applied to the expression `std::swap(t, u)` or
296
- `std::swap(u, t)` as appropriate.
297
 
298
- It is unspecified whether a library component that has a swappable
299
- requirement includes the header `<utility>` to ensure an appropriate
300
- evaluation context.
301
 
302
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
303
  with any rvalue or lvalue, respectively, of type `T`.
304
 
305
  A type `X` satisfying any of the iterator requirements (
306
  [[iterator.requirements]]) satisfies the requirements of
307
  `ValueSwappable` if, for any dereferenceable object `x` of type `X`,
308
  `*x` is swappable.
309
 
 
 
310
  User code can ensure that the evaluation of `swap` calls is performed in
311
  an appropriate context under the various conditions as follows:
312
 
313
  ``` cpp
314
  #include <utility>
@@ -321,11 +367,11 @@ void value_swap(T&& t, U&& u) {
321
  // for rvalues and lvalues
322
  }
323
 
324
  // Requires: lvalues of T shall be swappable.
325
  template <class T>
326
- void lv_swap(T& t1 T& t2) {
327
  using std::swap;
328
  swap(t1, t2); // OK: uses swappable conditions for
329
  } // lvalues of type T
330
 
331
  namespace N {
@@ -349,48 +395,52 @@ int main() {
349
  value_swap(a1, proxy(a2));
350
  assert(a1.m == -5 && a2.m == 5);
351
  }
352
  ```
353
 
 
 
354
  #### `NullablePointer` requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
355
 
356
  A `NullablePointer` type is a pointer-like type that supports null
357
  values. A type `P` meets the requirements of `NullablePointer` if:
358
 
359
  - `P` satisfies the requirements of `EqualityComparable`,
360
  `DefaultConstructible`, `CopyConstructible`, `CopyAssignable`, and
361
  `Destructible`,
362
  - lvalues of type `P` are swappable ([[swappable.requirements]]),
363
- - the expressions shown in Table  [[nullablepointer]] are valid and have
364
- the indicated semantics, and
365
  - `P` satisfies all the other requirements of this subclause.
366
 
367
  A value-initialized object of type `P` produces the null value of the
368
  type. The null value shall be equivalent only to itself. A
369
  default-initialized object of type `P` may have an indeterminate value.
370
- Operations involving indeterminate values may cause undefined behavior.
 
 
371
 
372
  An object `p` of type `P` can be contextually converted to `bool`
373
  (Clause  [[conv]]). The effect shall be as if `p != nullptr` had been
374
  evaluated in place of `p`.
375
 
376
  No operation which is part of the `NullablePointer` requirements shall
377
  exit via an exception.
378
 
379
- In Table  [[nullablepointer]], `u` denotes an identifier, `t` denotes a
380
- non-`const` lvalue of type `P`, `a` and `b` denote values of type
381
- (possibly `const`) `P`, and `np` denotes a value of type (possibly
382
  `const`) `std::nullptr_t`.
383
 
384
  **Table: `NullablePointer` requirements** <a id="nullablepointer">[nullablepointer]</a>
385
 
386
  | | | |
387
- | -------------- | ---------------------------------- | ------------------------ |
388
- | `P u(np);`<br> | | post: `u == nullptr` |
389
  | `P u = np;` | | |
390
- | `P(np)` | | post: `P(np) == nullptr` |
391
- | `t = np` | `P&` | post: `t == nullptr` |
392
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
393
  | `a == np` | contextually convertible to `bool` | `a == P()` |
394
  | `np == a` | | |
395
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
396
  | `np != a` | | |
@@ -401,25 +451,21 @@ non-`const` lvalue of type `P`, `a` and `b` denote values of type
401
  A type `H` meets the `Hash` requirements if:
402
 
403
  - it is a function object type ([[function.objects]]),
404
  - it satisfies the requirements of `CopyConstructible` and
405
  `Destructible` ([[utility.arg.requirements]]), and
406
- - the expressions shown in Table  [[hash]] are valid and have the
407
  indicated semantics.
408
 
409
  Given `Key` is an argument type for function objects of type `H`, in
410
- Table  [[hash]] `h` is a value of type (possibly `const`) `H`, `u` is an
411
- lvalue of type `Key`, and `k` is a value of a type convertible to
412
  (possibly `const`) `Key`.
413
 
414
- **Table: `Hash` requirements** <a id="hash">[hash]</a>
415
-
416
- | | | |
417
- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
418
- | `h(k)` | `size_t` | The value returned shall depend only on the argument `k` for the duration of the program. \enternote Thus all evaluations of the expression `h(k)` with the same value for `k` yield the same result for a given execution of the program. \exitnote \enternote For two different values `t1` and `t2`, the probability that `h(t1)` and `h(t2)` compare equal should be very small, approaching `1.0 / numeric_limits<size_t>::max()`. \exitnote |
419
- | `h(u)` | `size_t` | Shall not modify `u`. |
420
-
421
 
422
  #### Allocator requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
423
 
424
  The library describes a standard set of requirements for *allocators*,
425
  which are class-type objects that encapsulate the information about an
@@ -429,12 +475,12 @@ this allocation model, as well as the memory allocation and deallocation
429
  primitives for it. All of the string types (Clause  [[strings]]),
430
  containers (Clause  [[containers]]) (except array), string buffers and
431
  string streams (Clause  [[input.output]]), and `match_results` (Clause 
432
  [[re]]) are parameterized in terms of allocators.
433
 
434
- The template struct `allocator_traits` ([[allocator.traits]]) supplies
435
- a uniform interface to all allocator types. Table  [[tab:desc.var.def]]
436
  describes the types manipulated through allocators. Table 
437
  [[tab:utilities.allocator.requirements]] describes the requirements on
438
  allocator types and thus on types used to instantiate
439
  `allocator_traits`. A requirement is optional if the last column of
440
  Table  [[tab:utilities.allocator.requirements]] specifies a default for
@@ -445,31 +491,47 @@ of `allocator_traits` may provide different defaults and may provide
445
  defaults for different requirements than the primary template. Within
446
  Tables  [[tab:desc.var.def]] and 
447
  [[tab:utilities.allocator.requirements]], the use of `move` and
448
  `forward` always refers to `std::move` and `std::forward`, respectively.
449
 
 
 
450
  Note A: The member class template `rebind` in the table above is
451
- effectively a typedef template. In general, if the name `Allocator` is
452
- bound to `SomeAllocator<T>`, then `Allocator::rebind<U>::other` is the
453
- same type as `SomeAllocator<U>`, where `SomeAllocator<T>::value_type` is
454
- `T` and `SomeAllocator<U>::{}value_type` is `U`. If `Allocator` is a
455
- class template instantiation of the form `SomeAllocator<T, Args>`, where
456
- `Args` is zero or more type arguments, and `Allocator` does not supply a
457
- `rebind` member template, the standard `allocator_traits` template uses
458
- `SomeAllocator<U, Args>` in place of `Allocator::{}rebind<U>::other` by
459
- default. For allocator types that are not template instantiations of the
460
- above form, no default is provided.
 
 
 
 
 
 
 
 
 
 
 
 
 
461
 
462
  An allocator type `X` shall satisfy the requirements of
463
  `CopyConstructible` ([[utility.arg.requirements]]). The `X::pointer`,
464
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
465
  shall satisfy the requirements of `NullablePointer` (
466
- [[nullablepointer.requirements]]). No constructor, comparison operator,
467
- copy operation, move operation, or swap operation on these types shall
468
- exit via an exception. `X::pointer` and `X::const_pointer` shall also
469
- satisfy the requirements for a random access iterator (
470
- [[iterator.requirements]]).
 
471
 
472
  Let `x1` and `x2` denote objects of (possibly different) types
473
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
474
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
475
  pointer values, if and only if both `x1` and `x2` can be explicitly
@@ -503,15 +565,18 @@ p1 - p2
503
 
504
  either or both objects may be replaced by an equivalently-valued object
505
  of type `X::const_pointer` with no change in semantics.
506
 
507
  An allocator may constrain the types on which it can be instantiated and
508
- the arguments for which its `construct` member may be called. If a type
509
- cannot be used with a particular allocator, the allocator class or the
510
- call to `construct` may fail to instantiate.
 
511
 
512
- the following is an allocator class template supporting the minimal
 
 
513
  interface that satisfies the requirements of Table 
514
  [[tab:utilities.allocator.requirements]]:
515
 
516
  ``` cpp
517
  template <class Tp>
@@ -529,15 +594,29 @@ template <class T, class U>
529
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
530
  template <class T, class U>
531
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
532
  ```
533
 
 
 
534
  If the alignment associated with a specific over-aligned type is not
535
  supported by an allocator, instantiation of the allocator for that type
536
  may fail. The allocator also may silently ignore the requested
537
- alignment. Additionally, the member function `allocate` for that type
538
- may fail by throwing an object of type `std::bad_alloc`.
 
 
 
 
 
 
 
 
 
 
 
 
539
 
540
  ### Constraints on programs <a id="constraints">[[constraints]]</a>
541
 
542
  #### Overview <a id="constraints.overview">[[constraints.overview]]</a>
543
 
@@ -558,20 +637,21 @@ The behavior of a C++program is undefined if it adds declarations or
558
  definitions to namespace `std` or to a namespace within namespace `std`
559
  unless otherwise specified. A program may add a template specialization
560
  for any standard library template to namespace `std` only if the
561
  declaration depends on a user-defined type and the specialization meets
562
  the standard library requirements for the original template and is not
563
- explicitly prohibited.[^22]
564
 
565
  The behavior of a C++program is undefined if it declares
566
 
567
  - an explicit specialization of any member function of a standard
568
  library class template, or
569
  - an explicit specialization of any member function template of a
570
  standard library class or class template, or
571
  - an explicit or partial specialization of any member class template of
572
- a standard library class or class template.
 
573
 
574
  A program may explicitly instantiate a template defined in the standard
575
  library only if the declaration depends on the name of a user-defined
576
  type and the instantiation meets the standard library requirements for
577
  the original template.
@@ -584,10 +664,20 @@ namespace ([[namespace.def]]).
584
  The behavior of a C++program is undefined if it adds declarations or
585
  definitions to namespace `posix` or to a namespace within namespace
586
  `posix` unless otherwise specified. The namespace `posix` is reserved
587
  for use by ISO/IEC 9945 and other POSIX standards.
588
 
 
 
 
 
 
 
 
 
 
 
589
  #### Reserved names <a id="reserved.names">[[reserved.names]]</a>
590
 
591
  The C++standard library reserves the following kinds of names:
592
 
593
  - macros
@@ -596,61 +686,81 @@ The C++standard library reserves the following kinds of names:
596
 
597
  If a program declares or defines a name in a context where it is
598
  reserved, other than as explicitly allowed by this Clause, its behavior
599
  is undefined.
600
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
601
  ##### Macro names <a id="macro.names">[[macro.names]]</a>
602
 
603
  A translation unit that includes a standard library header shall not
604
  `#define` or `#undef` names declared in any standard library header.
605
 
606
  A translation unit shall not `#define` or `#undef` names lexically
607
  identical to keywords, to the identifiers listed in Table 
608
  [[tab:identifiers.special]], or to the *attribute-token*s described in 
609
  [[dcl.attr]].
610
 
611
- ##### Global names <a id="global.names">[[global.names]]</a>
612
-
613
- Certain sets of names and function signatures are always reserved to the
614
- implementation:
615
-
616
- - Each name that contains a double underscore `__` or begins with an
617
- underscore followed by an uppercase letter ([[lex.key]]) is reserved
618
- to the implementation for any use.
619
- - Each name that begins with an underscore is reserved to the
620
- implementation for use as a name in the global namespace.
621
-
622
  ##### External linkage <a id="extern.names">[[extern.names]]</a>
623
 
624
  Each name declared as an object with external linkage in a header is
625
  reserved to the implementation to designate that library object with
626
- external linkage, [^23] both in namespace `std` and in the global
627
  namespace.
628
 
629
  Each global function signature declared with external linkage in a
630
  header is reserved to the implementation to designate that function
631
- signature with external linkage. [^24]
632
 
633
- Each name from the Standard C library declared with external linkage is
634
  reserved to the implementation for use as a name with `extern "C"`
635
- linkage, both in namespace std and in the global namespace.
636
 
637
- Each function signature from the Standard C library declared with
638
  external linkage is reserved to the implementation for use as a function
639
- signature with both `extern "C"` and `extern "C++"` linkage, [^25] or as
640
  a name of namespace scope in the global namespace.
641
 
642
  ##### Types <a id="extern.types">[[extern.types]]</a>
643
 
644
- For each type T from the Standard C library,[^26] the types `::T` and
645
  `std::T` are reserved to the implementation and, when defined, `::T`
646
  shall be identical to `std::T`.
647
 
648
  ##### User-defined literal suffixes <a id="usrlit.suffix">[[usrlit.suffix]]</a>
649
 
650
- Literal suffix identifiers that do not start with an underscore are
651
- reserved for future standardization.
652
 
653
  #### Headers <a id="alt.headers">[[alt.headers]]</a>
654
 
655
  If a file with a name equivalent to the derived file name for one of the
656
  C++standard library headers is not provided as part of the
@@ -670,55 +780,73 @@ Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]]
670
  describe the behavior of numerous functions defined by the C++standard
671
  library. Under some circumstances, however, certain of these function
672
  descriptions also apply to replacement functions defined in the
673
  program ([[definitions]]).
674
 
675
- A C++program may provide the definition for any of twelve dynamic memory
676
- allocation function signatures declared in header `<new>` (
677
  [[basic.stc.dynamic]], [[support.dynamic]]):
678
 
679
- - `operator new(std::size_t)`
680
- - `operator new(std::size_t, const std::nothrow_t&)`
681
- - `operator new[](std::size_t)`
682
- - `operator new[](std::size_t, const std::nothrow_t&)`
683
- - `operator delete(void*)`
684
- - `operator delete(void*, const std::nothrow_t&)`
685
- - `operator delete[](void*)`
686
- - `operator delete[](void*, const std::nothrow_t&)`
687
- - `operator delete(void*, std::size_t)`
688
- - `operator delete(void*, std::size_t, const std::nothrow_t&)`
689
- - `operator delete[](void*, std::size_t)`
690
- - `operator delete[](void*, std::size_t, const std::nothrow_t&)`
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
691
 
692
  The program’s definitions are used instead of the default versions
693
  supplied by the implementation ([[support.dynamic]]). Such replacement
694
  occurs prior to program startup ([[basic.def.odr]], [[basic.start]]).
695
- The program’s definitions shall not be specified as `inline`. No
696
  diagnostic is required.
697
 
698
  #### Handler functions <a id="handler.functions">[[handler.functions]]</a>
699
 
700
- The C++standard library provides default versions of the following
701
- handler functions (Clause  [[language.support]]):
702
 
703
- - `unexpected_handler`
704
  - `terminate_handler`
705
 
706
  A C++program may install different handler functions during execution,
707
  by supplying a pointer to a function defined in the program or the
708
  library as an argument to (respectively):
709
 
710
  - `set_new_handler`
711
- - `set_unexpected`
712
- - `set_terminate` subclauses  [[alloc.errors]], Storage allocation
713
- errors, and  [[support.exception]], Exception handling.
 
714
 
715
  A C++program can get a pointer to the current handler function by
716
  calling the following functions:
717
 
718
  - `get_new_handler`
719
- - `get_unexpected`
720
  - `get_terminate`
721
 
722
  Calling the `set_*` and `get_*` functions shall not incur a data race. A
723
  call to any of the `set_*` functions shall synchronize with subsequent
724
  calls to the same `set_*` function and to the corresponding `get_*`
@@ -727,26 +855,26 @@ function.
727
  #### Other functions <a id="res.on.functions">[[res.on.functions]]</a>
728
 
729
  In certain cases (replacement functions, handler functions, operations
730
  on types used to instantiate standard library template components), the
731
  C++standard library depends on components supplied by a C++program. If
732
- these components do not meet their requirements, the Standard places no
733
- requirements on the implementation.
734
 
735
  In particular, the effects are undefined in the following cases:
736
 
737
  - for replacement functions ([[new.delete]]), if the installed
738
  replacement function does not implement the semantics of the
739
  applicable *Required behavior:* paragraph.
740
- - for handler functions ([[new.handler]], [[terminate.handler]],
741
- [[unexpected.handler]]), if the installed handler function does not
742
- implement the semantics of the applicable *Required behavior:*
743
- paragraph
744
  - for types used as template arguments when instantiating a template
745
  component, if the operations on the type do not implement the
746
- semantics of the applicable subclause ([[allocator.requirements]],
747
- [[container.requirements]], [[iterator.requirements]],
 
748
  [[numeric.requirements]]). Operations on such types can report a
749
  failure by throwing an exception unless otherwise specified.
750
  - if any replacement function or handler function or destructor
751
  operation exits via an exception, unless specifically allowed in the
752
  applicable *Required behavior:* paragraph.
@@ -767,37 +895,40 @@ the C++standard library, unless explicitly stated otherwise.
767
  address computations and accesses to objects (that would be valid if
768
  the pointer did point to the first element of such an array) are in
769
  fact valid.
770
  - If a function argument binds to an rvalue reference parameter, the
771
  implementation may assume that this parameter is a unique reference to
772
- this argument. If the parameter is a generic parameter of the form
773
- `T&&` and an lvalue of type `A` is bound, the argument binds to an
774
- lvalue reference ([[temp.deduct.call]]) and thus is not covered by
775
- the previous sentence. If a program casts an lvalue to an xvalue while
776
- passing that lvalue to a library function (e.g. by calling the
777
- function with the argument `move(x)`), the program is effectively
778
- asking that function to treat that lvalue as a temporary. The
779
- implementation is free to optimize away aliasing checks which might be
780
- needed if the argument was an lvalue.
 
781
 
782
- #### Shared objects and the library <a id="res.on.objects">[[res.on.objects]]</a>
783
 
784
  The behavior of a program is undefined if calls to standard library
785
  functions from different threads may introduce a data race. The
786
  conditions under which this may occur are specified in 
787
- [[res.on.data.races]]. Modifying an object of a standard library type
788
- that is shared between threads risks undefined behavior unless objects
789
- of that type are explicitly specified as being sharable without data
790
- races or the user supplies a locking mechanism.
791
 
792
- In particular, the program is required to ensure that completion of the
793
- constructor of any object of a class type defined in the standard
794
- library happens before any other member function invocation on that
795
- object and, unless otherwise specified, to ensure that completion of any
796
- member function invocation other than destruction on such an object
797
- happens before destruction of that object. This applies even to objects
798
- such as mutexes intended for thread synchronization.
 
 
 
 
 
799
 
800
  #### Requires paragraph <a id="res.on.required">[[res.on.required]]</a>
801
 
802
  Violation of the preconditions specified in a function’s *Requires:*
803
  paragraph results in undefined behavior unless the function’s *Throws:*
@@ -810,13 +941,13 @@ violated.
810
 
811
  This section describes the constraints upon, and latitude of,
812
  implementations of the C++standard library.
813
 
814
  An implementation’s use of headers is discussed in  [[res.on.headers]],
815
- its use of macros in  [[res.on.macro.definitions]], global functions in 
816
- [[global.functions]], member functions in  [[member.functions]], data
817
- race avoidance in  [[res.on.data.races]], access specifiers in 
818
  [[protection.within.classes]], class derivation in  [[derivation]], and
819
  exceptions in  [[res.on.exception.handling]].
820
 
821
  #### Headers <a id="res.on.headers">[[res.on.headers]]</a>
822
 
@@ -829,12 +960,13 @@ headers.
829
  Certain types and macros are defined in more than one header. Every such
830
  entity shall be defined such that any header that defines it may be
831
  included after any other header that also defines it (
832
  [[basic.def.odr]]).
833
 
834
- The C standard headers ([[depr.c.headers]]) shall include only their
835
- corresponding C++standard header, as described in  [[headers]].
 
836
 
837
  #### Restrictions on macro definitions <a id="res.on.macro.definitions">[[res.on.macro.definitions]]</a>
838
 
839
  The names and global function signatures described in  [[contents]] are
840
  reserved to the implementation.
@@ -842,66 +974,71 @@ reserved to the implementation.
842
  All object-like macros defined by the C standard library and described
843
  in this Clause as expanding to integral constant expressions are also
844
  suitable for use in `#if` preprocessing directives, unless explicitly
845
  stated otherwise.
846
 
847
- #### Global and non-member functions <a id="global.functions">[[global.functions]]</a>
848
 
849
- It is unspecified whether any global or non-member functions in the
850
- C++standard library are defined as `inline` ([[dcl.fct.spec]]).
851
 
852
- A call to a global or non-member function signature described in
853
- Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]]
854
- shall behave as if the implementation declared no additional global or
855
- non-member function signatures.[^27]
856
 
857
- An implementation shall not declare a global or non-member function
858
- signature with additional default arguments.
859
 
860
- Unless otherwise specified, global and non-member functions in the
861
- standard library shall not use functions from another namespace which
862
- are found through *argument-dependent name lookup* (
863
- [[basic.lookup.argdep]]). The phrase “unless otherwise specified” is
864
- intended to allow argument-dependent lookup in cases like that of
865
- `ostream_iterator::operator=` ([[ostream.iterator.ops]]):
 
 
 
 
 
866
 
867
  *Effects:*
868
 
869
  ``` cpp
870
  *out_stream << value;
871
  if (delim != 0)
872
  *out_stream << delim;
873
  return *this;
874
  ```
875
 
 
 
876
  #### Member functions <a id="member.functions">[[member.functions]]</a>
877
 
878
  It is unspecified whether any member functions in the C++standard
879
- library are defined as `inline` ([[dcl.fct.spec]]).
880
 
881
- An implementation may declare additional non-virtual member function
882
- signatures within a class:
 
 
 
883
 
884
- - by adding arguments with default values to a member function
885
- signature; [^28] An implementation may not add arguments with default
886
- values to virtual, global, or non-member functions.
887
- - by replacing a member function signature with default values by two or
888
- more member function signatures with equivalent behavior; and
889
- - by adding a member function signature for a member function name.
890
 
891
- A call to a member function signature described in the C++standard
892
- library behaves as if the implementation declares no additional member
893
- function signatures.[^29]
894
 
895
- #### `constexpr` functions and constructors <a id="constexpr.functions">[[constexpr.functions]]</a>
896
-
897
- This standard explicitly requires that certain standard library
898
- functions are `constexpr` ([[dcl.constexpr]]). An implementation shall
899
- not declare any standard library function signature as `constexpr`
900
- except for those where it is explicitly required. Within any header that
901
- provides any non-defining declarations of `constexpr` functions or
902
- constructors an implementation shall provide corresponding definitions.
903
 
904
  #### Requirements for stable algorithms <a id="algorithm.stable">[[algorithm.stable]]</a>
905
 
906
  When the requirements for an algorithm state that it is “stable” without
907
  further elaboration, it means:
@@ -915,12 +1052,12 @@ further elaboration, it means:
915
  original order) precede the elements from the second range (preserving
916
  their original order).
917
 
918
  #### Reentrancy <a id="reentrancy">[[reentrancy]]</a>
919
 
920
- Except where explicitly specified in this standard, it is
921
- *implementation-defined* which functions in the Standard C++ library may
922
  be recursively reentered.
923
 
924
  #### Data race avoidance <a id="res.on.data.races">[[res.on.data.races]]</a>
925
 
926
  This section specifies requirements that implementations shall meet to
@@ -937,36 +1074,38 @@ via the function’s arguments, including `this`.
937
  A C++standard library function shall not directly or indirectly modify
938
  objects ([[intro.multithread]]) accessible by threads other than the
939
  current thread unless the objects are accessed directly or indirectly
940
  via the function’s non-const arguments, including `this`.
941
 
942
- This means, for example, that implementations can’t use a static object
943
- for internal purposes without synchronization because it could cause a
944
- data race even in programs that do not explicitly share objects between
945
- threads.
946
 
947
  A C++standard library function shall not access objects indirectly
948
  accessible via its arguments or via elements of its container arguments
949
  except by invoking functions required by its specification on those
950
  container elements.
951
 
952
  Operations on iterators obtained by calling a standard library container
953
  or string member function may access the underlying container, but shall
954
- not modify it. In particular, container operations that invalidate
 
 
955
  iterators conflict with operations on iterators associated with that
956
- container.
957
 
958
  Implementations may share their own internal objects between threads if
959
  the objects are not visible to users and are protected against data
960
  races.
961
 
962
  Unless otherwise specified, C++standard library functions shall perform
963
  all operations solely within the current thread if those operations have
964
  effects that are visible ([[intro.multithread]]) to users.
965
 
966
- This allows implementations to parallelize operations if there are no
967
- visible side effects.
968
 
969
  #### Protection within classes <a id="protection.within.classes">[[protection.within.classes]]</a>
970
 
971
  It is unspecified whether any function signature or class described in
972
  Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]] is
@@ -984,64 +1123,74 @@ through a hierarchy of base classes with names reserved to the
984
  implementation.
985
 
986
  In any case:
987
 
988
  - Every base class described as `virtual` shall be virtual;
989
- - Every base class described as non-`virtual` shall not be virtual;
990
  - Unless explicitly stated otherwise, types with distinct names shall be
991
- distinct types.[^30]
 
 
 
992
 
993
  #### Restrictions on exception handling <a id="res.on.exception.handling">[[res.on.exception.handling]]</a>
994
 
995
  Any of the functions defined in the C++standard library can report a
996
- failure by throwing an exception of a type described in its paragraph.
997
- An implementation may strengthen the *exception-specification* for a
998
- non-virtual function by adding a non-throwing *noexcept-specification*.
 
999
 
1000
- A function may throw an object of a type not listed in its clause if its
1001
- type is derived from a type named in the clause and would be caught by
1002
- an exception handler for the base type.
1003
-
1004
- Functions from the C standard library shall not throw exceptions [^31]
1005
  except when such a function calls a program-supplied function that
1006
- throws an exception.[^32]
1007
 
1008
  Destructor operations defined in the C++standard library shall not throw
1009
  exceptions. Every destructor in the C++standard library shall behave as
1010
- if it had a non-throwing exception specification. Any other functions
1011
- defined in the C++standard library that do not have an
1012
- *exception-specification* may throw *implementation-defined* exceptions
1013
- unless otherwise specified.[^33] An implementation may strengthen this
1014
- implicit *exception-specification* by adding an explicit one.[^34]
 
 
 
 
 
 
1015
 
1016
  #### Restrictions on storage of pointers <a id="res.on.pointer.storage">[[res.on.pointer.storage]]</a>
1017
 
1018
  Objects constructed by the standard library that may hold a
1019
  user-supplied pointer value or an integer of type `std::intptr_t` shall
1020
  store such values in a traceable pointer location (
1021
- [[basic.stc.dynamic.safety]]). Other libraries are strongly encouraged
1022
- to do the same, since not doing so may result in accidental use of
1023
- pointers that are not safely derived. Libraries that store pointers
1024
- outside the user’s address space should make it appear that they are
1025
- stored and retrieved from a traceable pointer location.
 
 
1026
 
1027
  #### Value of error codes <a id="value.error.codes">[[value.error.codes]]</a>
1028
 
1029
  Certain functions in the C++standard library report errors via a
1030
  `std::error_code` ([[syserr.errcode.overview]]) object. That object’s
1031
  `category()` member shall return `std::system_category()` for errors
1032
  originating from the operating system, or a reference to an
1033
  *implementation-defined* `error_category` object for errors originating
1034
  elsewhere. The implementation shall define the possible values of
1035
- `value()` for each of these error categories. For operating systems that
1036
- are based on POSIX, implementations are encouraged to define the
1037
- `std::system_category()` values as identical to the POSIX `errno`
1038
- values, with additional values as defined by the operating system’s
1039
- documentation. Implementations for operating systems that are not based
1040
- on POSIX are encouraged to define values identical to the operating
1041
- system’s values. For errors that do not originate from the operating
1042
- system, the implementation may provide enums for the associated values.
 
 
1043
 
1044
  #### Moved-from state of library types <a id="lib.types.movedfrom">[[lib.types.movedfrom]]</a>
1045
 
1046
  Objects of types defined in the C++standard library may be moved from (
1047
  [[class.copy]]). Move operations may be explicitly specified or
@@ -1051,18 +1200,21 @@ objects shall be placed in a valid but unspecified state.
1051
  <!-- Link reference definitions -->
1052
  [alg.c.library]: algorithms.md#alg.c.library
1053
  [alg.sorting]: algorithms.md#alg.sorting
1054
  [algorithm.stable]: #algorithm.stable
1055
  [algorithms]: algorithms.md#algorithms
 
1056
  [alloc.errors]: language.md#alloc.errors
1057
  [allocator.requirements]: #allocator.requirements
 
1058
  [allocator.traits]: utilities.md#allocator.traits
1059
  [alt.headers]: #alt.headers
1060
  [atomics]: atomics.md#atomics
1061
  [bad.alloc]: language.md#bad.alloc
1062
  [basic.def.odr]: basic.md#basic.def.odr
1063
  [basic.fundamental]: basic.md#basic.fundamental
 
1064
  [basic.link]: basic.md#basic.link
1065
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
1066
  [basic.scope.namespace]: basic.md#basic.scope.namespace
1067
  [basic.start]: basic.md#basic.start
1068
  [basic.stc.dynamic]: basic.md#basic.stc.dynamic
@@ -1071,10 +1223,11 @@ objects shall be placed in a valid but unspecified state.
1071
  [bitmask.types]: #bitmask.types
1072
  [byte.strings]: #byte.strings
1073
  [c.locales]: localization.md#c.locales
1074
  [c.strings]: strings.md#c.strings
1075
  [character.seq]: #character.seq
 
1076
  [class.copy]: special.md#class.copy
1077
  [class.ctor]: special.md#class.ctor
1078
  [class.dtor]: special.md#class.dtor
1079
  [class.mem]: class.md#class.mem
1080
  [class.mfct]: class.md#class.mfct
@@ -1095,49 +1248,50 @@ objects shall be placed in a valid but unspecified state.
1095
  [cstdint]: language.md#cstdint
1096
  [dcl.array]: dcl.md#dcl.array
1097
  [dcl.attr]: dcl.md#dcl.attr
1098
  [dcl.constexpr]: dcl.md#dcl.constexpr
1099
  [dcl.fct.default]: dcl.md#dcl.fct.default
1100
- [dcl.fct.spec]: dcl.md#dcl.fct.spec
1101
  [dcl.init]: dcl.md#dcl.init
 
 
1102
  [dcl.link]: dcl.md#dcl.link
1103
  [definitions]: #definitions
1104
- [defns.additional]: #defns.additional
1105
  [depr]: future.md#depr
1106
  [depr.c.headers]: future.md#depr.c.headers
 
 
1107
  [derivation]: #derivation
1108
  [derived.classes]: #derived.classes
1109
  [description]: #description
1110
- [destructible]: #destructible
1111
  [diagnostics]: diagnostics.md#diagnostics
1112
  [enumerated.types]: #enumerated.types
1113
- [equalitycomparable]: #equalitycomparable
1114
  [except]: except.md#except
 
 
 
1115
  [expr.delete]: expr.md#expr.delete
1116
  [expr.eq]: expr.md#expr.eq
1117
  [expr.new]: expr.md#expr.new
1118
  [expr.rel]: expr.md#expr.rel
1119
  [extern.names]: #extern.names
1120
  [extern.types]: #extern.types
1121
  [function.objects]: utilities.md#function.objects
1122
  [functions.within.classes]: #functions.within.classes
1123
  [global.functions]: #global.functions
1124
- [global.names]: #global.names
1125
  [handler.functions]: #handler.functions
1126
- [hash]: #hash
1127
  [hash.requirements]: #hash.requirements
1128
  [headers]: #headers
1129
  [input.output]: input.md#input.output
1130
  [intro.compliance]: intro.md#intro.compliance
1131
  [intro.defs]: intro.md#intro.defs
1132
  [intro.multithread]: intro.md#intro.multithread
1133
  [intro.refs]: intro.md#intro.refs
1134
  [iterator.requirements]: iterators.md#iterator.requirements
 
1135
  [iterators]: iterators.md#iterators
1136
  [language.support]: language.md#language.support
1137
  [lex]: lex.md#lex
1138
- [lex.key]: lex.md#lex.key
1139
  [lex.phases]: lex.md#lex.phases
1140
  [lib.types.movedfrom]: #lib.types.movedfrom
1141
  [library]: #library
1142
  [library.c]: #library.c
1143
  [library.general]: #library.general
@@ -1147,25 +1301,27 @@ objects shall be placed in a valid but unspecified state.
1147
  [member.functions]: #member.functions
1148
  [meta]: utilities.md#meta
1149
  [multibyte.strings]: #multibyte.strings
1150
  [namespace.constraints]: #namespace.constraints
1151
  [namespace.def]: dcl.md#namespace.def
 
1152
  [namespace.posix]: #namespace.posix
1153
  [namespace.std]: #namespace.std
1154
  [namespace.udecl]: dcl.md#namespace.udecl
1155
  [new.delete]: language.md#new.delete
1156
  [new.handler]: language.md#new.handler
1157
- [nullablepointer]: #nullablepointer
1158
  [nullablepointer.requirements]: #nullablepointer.requirements
1159
  [numeric.requirements]: numerics.md#numeric.requirements
1160
  [numerics]: numerics.md#numerics
1161
  [objects.within.classes]: #objects.within.classes
1162
  [organization]: #organization
1163
  [ostream.iterator.ops]: iterators.md#ostream.iterator.ops
 
1164
  [over.match]: over.md#over.match
1165
  [over.oper]: over.md#over.oper
1166
  [protection.within.classes]: #protection.within.classes
 
1167
  [re]: re.md#re
1168
  [reentrancy]: #reentrancy
1169
  [replacement.functions]: #replacement.functions
1170
  [requirements]: #requirements
1171
  [res.on.arguments]: #res.on.arguments
@@ -1196,164 +1352,151 @@ objects shall be placed in a valid but unspecified state.
1196
  [support.start.term]: language.md#support.start.term
1197
  [support.types]: language.md#support.types
1198
  [swappable.requirements]: #swappable.requirements
1199
  [syserr]: diagnostics.md#syserr
1200
  [syserr.errcode.overview]: diagnostics.md#syserr.errcode.overview
 
 
1201
  [tab:cpp.c.headers]: #tab:cpp.c.headers
1202
  [tab:cpp.headers.freestanding]: #tab:cpp.headers.freestanding
1203
  [tab:cpp.library.headers]: #tab:cpp.library.headers
1204
  [tab:desc.var.def]: #tab:desc.var.def
 
 
 
1205
  [tab:identifiers.special]: lex.md#tab:identifiers.special
1206
  [tab:library.categories]: #tab:library.categories
 
 
1207
  [tab:utilities.allocator.requirements]: #tab:utilities.allocator.requirements
1208
  [temp.deduct.call]: temp.md#temp.deduct.call
1209
  [template.bitset]: utilities.md#template.bitset
1210
  [terminate.handler]: language.md#terminate.handler
1211
  [thread]: thread.md#thread
1212
  [type.descriptions]: #type.descriptions
1213
  [type.descriptions.general]: #type.descriptions.general
1214
- [unexpected.handler]: future.md#unexpected.handler
1215
  [using]: #using
1216
  [using.headers]: #using.headers
1217
  [using.linkage]: #using.linkage
1218
  [using.overview]: #using.overview
1219
  [usrlit.suffix]: #usrlit.suffix
1220
  [utilities]: utilities.md#utilities
1221
  [utility]: utilities.md#utility
1222
  [utility.arg.requirements]: #utility.arg.requirements
1223
  [utility.requirements]: #utility.requirements
1224
  [value.error.codes]: #value.error.codes
 
1225
 
1226
- [^1]: This definition is taken from POSIX.
1227
-
1228
- [^2]: To save space, items that do not apply to a Clause are omitted.
1229
  For example, if a Clause does not specify any requirements, there
1230
  will be no “Requirements” subclause.
1231
 
1232
- [^3]: Although in some cases the code given is unambiguously the optimum
1233
  implementation.
1234
 
1235
- [^4]: To save space, items that do not apply to a class are omitted. For
1236
  example, if a class does not specify any comparison functions, there
1237
  will be no “Comparison functions” subclause.
1238
 
1239
- [^5]: To save space, items that do not apply to a function are omitted.
1240
  For example, if a function does not specify any further
1241
- preconditions, there will be no Requires paragraph.
1242
 
1243
- [^6]: This simplifies the presentation of complexity requirements in
1244
  some cases.
1245
 
1246
- [^7]: Examples from  [[utility.requirements]] include:
1247
  `EqualityComparable`, `LessThanComparable`, `CopyConstructible`.
1248
  Examples from  [[iterator.requirements]] include: `InputIterator`,
1249
- `ForwardIterator`, `Function`, `Predicate`.
1250
 
1251
- [^8]: Such as an integer type, with constant integer values (
1252
  [[basic.fundamental]]).
1253
 
1254
- [^9]: Note that this definition differs from the definition in ISO C
1255
- 7.1.1.
1256
 
1257
- [^10]: declared in `<clocale>` ([[c.locales]]).
1258
-
1259
- [^11]: Many of the objects manipulated by function signatures declared
1260
- in `<cstring>` ([[c.strings]]) are character sequences or NTBSs.
1261
- The size of some of these character sequences is limited by a length
1262
  value, maintained separately from the character sequence.
1263
 
1264
- [^12]: A string literal, such as `"abc"`, is a static NTBS.
1265
 
1266
- [^13]: An NTBSthat contains characters only from the basic execution
1267
  character set is also an NTMBS. Each multibyte character then
1268
  consists of a single byte.
1269
 
1270
- [^14]: The C standard library headers (Annex  [[depr.c.headers]]) also
1271
  define names within the global namespace, while the C++headers for C
1272
  library facilities ([[headers]]) may also define names within the
1273
  global namespace.
1274
 
1275
- [^15]: This gives implementers freedom to use inline namespaces to
1276
  support multiple configurations of the library.
1277
 
1278
- [^16]: A header is not necessarily a source file, nor are the sequences
1279
  delimited by `<` and `>` in header names necessarily valid source
1280
  file names ([[cpp.include]]).
1281
 
1282
- [^17]: This disallows the practice, allowed in C, of providing a masking
 
 
 
1283
  macro in addition to the function prototype. The only way to achieve
1284
  equivalent inline behavior in C++is to provide a definition as an
1285
  extern inline function.
1286
 
1287
- [^18]: In particular, including the standard header `<iso646.h>` or
1288
  `<ciso646>` has no effect.
1289
 
1290
- [^19]: The `".h"` headers dump all their names into the global
1291
  namespace, whereas the newer forms keep their names in namespace
1292
  `std`. Therefore, the newer forms are the preferred forms for all
1293
  uses except for C++programs which are intended to be strictly
1294
  compatible with C.
1295
 
1296
- [^20]: This is the same as the Standard C library.
1297
 
1298
- [^21]: The only reliable way to declare an object or function signature
1299
- from the Standard C library is by including the header that declares
1300
  it, notwithstanding the latitude granted in 7.1.4 of the C Standard.
1301
 
1302
- [^22]: Any library code that instantiates other library templates must
1303
  be prepared to work adequately with any user-supplied specialization
1304
- that meets the minimum requirements of the Standard.
1305
 
1306
- [^23]: The list of such reserved names includes `errno`, declared or
1307
  defined in `<cerrno>`.
1308
 
1309
- [^24]: The list of such reserved function signatures with external
1310
  linkage includes `setjmp(jmp_buf)`, declared or defined in
1311
  `<csetjmp>`, and `va_end(va_list)`, declared or defined in
1312
  `<cstdarg>`.
1313
 
1314
- [^25]: The function signatures declared in `<cuchar>`, `<cwchar>`, and
1315
  `<cwctype>` are always reserved, notwithstanding the restrictions
1316
  imposed in subclause 4.5.1 of Amendment 1 to the C Standard for
1317
  these headers.
1318
 
1319
- [^26]: These types are `clock_t`, `div_t`, `FILE`, `fpos_t`, `lconv`,
1320
  `ldiv_t`, `mbstate_t`, `ptrdiff_t`, `sig_atomic_t`, `size_t`,
1321
  `time_t`, `tm`, `va_list`, `wctrans_t`, `wctype_t`, and `wint_t`.
1322
 
1323
- [^27]: A valid C++program always calls the expected library global or
1324
- non-member function. An implementation may also define additional
1325
- global or non-member functions that would otherwise not be called by
1326
- a valid C++program.
1327
 
1328
- [^28]: Hence, the address of a member function of a class in the
1329
- C++standard library has an unspecified type.
1330
-
1331
- [^29]: A valid C++program always calls the expected library member
1332
- function, or one with equivalent behavior. An implementation may
1333
- also define additional member functions that would otherwise not be
1334
- called by a valid C++program.
1335
-
1336
- [^30]: There is an implicit exception to this rule for types that are
1337
  described as synonyms for basic integral types, such as `size_t` (
1338
  [[support.types]]) and `streamoff` ([[stream.types]]).
1339
 
1340
- [^31]: That is, the C library functions can all be treated as if they
1341
  are marked `noexcept`. This allows implementations to make
1342
  performance optimizations based on the absence of exceptions at
1343
  runtime.
1344
 
1345
- [^32]: The functions `qsort()` and `bsearch()` ([[alg.c.library]]) meet
1346
  this condition.
1347
 
1348
- [^33]: In particular, they can report a failure to allocate storage by
1349
  throwing an exception of type `bad_alloc`, or a class derived from
1350
- `bad_alloc` ([[bad.alloc]]). Library implementations should report
1351
- errors by throwing exceptions of or derived from the standard
1352
- exception classes ([[bad.alloc]], [[support.exception]],
1353
- [[std.exceptions]]).
1354
-
1355
- [^34]: That is, an implementation may provide an explicit
1356
- *exception-specification* that defines the subset of “any”
1357
- exceptions thrown by that function. This implies that the
1358
- implementation may list implementation-defined types in such an
1359
- *exception-specification*.
 
15
  [[constraints]] describes constraints on well-formed C++programs, and
16
  [[conforming]] describes constraints on conforming implementations.
17
 
18
  ### Library contents and organization <a id="organization">[[organization]]</a>
19
 
20
+ [[contents]] describes the entities and macros defined in the
21
+ C++standard library. [[headers]] lists the standard library headers and
22
+ some constraints on those headers. [[compliance]] lists requirements for
23
+ a freestanding implementation of the C++ standard library.
24
 
25
  #### Library contents <a id="contents">[[contents]]</a>
26
 
27
+ The C++standard library provides definitions for the entities and macros
28
+ described in the synopses of the C++standard library headers (
29
+ [[headers]]).
30
 
31
+ All library entities except `operator new` and `operator delete` are
32
+ defined within the namespace `std` or namespaces nested within namespace
33
+ `std`.[^12] It is unspecified whether names declared in a specific
34
+ namespace are declared directly in that namespace or in an inline
35
+ namespace inside that namespace.[^13]
36
 
37
  Whenever a name `x` defined in the standard library is mentioned, the
38
  name `x` is assumed to be fully qualified as `::std::x`, unless
39
+ explicitly described otherwise. For example, if the *Effects:* section
40
+ for library function `F` is described as calling library function `G`,
41
+ the function `::std::G` is meant.
42
 
43
  #### Headers <a id="headers">[[headers]]</a>
44
 
45
  Each element of the C++standard library is declared or defined (as
46
+ appropriate) in a *header*.[^14]
47
 
48
+ The C++standard library provides the *C++library headers*, shown in
49
  Table  [[tab:cpp.library.headers]].
50
 
51
  **Table: C++library headers** <a id="tab:cpp.library.headers">[tab:cpp.library.headers]</a>
52
 
53
+ | | | | |
54
+ | ---------------------- | -------------------- | -------------------- | ----------------- |
55
+ | `<algorithm>` | `<future>` | `<numeric>` | `<strstream>` |
56
+ | `<any>` | `<initializer_list>` | `<optional>` | `<system_error>` |
57
+ | `<array>` | `<iomanip>` | `<ostream>` | `<thread>` |
58
+ | `<atomic>` | `<ios>` | `<queue>` | `<tuple>` |
59
+ | `<bitset>` | `<iosfwd>` | `<random>` | `<type_traits>` |
60
+ | `<chrono>` | `<iostream>` | `<ratio>` | `<typeindex>` |
61
+ | `<codecvt>` | `<istream>` | `<regex>` | `<typeinfo>` |
62
+ | `<complex>` | `<iterator>` | `<scoped_allocator>` | `<unordered_map>` |
63
+ | `<condition_variable>` | `<limits>` | `<set>` | `<unordered_set>` |
64
+ | `<deque>` | `<list>` | `<shared_mutex>` | `<utility>` |
65
+ | `<exception>` | `<locale>` | `<sstream>` | `<valarray>` |
66
+ | `<execution>` | `<map>` | `<stack>` | `<variant>` |
67
+ | `<filesystem>` | `<memory>` | `<stdexcept>` | `<vector>` |
68
+ | `<forward_list>` | `<memory_resource>` | `<streambuf>` | |
69
+ | `<fstream>` | `<mutex>` | `<string>` | |
70
+ | `<functional>` | `<new>` | `<string_view>` | |
71
 
72
 
73
+ The facilities of the C standard library are provided in the additional
74
+ headers shown in Table  [[tab:cpp.c.headers]]. [^15]
75
 
76
  **Table: C++headers for C library facilities** <a id="tab:cpp.c.headers">[tab:cpp.c.headers]</a>
77
 
78
  | | | | | |
79
  | ------------ | ------------- | ------------- | ----------- | ----------- |
 
83
  | `<cerrno>` | `<clocale>` | `<cstdbool>` | `<ctgmath>` | |
84
  | `<cfenv>` | `<cmath>` | `<cstddef>` | `<ctime>` | |
85
  | `<cfloat>` | `<csetjmp>` | `<cstdint>` | `<cuchar>` | |
86
 
87
 
88
+ Except as noted in Clauses  [[library]] through  [[thread]] and Annex 
89
+ [[depr]], the contents of each header `cname` is the same as that of the
90
+ corresponding header `name.h` as specified in the C standard library
91
+ (Clause  [[intro.refs]]). In the C++standard library, however, the
 
92
  declarations (except for names which are defined as macros in C) are
93
  within namespace scope ([[basic.scope.namespace]]) of the namespace
94
+ `std`. It is unspecified whether these names (including any overloads
95
+ added in Clauses  [[language.support]] through  [[thread]] and Annex 
96
+ [[depr]]) are first declared within the global namespace scope and are
97
+ then injected into namespace `std` by explicit *using-declaration*s (
98
+ [[namespace.udecl]]).
99
 
100
  Names which are defined as macros in C shall be defined as macros in the
101
  C++ standard library, even if C grants license for implementation as
102
+ functions.
103
+
104
+ [*Note 1*: The names defined as macros in C include the following:
105
+ `assert`, `offsetof`, `setjmp`, `va_arg`, `va_end`, and
106
+ `va_start`. — *end note*]
107
 
108
  Names that are defined as functions in C shall be defined as functions
109
+ in the C++standard library.[^16]
110
 
111
  Identifiers that are keywords or operators in C++shall not be defined as
112
+ macros in C++standard library headers.[^17]
113
 
114
  [[depr.c.headers]], C standard library headers, describes the effects of
115
+ using the `name.h` (C header) form in a C++program.[^18]
116
+
117
+ Annex K of the C standard describes a large number of functions, with
118
+ associated types and macros, which “promote safer, more secure
119
+ programming” than many of the traditional C library functions. The names
120
+ of the functions have a suffix of `_s`; most of them provide the same
121
+ service as the C library function with the unsuffixed name, but
122
+ generally take an additional argument whose value is the size of the
123
+ result array. If any C++header is included, it is
124
+ *implementation-defined* whether any of these names is declared in the
125
+ global namespace. (None of them is declared in namespace `std`.)
126
+
127
+ Table  [[tab:c.annex.k.names]] lists the Annex K names that may be
128
+ declared in some header. These names are also subject to the
129
+ restrictions of  [[macro.names]].
130
+
131
+ **Table: C standard Annex K names** <a id="tab:c.annex.k.names">[tab:c.annex.k.names]</a>
132
+
133
+ | | | | |
134
+ | ---------------------- | -------------------------- | -------------- | ------------- |
135
+ | `abort_handler_s` | `mbstowcs_s` | `strncat_s` | `vswscanf_s` |
136
+ | `asctime_s` | `memcpy_s` | `strncpy_s` | `vwprintf_s` |
137
+ | `bsearch_s` | `memmove_s` | `strtok_s` | `vwscanf_s` |
138
+ | `constraint_handler_t` | `memset_s` | `swprintf_s` | `wcrtomb_s` |
139
+ | `ctime_s` | `printf_s` | `swscanf_s` | `wcscat_s` |
140
+ | `errno_t` | `qsort_s` | `tmpfile_s` | `wcscpy_s` |
141
+ | `fopen_s` | `RSIZE_MAX` | `TMP_MAX_S` | `wcsncat_s` |
142
+ | `fprintf_s` | `rsize_t` | `tmpnam_s` | `wcsncpy_s` |
143
+ | `freopen_s` | `scanf_s` | `vfprintf_s` | `wcsnlen_s` |
144
+ | `fscanf_s` | `set_constraint_handler_s` | `vfscanf_s` | `wcsrtombs_s` |
145
+ | `fwprintf_s` | `snprintf_s` | `vfwprintf_s` | `wcstok_s` |
146
+ | `fwscanf_s` | `snwprintf_s` | `vfwscanf_s` | `wcstombs_s` |
147
+ | `getenv_s` | `sprintf_s` | `vprintf_s` | `wctomb_s` |
148
+ | `gets_s` | `sscanf_s` | `vscanf_s` | `wmemcpy_s` |
149
+ | `gmtime_s` | `strcat_s` | `vsnprintf_s` | `wmemmove_s` |
150
+ | `ignore_handler_s` | `strcpy_s` | `vsnwprintf_s` | `wprintf_s` |
151
+ | `L_tmpnam_s` | `strerror_s` | `vsprintf_s` | `wscanf_s` |
152
+ | `localtime_s` | `strerrorlen_s` | `vsscanf_s` | |
153
+ | `mbsrtowcs_s` | `strlen_s` | `vswprintf_s` | |
154
+
155
 
156
  #### Freestanding implementations <a id="compliance">[[compliance]]</a>
157
 
158
  Two kinds of implementations are defined: *hosted* and *freestanding* (
159
  [[intro.compliance]]). For a hosted implementation, this International
 
164
  [[tab:cpp.headers.freestanding]].
165
 
166
  **Table: C++headers for freestanding implementations** <a id="tab:cpp.headers.freestanding">[tab:cpp.headers.freestanding]</a>
167
 
168
  | Subclause | | Header |
169
+ | --------------------------------------------- | ------------------------- | --------------------------------- |
170
  | | | `<ciso646>` |
171
  | [[support.types]] | Types | `<cstddef>` |
172
  | [[support.limits]] | Implementation properties | `<cfloat>` `<limits>` `<climits>` |
173
  | [[cstdint]] | Integer types | `<cstdint>` |
174
  | [[support.start.term]] | Start and termination | `<cstdlib>` |
175
  | [[support.dynamic]] | Dynamic memory management | `<new>` |
176
  | [[support.rtti]] | Type identification | `<typeinfo>` |
177
  | [[support.exception]] | Exception handling | `<exception>` |
178
  | [[support.initlist]] | Initializer lists | `<initializer_list>` |
179
+ | [[support.runtime]] | Other runtime support | `<cstdarg>` |
180
  | [[meta]] | Type traits | `<type_traits>` |
181
  | [[atomics]] | Atomics | `<atomic>` |
182
+ | [[depr.cstdalign.syn]], [[depr.cstdbool.syn]] | Deprecated headers | `<cstdalign>` `<cstdbool>` |
183
 
184
 
185
  The supplied version of the header `<cstdlib>` shall declare at least
186
  the functions `abort`, `atexit`, `at_quick_exit`, `exit`, and
187
  `quick_exit` ([[support.start.term]]). The other headers listed in this
 
204
 
205
  A translation unit may include library headers in any order (Clause 
206
  [[lex]]). Each may be included more than once, with no effect different
207
  from being included exactly once, except that the effect of including
208
  either `<cassert>` or `<assert.h>` depends each time on the lexically
209
+ current definition of `NDEBUG`.[^19]
210
 
211
+ A translation unit shall include a header only outside of any
212
  declaration or definition, and shall include the header lexically before
213
  the first reference in that translation unit to any of the entities
214
  declared in that header. No diagnostic is required.
215
 
216
  #### Linkage <a id="using.linkage">[[using.linkage]]</a>
 
220
  the default `extern "C++"` linkage ([[dcl.link]]).
221
 
222
  Whether a name from the C standard library declared with external
223
  linkage has `extern "C"` or `extern "C++"` linkage is
224
  *implementation-defined*. It is recommended that an implementation use
225
+ `extern "C++"` linkage for this purpose.[^20]
226
 
227
  Objects and functions defined in the library and required by a
228
  C++program are included in the program prior to program startup.
229
 
230
+ See also replacement functions ([[replacement.functions]]), runtime
231
+ changes ([[handler.functions]]).
232
 
233
  ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
234
 
235
  [[utility.arg.requirements]] describes requirements on types and
236
  expressions used to instantiate templates defined in the C++standard
 
243
  allocators.
244
 
245
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
246
 
247
  The template definitions in the C++standard library refer to various
248
+ named requirements whose details are set out in Tables 
249
+ [[tab:equalitycomparable]]– [[tab:destructible]]. In these tables, `T`
250
+ is an object or reference type to be supplied by a C++program
251
+ instantiating a template; `a`, `b`, and `c` are values of type (possibly
252
+ `const`) `T`; `s` and `t` are modifiable lvalues of type `T`; `u`
253
+ denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
254
+ lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
255
 
256
  In general, a default constructor is not required. Certain container
257
  class member function signatures specify `T()` as a default argument.
258
  `T()` shall be a well-defined expression ([[dcl.init]]) if one of those
259
  signatures is called using the default argument ([[dcl.fct.default]]).
260
 
261
  **Table: `EqualityComparable` requirements** <a id="equalitycomparable">[equalitycomparable]</a>
262
 
263
+ | Expression | Return type |
264
+ | ---------- | ----------- |
265
  | `a == b` | convertible to `bool` | `==` is an equivalence relation, that is, it has the following properties: For all `a`, `a == a`.; If `a == b`, then `b == a`.; If `a == b` and `b == c`, then `a == c`. |
266
 
267
  **Table: `LessThanComparable` requirements** <a id="lessthancomparable">[lessthancomparable]</a>
268
 
269
+ | Expression | Return type | Requirement |
270
+ | ---------- | --------------------- | --------------------------------------------------------- |
271
  | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation~([[alg.sorting]]) |
272
 
273
  **Table: `DefaultConstructible` requirements** <a id="defaultconstructible">[defaultconstructible]</a>
274
 
275
+ | Expression | Post-condition |
276
+ | -------------- | ------------------------------------------------------------------- |
277
  | `T t;` | object `t` is default-initialized |
278
+ | `T u{};` | object `u` is value-initialized or aggregate-initialized |
279
+ | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
 
280
 
281
+ [*Note 1*: `rv` must still meet the requirements of the library
282
+ component that is using it. The operations listed in those requirements
283
+ must work as specified whether `rv` has been moved from or
284
+ not. *end note*]
 
 
 
285
 
286
  **Table: `CopyConstructible` requirements (in addition to `MoveConstructible`)** <a id="copyconstructible">[copyconstructible]</a>
287
 
288
+ | Expression | Post-condition |
289
  | ---------- | --------------------------------------------------------- |
290
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
291
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
292
 
293
+ [*Note 2*:  `rv` must still meet the requirements of the library
294
+ component that is using it, whether or not `t` and `rv` refer to the
295
+ same object. The operations listed in those requirements must work as
296
+ specified whether `rv` has been moved from or not. — *end note*]
 
 
297
 
298
  **Table: `CopyAssignable` requirements (in addition to `MoveAssignable`)** <a id="copyassignable">[copyassignable]</a>
299
 
300
+ | Expression | Return type | Return value | Post-condition |
301
+ | ---------- | ----------- | ------------ | ------------------------------------------------------- |
302
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
303
 
304
 
305
  **Table: `Destructible` requirements** <a id="destructible">[destructible]</a>
306
 
307
+ | Expression | Post-condition |
308
+ | ---------- | --------------------------------------------------------------------- |
309
  | `u.~T()` | All resources owned by `u` are reclaimed, no exception is propagated. |
310
 
311
 
312
  #### `Swappable` requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
313
 
 
331
  - the two `swap` function templates defined in `<utility>` (
332
  [[utility]]) and
333
  - the lookup set produced by argument-dependent lookup (
334
  [[basic.lookup.argdep]]).
335
 
336
+ [*Note 1*: If `T` and `U` are both fundamental types or arrays of
337
+ fundamental types and the declarations from the header `<utility>` are
338
+ in scope, the overall lookup set described above is equivalent to that
339
+ of the qualified name lookup applied to the expression `std::swap(t, u)`
340
+ or `std::swap(u, t)` as appropriate. — *end note*]
341
 
342
+ [*Note 2*: It is unspecified whether a library component that has a
343
+ swappable requirement includes the header `<utility>` to ensure an
344
+ appropriate evaluation context. — *end note*]
345
 
346
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
347
  with any rvalue or lvalue, respectively, of type `T`.
348
 
349
  A type `X` satisfying any of the iterator requirements (
350
  [[iterator.requirements]]) satisfies the requirements of
351
  `ValueSwappable` if, for any dereferenceable object `x` of type `X`,
352
  `*x` is swappable.
353
 
354
+ [*Example 1*:
355
+
356
  User code can ensure that the evaluation of `swap` calls is performed in
357
  an appropriate context under the various conditions as follows:
358
 
359
  ``` cpp
360
  #include <utility>
 
367
  // for rvalues and lvalues
368
  }
369
 
370
  // Requires: lvalues of T shall be swappable.
371
  template <class T>
372
+ void lv_swap(T& t1, T& t2) {
373
  using std::swap;
374
  swap(t1, t2); // OK: uses swappable conditions for
375
  } // lvalues of type T
376
 
377
  namespace N {
 
395
  value_swap(a1, proxy(a2));
396
  assert(a1.m == -5 && a2.m == 5);
397
  }
398
  ```
399
 
400
+ — *end example*]
401
+
402
  #### `NullablePointer` requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
403
 
404
  A `NullablePointer` type is a pointer-like type that supports null
405
  values. A type `P` meets the requirements of `NullablePointer` if:
406
 
407
  - `P` satisfies the requirements of `EqualityComparable`,
408
  `DefaultConstructible`, `CopyConstructible`, `CopyAssignable`, and
409
  `Destructible`,
410
  - lvalues of type `P` are swappable ([[swappable.requirements]]),
411
+ - the expressions shown in Table  [[tab:nullablepointer]] are valid and
412
+ have the indicated semantics, and
413
  - `P` satisfies all the other requirements of this subclause.
414
 
415
  A value-initialized object of type `P` produces the null value of the
416
  type. The null value shall be equivalent only to itself. A
417
  default-initialized object of type `P` may have an indeterminate value.
418
+
419
+ [*Note 1*: Operations involving indeterminate values may cause
420
+ undefined behavior. — *end note*]
421
 
422
  An object `p` of type `P` can be contextually converted to `bool`
423
  (Clause  [[conv]]). The effect shall be as if `p != nullptr` had been
424
  evaluated in place of `p`.
425
 
426
  No operation which is part of the `NullablePointer` requirements shall
427
  exit via an exception.
428
 
429
+ In Table  [[tab:nullablepointer]], `u` denotes an identifier, `t`
430
+ denotes a non-`const` lvalue of type `P`, `a` and `b` denote values of
431
+ type (possibly `const`) `P`, and `np` denotes a value of type (possibly
432
  `const`) `std::nullptr_t`.
433
 
434
  **Table: `NullablePointer` requirements** <a id="nullablepointer">[nullablepointer]</a>
435
 
436
  | | | |
437
+ | -------------- | ---------------------------------- | ---------------------------------- |
438
+ | `P u(np);`<br> | | Postconditions: `u == nullptr` |
439
  | `P u = np;` | | |
440
+ | `P(np)` | | Postconditions: `P(np) == nullptr` |
441
+ | `t = np` | `P&` | Postconditions: `t == nullptr` |
442
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
443
  | `a == np` | contextually convertible to `bool` | `a == P()` |
444
  | `np == a` | | |
445
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
446
  | `np != a` | | |
 
451
  A type `H` meets the `Hash` requirements if:
452
 
453
  - it is a function object type ([[function.objects]]),
454
  - it satisfies the requirements of `CopyConstructible` and
455
  `Destructible` ([[utility.arg.requirements]]), and
456
+ - the expressions shown in Table  [[tab:hash]] are valid and have the
457
  indicated semantics.
458
 
459
  Given `Key` is an argument type for function objects of type `H`, in
460
+ Table  [[tab:hash]] `h` is a value of type (possibly `const`) `H`, `u`
461
+ is an lvalue of type `Key`, and `k` is a value of a type convertible to
462
  (possibly `const`) `Key`.
463
 
464
+ [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
465
+ value for `k` yield the same result for a given execution of the
466
+ program. — *end note*]
 
 
 
 
467
 
468
  #### Allocator requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
469
 
470
  The library describes a standard set of requirements for *allocators*,
471
  which are class-type objects that encapsulate the information about an
 
475
  primitives for it. All of the string types (Clause  [[strings]]),
476
  containers (Clause  [[containers]]) (except array), string buffers and
477
  string streams (Clause  [[input.output]]), and `match_results` (Clause 
478
  [[re]]) are parameterized in terms of allocators.
479
 
480
+ The class template `allocator_traits` ([[allocator.traits]]) supplies a
481
+ uniform interface to all allocator types. Table  [[tab:desc.var.def]]
482
  describes the types manipulated through allocators. Table 
483
  [[tab:utilities.allocator.requirements]] describes the requirements on
484
  allocator types and thus on types used to instantiate
485
  `allocator_traits`. A requirement is optional if the last column of
486
  Table  [[tab:utilities.allocator.requirements]] specifies a default for
 
491
  defaults for different requirements than the primary template. Within
492
  Tables  [[tab:desc.var.def]] and 
493
  [[tab:utilities.allocator.requirements]], the use of `move` and
494
  `forward` always refers to `std::move` and `std::forward`, respectively.
495
 
496
+ [*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
497
+
498
  Note A: The member class template `rebind` in the table above is
499
+ effectively a typedef template.
500
+
501
+ [*Note 2*: In general, if the name `Allocator` is bound to
502
+ `SomeAllocator<T>`, then `Allocator::rebind<U>::other` is the same type
503
+ as `SomeAllocator<U>`, where `SomeAllocator<T>::value_type` is `T` and
504
+ `SomeAllocator<U>::{}value_type` is `U`. *end note*]
505
+
506
+ If `Allocator` is a class template instantiation of the form
507
+ `SomeAllocator<T, Args>`, where `Args` is zero or more type arguments,
508
+ and `Allocator` does not supply a `rebind` member template, the standard
509
+ `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
510
+ `Allocator::{}rebind<U>::other` by default. For allocator types that are
511
+ not template instantiations of the above form, no default is provided.
512
+
513
+ Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
514
+ `X` shall satisfy the `CopyAssignable` requirements (Table 
515
+ [[tab:copyassignable]]) and the copy operation shall not throw
516
+ exceptions. If `X::propagate_on_container_move_assignment::value` is
517
+ `true`, `X` shall satisfy the `MoveAssignable` requirements (Table 
518
+ [[tab:moveassignable]]) and the move operation shall not throw
519
+ exceptions. If `X::propagate_on_container_swap::value` is `true`,
520
+ lvalues of type `X` shall be swappable ([[swappable.requirements]]) and
521
+ the `swap` operation shall not throw exceptions.
522
 
523
  An allocator type `X` shall satisfy the requirements of
524
  `CopyConstructible` ([[utility.arg.requirements]]). The `X::pointer`,
525
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
526
  shall satisfy the requirements of `NullablePointer` (
527
+ [[nullablepointer.requirements]]). No constructor, comparison function,
528
+ copy operation, move operation, or swap operation on these pointer types
529
+ shall exit via an exception. `X::pointer` and `X::const_pointer` shall
530
+ also satisfy the requirements for a random access iterator (
531
+ [[random.access.iterators]]) and of a contiguous iterator (
532
+ [[iterator.requirements.general]]).
533
 
534
  Let `x1` and `x2` denote objects of (possibly different) types
535
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
536
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
537
  pointer values, if and only if both `x1` and `x2` can be explicitly
 
565
 
566
  either or both objects may be replaced by an equivalently-valued object
567
  of type `X::const_pointer` with no change in semantics.
568
 
569
  An allocator may constrain the types on which it can be instantiated and
570
+ the arguments for which its `construct` or `destroy` members may be
571
+ called. If a type cannot be used with a particular allocator, the
572
+ allocator class or the call to `construct` or `destroy` may fail to
573
+ instantiate.
574
 
575
+ [*Example 1*:
576
+
577
+ The following is an allocator class template supporting the minimal
578
  interface that satisfies the requirements of Table 
579
  [[tab:utilities.allocator.requirements]]:
580
 
581
  ``` cpp
582
  template <class Tp>
 
594
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
595
  template <class T, class U>
596
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
597
  ```
598
 
599
+ — *end example*]
600
+
601
  If the alignment associated with a specific over-aligned type is not
602
  supported by an allocator, instantiation of the allocator for that type
603
  may fail. The allocator also may silently ignore the requested
604
+ alignment.
605
+
606
+ [*Note 3*: Additionally, the member function `allocate` for that type
607
+ may fail by throwing an object of type `bad_alloc`. — *end note*]
608
+
609
+ ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
610
+
611
+ If `X` is an allocator class for type `T`, `X` additionally satisfies
612
+ the allocator completeness requirements if, whether or not `T` is a
613
+ complete type:
614
+
615
+ - `X` is a complete type, and
616
+ - all the member types of `allocator_traits<X>` ([[allocator.traits]])
617
+ other than `value_type` are complete types.
618
 
619
  ### Constraints on programs <a id="constraints">[[constraints]]</a>
620
 
621
  #### Overview <a id="constraints.overview">[[constraints.overview]]</a>
622
 
 
637
  definitions to namespace `std` or to a namespace within namespace `std`
638
  unless otherwise specified. A program may add a template specialization
639
  for any standard library template to namespace `std` only if the
640
  declaration depends on a user-defined type and the specialization meets
641
  the standard library requirements for the original template and is not
642
+ explicitly prohibited.[^21]
643
 
644
  The behavior of a C++program is undefined if it declares
645
 
646
  - an explicit specialization of any member function of a standard
647
  library class template, or
648
  - an explicit specialization of any member function template of a
649
  standard library class or class template, or
650
  - an explicit or partial specialization of any member class template of
651
+ a standard library class or class template, or
652
+ - a deduction guide for any standard library class template.
653
 
654
  A program may explicitly instantiate a template defined in the standard
655
  library only if the declaration depends on the name of a user-defined
656
  type and the instantiation meets the standard library requirements for
657
  the original template.
 
664
  The behavior of a C++program is undefined if it adds declarations or
665
  definitions to namespace `posix` or to a namespace within namespace
666
  `posix` unless otherwise specified. The namespace `posix` is reserved
667
  for use by ISO/IEC 9945 and other POSIX standards.
668
 
669
+ ##### Namespaces for future standardization <a id="namespace.future">[[namespace.future]]</a>
670
+
671
+ Top level namespaces with a name starting with `std` and followed by a
672
+ non-empty sequence of digits are reserved for future standardization.
673
+ The behavior of a C++program is undefined if it adds declarations or
674
+ definitions to such a namespace.
675
+
676
+ [*Example 1*: The top level namespace `std2` is reserved for use by
677
+ future revisions of this International Standard. — *end example*]
678
+
679
  #### Reserved names <a id="reserved.names">[[reserved.names]]</a>
680
 
681
  The C++standard library reserves the following kinds of names:
682
 
683
  - macros
 
686
 
687
  If a program declares or defines a name in a context where it is
688
  reserved, other than as explicitly allowed by this Clause, its behavior
689
  is undefined.
690
 
691
+ ##### Zombie names <a id="zombie.names">[[zombie.names]]</a>
692
+
693
+ In namespace `std`, the following names are reserved for previous
694
+ standardization:
695
+
696
+ - `auto_ptr`,
697
+ - `binary_function`,
698
+ - `bind1st`,
699
+ - `bind2nd`,
700
+ - `binder1st`,
701
+ - `binder2nd`,
702
+ - `const_mem_fun1_ref_t`,
703
+ - `const_mem_fun1_t`,
704
+ - `const_mem_fun_ref_t`,
705
+ - `const_mem_fun_t`,
706
+ - `get_unexpected`,
707
+ - `mem_fun1_ref_t`,
708
+ - `mem_fun1_t`,
709
+ - `mem_fun_ref_t`,
710
+ - `mem_fun_ref`,
711
+ - `mem_fun_t`,
712
+ - `mem_fun`,
713
+ - `pointer_to_binary_function`,
714
+ - `pointer_to_unary_function`,
715
+ - `ptr_fun`,
716
+ - `random_shuffle`,
717
+ - `set_unexpected`,
718
+ - `unary_function`,
719
+ - `unexpected`, and
720
+ - `unexpected_handler`.
721
+
722
  ##### Macro names <a id="macro.names">[[macro.names]]</a>
723
 
724
  A translation unit that includes a standard library header shall not
725
  `#define` or `#undef` names declared in any standard library header.
726
 
727
  A translation unit shall not `#define` or `#undef` names lexically
728
  identical to keywords, to the identifiers listed in Table 
729
  [[tab:identifiers.special]], or to the *attribute-token*s described in 
730
  [[dcl.attr]].
731
 
 
 
 
 
 
 
 
 
 
 
 
732
  ##### External linkage <a id="extern.names">[[extern.names]]</a>
733
 
734
  Each name declared as an object with external linkage in a header is
735
  reserved to the implementation to designate that library object with
736
+ external linkage, [^22] both in namespace `std` and in the global
737
  namespace.
738
 
739
  Each global function signature declared with external linkage in a
740
  header is reserved to the implementation to designate that function
741
+ signature with external linkage.[^23]
742
 
743
+ Each name from the C standard library declared with external linkage is
744
  reserved to the implementation for use as a name with `extern "C"`
745
+ linkage, both in namespace `std` and in the global namespace.
746
 
747
+ Each function signature from the C standard library declared with
748
  external linkage is reserved to the implementation for use as a function
749
+ signature with both `extern "C"` and `extern "C++"` linkage,[^24] or as
750
  a name of namespace scope in the global namespace.
751
 
752
  ##### Types <a id="extern.types">[[extern.types]]</a>
753
 
754
+ For each type T from the C standard library,[^25] the types `::T` and
755
  `std::T` are reserved to the implementation and, when defined, `::T`
756
  shall be identical to `std::T`.
757
 
758
  ##### User-defined literal suffixes <a id="usrlit.suffix">[[usrlit.suffix]]</a>
759
 
760
+ Literal suffix identifiers ([[over.literal]]) that do not start with an
761
+ underscore are reserved for future standardization.
762
 
763
  #### Headers <a id="alt.headers">[[alt.headers]]</a>
764
 
765
  If a file with a name equivalent to the derived file name for one of the
766
  C++standard library headers is not provided as part of the
 
780
  describe the behavior of numerous functions defined by the C++standard
781
  library. Under some circumstances, however, certain of these function
782
  descriptions also apply to replacement functions defined in the
783
  program ([[definitions]]).
784
 
785
+ A C++program may provide the definition for any of the following dynamic
786
+ memory allocation function signatures declared in header `<new>` (
787
  [[basic.stc.dynamic]], [[support.dynamic]]):
788
 
789
+ ``` cpp
790
+ operator new(std::size_t)
791
+ operator new(std::size_t, std::align_val_t)
792
+ operator new(std::size_t, const std::nothrow_t&)
793
+ operator new(std::size_t, std::align_val_t, const std::nothrow_t&)
794
+ ```
795
+
796
+ ``` cpp
797
+ operator delete(void*)
798
+ operator delete(void*, std::size_t)
799
+ operator delete(void*, std::align_val_t)
800
+ operator delete(void*, std::size_t, std::align_val_t)
801
+ operator delete(void*, const std::nothrow_t&)
802
+ operator delete(void*, std::align_val_t, const std::nothrow_t&)
803
+ ```
804
+
805
+ ``` cpp
806
+ operator new[](std::size_t)
807
+ operator new[](std::size_t, std::align_val_t)
808
+ operator new[](std::size_t, const std::nothrow_t&)
809
+ operator new[](std::size_t, std::align_val_t, const std::nothrow_t&)
810
+ ```
811
+
812
+ ``` cpp
813
+ operator delete[](void*)
814
+ operator delete[](void*, std::size_t)
815
+ operator delete[](void*, std::align_val_t)
816
+ operator delete[](void*, std::size_t, std::align_val_t)
817
+ operator delete[](void*, const std::nothrow_t&)
818
+ operator delete[](void*, std::align_val_t, const std::nothrow_t&)
819
+ ```
820
 
821
  The program’s definitions are used instead of the default versions
822
  supplied by the implementation ([[support.dynamic]]). Such replacement
823
  occurs prior to program startup ([[basic.def.odr]], [[basic.start]]).
824
+ The program’s declarations shall not be specified as `inline`. No
825
  diagnostic is required.
826
 
827
  #### Handler functions <a id="handler.functions">[[handler.functions]]</a>
828
 
829
+ The C++standard library provides a default version of the following
830
+ handler function (Clause  [[language.support]]):
831
 
 
832
  - `terminate_handler`
833
 
834
  A C++program may install different handler functions during execution,
835
  by supplying a pointer to a function defined in the program or the
836
  library as an argument to (respectively):
837
 
838
  - `set_new_handler`
839
+ - `set_terminate`
840
+
841
+ See also subclauses  [[alloc.errors]], Storage allocation errors, and 
842
+ [[support.exception]], Exception handling.
843
 
844
  A C++program can get a pointer to the current handler function by
845
  calling the following functions:
846
 
847
  - `get_new_handler`
 
848
  - `get_terminate`
849
 
850
  Calling the `set_*` and `get_*` functions shall not incur a data race. A
851
  call to any of the `set_*` functions shall synchronize with subsequent
852
  calls to the same `set_*` function and to the corresponding `get_*`
 
855
  #### Other functions <a id="res.on.functions">[[res.on.functions]]</a>
856
 
857
  In certain cases (replacement functions, handler functions, operations
858
  on types used to instantiate standard library template components), the
859
  C++standard library depends on components supplied by a C++program. If
860
+ these components do not meet their requirements, this International
861
+ Standard places no requirements on the implementation.
862
 
863
  In particular, the effects are undefined in the following cases:
864
 
865
  - for replacement functions ([[new.delete]]), if the installed
866
  replacement function does not implement the semantics of the
867
  applicable *Required behavior:* paragraph.
868
+ - for handler functions ([[new.handler]], [[terminate.handler]]), if
869
+ the installed handler function does not implement the semantics of the
870
+ applicable *Required behavior:* paragraph
 
871
  - for types used as template arguments when instantiating a template
872
  component, if the operations on the type do not implement the
873
+ semantics of the applicable *Requirements* subclause (
874
+ [[allocator.requirements]], [[container.requirements]],
875
+ [[iterator.requirements]], [[algorithms.requirements]],
876
  [[numeric.requirements]]). Operations on such types can report a
877
  failure by throwing an exception unless otherwise specified.
878
  - if any replacement function or handler function or destructor
879
  operation exits via an exception, unless specifically allowed in the
880
  applicable *Required behavior:* paragraph.
 
895
  address computations and accesses to objects (that would be valid if
896
  the pointer did point to the first element of such an array) are in
897
  fact valid.
898
  - If a function argument binds to an rvalue reference parameter, the
899
  implementation may assume that this parameter is a unique reference to
900
+ this argument. \[*Note 1*: If the parameter is a generic parameter of
901
+ the form `T&&` and an lvalue of type `A` is bound, the argument binds
902
+ to an lvalue reference ([[temp.deduct.call]]) and thus is not covered
903
+ by the previous sentence. *end note*] \[*Note 2*: If a program
904
+ casts an lvalue to an xvalue while passing that lvalue to a library
905
+ function (e.g. by calling the function with the argument
906
+ `std::move(x)`), the program is effectively asking that function to
907
+ treat that lvalue as a temporary. The implementation is free to
908
+ optimize away aliasing checks which might be needed if the argument
909
+ was an lvalue. — *end note*]
910
 
911
+ #### Library object access <a id="res.on.objects">[[res.on.objects]]</a>
912
 
913
  The behavior of a program is undefined if calls to standard library
914
  functions from different threads may introduce a data race. The
915
  conditions under which this may occur are specified in 
916
+ [[res.on.data.races]].
 
 
 
917
 
918
+ [*Note 1*: Modifying an object of a standard library type that is
919
+ shared between threads risks undefined behavior unless objects of that
920
+ type are explicitly specified as being sharable without data races or
921
+ the user supplies a locking mechanism. *end note*]
922
+
923
+ If an object of a standard library type is accessed, and the beginning
924
+ of the object’s lifetime ([[basic.life]]) does not happen before the
925
+ access, or the access does not happen before the end of the object’s
926
+ lifetime, the behavior is undefined unless otherwise specified.
927
+
928
+ [*Note 2*: This applies even to objects such as mutexes intended for
929
+ thread synchronization. — *end note*]
930
 
931
  #### Requires paragraph <a id="res.on.required">[[res.on.required]]</a>
932
 
933
  Violation of the preconditions specified in a function’s *Requires:*
934
  paragraph results in undefined behavior unless the function’s *Throws:*
 
941
 
942
  This section describes the constraints upon, and latitude of,
943
  implementations of the C++standard library.
944
 
945
  An implementation’s use of headers is discussed in  [[res.on.headers]],
946
+ its use of macros in  [[res.on.macro.definitions]], non-member functions
947
+ in  [[global.functions]], member functions in  [[member.functions]],
948
+ data race avoidance in  [[res.on.data.races]], access specifiers in 
949
  [[protection.within.classes]], class derivation in  [[derivation]], and
950
  exceptions in  [[res.on.exception.handling]].
951
 
952
  #### Headers <a id="res.on.headers">[[res.on.headers]]</a>
953
 
 
960
  Certain types and macros are defined in more than one header. Every such
961
  entity shall be defined such that any header that defines it may be
962
  included after any other header that also defines it (
963
  [[basic.def.odr]]).
964
 
965
+ The C standard library headers ([[depr.c.headers]]) shall include only
966
+ their corresponding C++standard library header, as described in 
967
+ [[headers]].
968
 
969
  #### Restrictions on macro definitions <a id="res.on.macro.definitions">[[res.on.macro.definitions]]</a>
970
 
971
  The names and global function signatures described in  [[contents]] are
972
  reserved to the implementation.
 
974
  All object-like macros defined by the C standard library and described
975
  in this Clause as expanding to integral constant expressions are also
976
  suitable for use in `#if` preprocessing directives, unless explicitly
977
  stated otherwise.
978
 
979
+ #### Non-member functions <a id="global.functions">[[global.functions]]</a>
980
 
981
+ It is unspecified whether any non-member functions in the C++standard
982
+ library are defined as `inline` ([[dcl.inline]]).
983
 
984
+ A call to a non-member function signature described in Clauses 
985
+ [[language.support]] through  [[thread]] and Annex  [[depr]] shall
986
+ behave as if the implementation declared no additional non-member
987
+ function signatures.[^26]
988
 
989
+ An implementation shall not declare a non-member function signature with
990
+ additional default arguments.
991
 
992
+ Unless otherwise specified, calls made by functions in the standard
993
+ library to non-operator, non-member functions do not use functions from
994
+ another namespace which are found through *argument-dependent name
995
+ lookup* ([[basic.lookup.argdep]]).
996
+
997
+ [*Note 1*:
998
+
999
+ The phrase “unless otherwise specified” applies to cases such as the
1000
+ swappable with requirements ([[swappable.requirements]]). The exception
1001
+ for overloaded operators allows argument-dependent lookup in cases like
1002
+ that of `ostream_iterator::operator=` ([[ostream.iterator.ops]]):
1003
 
1004
  *Effects:*
1005
 
1006
  ``` cpp
1007
  *out_stream << value;
1008
  if (delim != 0)
1009
  *out_stream << delim;
1010
  return *this;
1011
  ```
1012
 
1013
+ — *end note*]
1014
+
1015
  #### Member functions <a id="member.functions">[[member.functions]]</a>
1016
 
1017
  It is unspecified whether any member functions in the C++standard
1018
+ library are defined as `inline` ([[dcl.inline]]).
1019
 
1020
+ For a non-virtual member function described in the C++standard library,
1021
+ an implementation may declare a different set of member function
1022
+ signatures, provided that any call to the member function that would
1023
+ select an overload from the set of declarations described in this
1024
+ International Standard behaves as if that overload were selected.
1025
 
1026
+ [*Note 1*: For instance, an implementation may add parameters with
1027
+ default values, or replace a member function with default arguments with
1028
+ two or more member functions with equivalent behavior, or add additional
1029
+ signatures for a member function name. *end note*]
 
 
1030
 
1031
+ #### Constexpr functions and constructors <a id="constexpr.functions">[[constexpr.functions]]</a>
 
 
1032
 
1033
+ This International Standard explicitly requires that certain standard
1034
+ library functions are `constexpr` ([[dcl.constexpr]]). An
1035
+ implementation shall not declare any standard library function signature
1036
+ as `constexpr` except for those where it is explicitly required. Within
1037
+ any header that provides any non-defining declarations of constexpr
1038
+ functions or constructors an implementation shall provide corresponding
1039
+ definitions.
 
1040
 
1041
  #### Requirements for stable algorithms <a id="algorithm.stable">[[algorithm.stable]]</a>
1042
 
1043
  When the requirements for an algorithm state that it is “stable” without
1044
  further elaboration, it means:
 
1052
  original order) precede the elements from the second range (preserving
1053
  their original order).
1054
 
1055
  #### Reentrancy <a id="reentrancy">[[reentrancy]]</a>
1056
 
1057
+ Except where explicitly specified in this International Standard, it is
1058
+ *implementation-defined* which functions in the C++standard library may
1059
  be recursively reentered.
1060
 
1061
  #### Data race avoidance <a id="res.on.data.races">[[res.on.data.races]]</a>
1062
 
1063
  This section specifies requirements that implementations shall meet to
 
1074
  A C++standard library function shall not directly or indirectly modify
1075
  objects ([[intro.multithread]]) accessible by threads other than the
1076
  current thread unless the objects are accessed directly or indirectly
1077
  via the function’s non-const arguments, including `this`.
1078
 
1079
+ [*Note 1*: This means, for example, that implementations can’t use a
1080
+ static object for internal purposes without synchronization because it
1081
+ could cause a data race even in programs that do not explicitly share
1082
+ objects between threads. — *end note*]
1083
 
1084
  A C++standard library function shall not access objects indirectly
1085
  accessible via its arguments or via elements of its container arguments
1086
  except by invoking functions required by its specification on those
1087
  container elements.
1088
 
1089
  Operations on iterators obtained by calling a standard library container
1090
  or string member function may access the underlying container, but shall
1091
+ not modify it.
1092
+
1093
+ [*Note 2*: In particular, container operations that invalidate
1094
  iterators conflict with operations on iterators associated with that
1095
+ container. — *end note*]
1096
 
1097
  Implementations may share their own internal objects between threads if
1098
  the objects are not visible to users and are protected against data
1099
  races.
1100
 
1101
  Unless otherwise specified, C++standard library functions shall perform
1102
  all operations solely within the current thread if those operations have
1103
  effects that are visible ([[intro.multithread]]) to users.
1104
 
1105
+ [*Note 3*: This allows implementations to parallelize operations if
1106
+ there are no visible side effects. — *end note*]
1107
 
1108
  #### Protection within classes <a id="protection.within.classes">[[protection.within.classes]]</a>
1109
 
1110
  It is unspecified whether any function signature or class described in
1111
  Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]] is
 
1123
  implementation.
1124
 
1125
  In any case:
1126
 
1127
  - Every base class described as `virtual` shall be virtual;
1128
+ - Every base class not specified as `virtual` shall not be virtual;
1129
  - Unless explicitly stated otherwise, types with distinct names shall be
1130
+ distinct types.[^27]
1131
+
1132
+ All types specified in the C++standard library shall be non-`final`
1133
+ types unless otherwise specified.
1134
 
1135
  #### Restrictions on exception handling <a id="res.on.exception.handling">[[res.on.exception.handling]]</a>
1136
 
1137
  Any of the functions defined in the C++standard library can report a
1138
+ failure by throwing an exception of a type described in its *Throws:*
1139
+ paragraph, or of a type derived from a type named in the *Throws:*
1140
+ paragraph that would be caught by an exception handler for the base
1141
+ type.
1142
 
1143
+ Functions from the C standard library shall not throw exceptions [^28]
 
 
 
 
1144
  except when such a function calls a program-supplied function that
1145
+ throws an exception.[^29]
1146
 
1147
  Destructor operations defined in the C++standard library shall not throw
1148
  exceptions. Every destructor in the C++standard library shall behave as
1149
+ if it had a non-throwing exception specification.
1150
+
1151
+ Functions defined in the C++standard library that do not have a
1152
+ *Throws:* paragraph but do have a potentially-throwing exception
1153
+ specification may throw *implementation-defined* exceptions. [^30]
1154
+ Implementations should report errors by throwing exceptions of or
1155
+ derived from the standard exception classes ([[bad.alloc]],
1156
+ [[support.exception]], [[std.exceptions]]).
1157
+
1158
+ An implementation may strengthen the exception specification for a
1159
+ non-virtual function by adding a non-throwing exception specification.
1160
 
1161
  #### Restrictions on storage of pointers <a id="res.on.pointer.storage">[[res.on.pointer.storage]]</a>
1162
 
1163
  Objects constructed by the standard library that may hold a
1164
  user-supplied pointer value or an integer of type `std::intptr_t` shall
1165
  store such values in a traceable pointer location (
1166
+ [[basic.stc.dynamic.safety]]).
1167
+
1168
+ [*Note 1*: Other libraries are strongly encouraged to do the same,
1169
+ since not doing so may result in accidental use of pointers that are not
1170
+ safely derived. Libraries that store pointers outside the user’s address
1171
+ space should make it appear that they are stored and retrieved from a
1172
+ traceable pointer location. — *end note*]
1173
 
1174
  #### Value of error codes <a id="value.error.codes">[[value.error.codes]]</a>
1175
 
1176
  Certain functions in the C++standard library report errors via a
1177
  `std::error_code` ([[syserr.errcode.overview]]) object. That object’s
1178
  `category()` member shall return `std::system_category()` for errors
1179
  originating from the operating system, or a reference to an
1180
  *implementation-defined* `error_category` object for errors originating
1181
  elsewhere. The implementation shall define the possible values of
1182
+ `value()` for each of these error categories.
1183
+
1184
+ [*Example 1*: For operating systems that are based on POSIX,
1185
+ implementations are encouraged to define the `std::system_category()`
1186
+ values as identical to the POSIX `errno` values, with additional values
1187
+ as defined by the operating system’s documentation. Implementations for
1188
+ operating systems that are not based on POSIX are encouraged to define
1189
+ values identical to the operating system’s values. For errors that do
1190
+ not originate from the operating system, the implementation may provide
1191
+ enums for the associated values. — *end example*]
1192
 
1193
  #### Moved-from state of library types <a id="lib.types.movedfrom">[[lib.types.movedfrom]]</a>
1194
 
1195
  Objects of types defined in the C++standard library may be moved from (
1196
  [[class.copy]]). Move operations may be explicitly specified or
 
1200
  <!-- Link reference definitions -->
1201
  [alg.c.library]: algorithms.md#alg.c.library
1202
  [alg.sorting]: algorithms.md#alg.sorting
1203
  [algorithm.stable]: #algorithm.stable
1204
  [algorithms]: algorithms.md#algorithms
1205
+ [algorithms.requirements]: algorithms.md#algorithms.requirements
1206
  [alloc.errors]: language.md#alloc.errors
1207
  [allocator.requirements]: #allocator.requirements
1208
+ [allocator.requirements.completeness]: #allocator.requirements.completeness
1209
  [allocator.traits]: utilities.md#allocator.traits
1210
  [alt.headers]: #alt.headers
1211
  [atomics]: atomics.md#atomics
1212
  [bad.alloc]: language.md#bad.alloc
1213
  [basic.def.odr]: basic.md#basic.def.odr
1214
  [basic.fundamental]: basic.md#basic.fundamental
1215
+ [basic.life]: basic.md#basic.life
1216
  [basic.link]: basic.md#basic.link
1217
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
1218
  [basic.scope.namespace]: basic.md#basic.scope.namespace
1219
  [basic.start]: basic.md#basic.start
1220
  [basic.stc.dynamic]: basic.md#basic.stc.dynamic
 
1223
  [bitmask.types]: #bitmask.types
1224
  [byte.strings]: #byte.strings
1225
  [c.locales]: localization.md#c.locales
1226
  [c.strings]: strings.md#c.strings
1227
  [character.seq]: #character.seq
1228
+ [class.conv.ctor]: special.md#class.conv.ctor
1229
  [class.copy]: special.md#class.copy
1230
  [class.ctor]: special.md#class.ctor
1231
  [class.dtor]: special.md#class.dtor
1232
  [class.mem]: class.md#class.mem
1233
  [class.mfct]: class.md#class.mfct
 
1248
  [cstdint]: language.md#cstdint
1249
  [dcl.array]: dcl.md#dcl.array
1250
  [dcl.attr]: dcl.md#dcl.attr
1251
  [dcl.constexpr]: dcl.md#dcl.constexpr
1252
  [dcl.fct.default]: dcl.md#dcl.fct.default
 
1253
  [dcl.init]: dcl.md#dcl.init
1254
+ [dcl.init.list]: dcl.md#dcl.init.list
1255
+ [dcl.inline]: dcl.md#dcl.inline
1256
  [dcl.link]: dcl.md#dcl.link
1257
  [definitions]: #definitions
 
1258
  [depr]: future.md#depr
1259
  [depr.c.headers]: future.md#depr.c.headers
1260
+ [depr.cstdalign.syn]: future.md#depr.cstdalign.syn
1261
+ [depr.cstdbool.syn]: future.md#depr.cstdbool.syn
1262
  [derivation]: #derivation
1263
  [derived.classes]: #derived.classes
1264
  [description]: #description
 
1265
  [diagnostics]: diagnostics.md#diagnostics
1266
  [enumerated.types]: #enumerated.types
 
1267
  [except]: except.md#except
1268
+ [expos.only.types]: #expos.only.types
1269
+ [expr.cond]: expr.md#expr.cond
1270
+ [expr.const]: expr.md#expr.const
1271
  [expr.delete]: expr.md#expr.delete
1272
  [expr.eq]: expr.md#expr.eq
1273
  [expr.new]: expr.md#expr.new
1274
  [expr.rel]: expr.md#expr.rel
1275
  [extern.names]: #extern.names
1276
  [extern.types]: #extern.types
1277
  [function.objects]: utilities.md#function.objects
1278
  [functions.within.classes]: #functions.within.classes
1279
  [global.functions]: #global.functions
 
1280
  [handler.functions]: #handler.functions
 
1281
  [hash.requirements]: #hash.requirements
1282
  [headers]: #headers
1283
  [input.output]: input.md#input.output
1284
  [intro.compliance]: intro.md#intro.compliance
1285
  [intro.defs]: intro.md#intro.defs
1286
  [intro.multithread]: intro.md#intro.multithread
1287
  [intro.refs]: intro.md#intro.refs
1288
  [iterator.requirements]: iterators.md#iterator.requirements
1289
+ [iterator.requirements.general]: iterators.md#iterator.requirements.general
1290
  [iterators]: iterators.md#iterators
1291
  [language.support]: language.md#language.support
1292
  [lex]: lex.md#lex
 
1293
  [lex.phases]: lex.md#lex.phases
1294
  [lib.types.movedfrom]: #lib.types.movedfrom
1295
  [library]: #library
1296
  [library.c]: #library.c
1297
  [library.general]: #library.general
 
1301
  [member.functions]: #member.functions
1302
  [meta]: utilities.md#meta
1303
  [multibyte.strings]: #multibyte.strings
1304
  [namespace.constraints]: #namespace.constraints
1305
  [namespace.def]: dcl.md#namespace.def
1306
+ [namespace.future]: #namespace.future
1307
  [namespace.posix]: #namespace.posix
1308
  [namespace.std]: #namespace.std
1309
  [namespace.udecl]: dcl.md#namespace.udecl
1310
  [new.delete]: language.md#new.delete
1311
  [new.handler]: language.md#new.handler
 
1312
  [nullablepointer.requirements]: #nullablepointer.requirements
1313
  [numeric.requirements]: numerics.md#numeric.requirements
1314
  [numerics]: numerics.md#numerics
1315
  [objects.within.classes]: #objects.within.classes
1316
  [organization]: #organization
1317
  [ostream.iterator.ops]: iterators.md#ostream.iterator.ops
1318
+ [over.literal]: over.md#over.literal
1319
  [over.match]: over.md#over.match
1320
  [over.oper]: over.md#over.oper
1321
  [protection.within.classes]: #protection.within.classes
1322
+ [random.access.iterators]: iterators.md#random.access.iterators
1323
  [re]: re.md#re
1324
  [reentrancy]: #reentrancy
1325
  [replacement.functions]: #replacement.functions
1326
  [requirements]: #requirements
1327
  [res.on.arguments]: #res.on.arguments
 
1352
  [support.start.term]: language.md#support.start.term
1353
  [support.types]: language.md#support.types
1354
  [swappable.requirements]: #swappable.requirements
1355
  [syserr]: diagnostics.md#syserr
1356
  [syserr.errcode.overview]: diagnostics.md#syserr.errcode.overview
1357
+ [tab:c.annex.k.names]: #tab:c.annex.k.names
1358
+ [tab:copyassignable]: #tab:copyassignable
1359
  [tab:cpp.c.headers]: #tab:cpp.c.headers
1360
  [tab:cpp.headers.freestanding]: #tab:cpp.headers.freestanding
1361
  [tab:cpp.library.headers]: #tab:cpp.library.headers
1362
  [tab:desc.var.def]: #tab:desc.var.def
1363
+ [tab:destructible]: #tab:destructible
1364
+ [tab:equalitycomparable]: #tab:equalitycomparable
1365
+ [tab:hash]: #tab:hash
1366
  [tab:identifiers.special]: lex.md#tab:identifiers.special
1367
  [tab:library.categories]: #tab:library.categories
1368
+ [tab:moveassignable]: #tab:moveassignable
1369
+ [tab:nullablepointer]: #tab:nullablepointer
1370
  [tab:utilities.allocator.requirements]: #tab:utilities.allocator.requirements
1371
  [temp.deduct.call]: temp.md#temp.deduct.call
1372
  [template.bitset]: utilities.md#template.bitset
1373
  [terminate.handler]: language.md#terminate.handler
1374
  [thread]: thread.md#thread
1375
  [type.descriptions]: #type.descriptions
1376
  [type.descriptions.general]: #type.descriptions.general
 
1377
  [using]: #using
1378
  [using.headers]: #using.headers
1379
  [using.linkage]: #using.linkage
1380
  [using.overview]: #using.overview
1381
  [usrlit.suffix]: #usrlit.suffix
1382
  [utilities]: utilities.md#utilities
1383
  [utility]: utilities.md#utility
1384
  [utility.arg.requirements]: #utility.arg.requirements
1385
  [utility.requirements]: #utility.requirements
1386
  [value.error.codes]: #value.error.codes
1387
+ [zombie.names]: #zombie.names
1388
 
1389
+ [^1]: To save space, items that do not apply to a Clause are omitted.
 
 
1390
  For example, if a Clause does not specify any requirements, there
1391
  will be no “Requirements” subclause.
1392
 
1393
+ [^2]: Although in some cases the code given is unambiguously the optimum
1394
  implementation.
1395
 
1396
+ [^3]: To save space, items that do not apply to a class are omitted. For
1397
  example, if a class does not specify any comparison functions, there
1398
  will be no “Comparison functions” subclause.
1399
 
1400
+ [^4]: To save space, items that do not apply to a function are omitted.
1401
  For example, if a function does not specify any further
1402
+ preconditions, there will be no *Requires:* paragraph.
1403
 
1404
+ [^5]: This simplifies the presentation of complexity requirements in
1405
  some cases.
1406
 
1407
+ [^6]: Examples from  [[utility.requirements]] include:
1408
  `EqualityComparable`, `LessThanComparable`, `CopyConstructible`.
1409
  Examples from  [[iterator.requirements]] include: `InputIterator`,
1410
+ `ForwardIterator`.
1411
 
1412
+ [^7]: Such as an integer type, with constant integer values (
1413
  [[basic.fundamental]]).
1414
 
1415
+ [^8]: declared in `<clocale>` ([[c.locales]]).
 
1416
 
1417
+ [^9]: Many of the objects manipulated by function signatures declared in
1418
+ `<cstring>` ([[c.strings]]) are character sequences or NTBSs. The
1419
+ size of some of these character sequences is limited by a length
 
 
1420
  value, maintained separately from the character sequence.
1421
 
1422
+ [^10]: A string literal, such as `"abc"`, is a static NTBS.
1423
 
1424
+ [^11]: An NTBSthat contains characters only from the basic execution
1425
  character set is also an NTMBS. Each multibyte character then
1426
  consists of a single byte.
1427
 
1428
+ [^12]: The C standard library headers (Annex  [[depr.c.headers]]) also
1429
  define names within the global namespace, while the C++headers for C
1430
  library facilities ([[headers]]) may also define names within the
1431
  global namespace.
1432
 
1433
+ [^13]: This gives implementers freedom to use inline namespaces to
1434
  support multiple configurations of the library.
1435
 
1436
+ [^14]: A header is not necessarily a source file, nor are the sequences
1437
  delimited by `<` and `>` in header names necessarily valid source
1438
  file names ([[cpp.include]]).
1439
 
1440
+ [^15]: It is intentional that there is no C++header for any of these C
1441
+ headers: `<stdatomic.h>`, `<stdnoreturn.h>`, `<threads.h>`.
1442
+
1443
+ [^16]: This disallows the practice, allowed in C, of providing a masking
1444
  macro in addition to the function prototype. The only way to achieve
1445
  equivalent inline behavior in C++is to provide a definition as an
1446
  extern inline function.
1447
 
1448
+ [^17]: In particular, including the standard header `<iso646.h>` or
1449
  `<ciso646>` has no effect.
1450
 
1451
+ [^18]: The `".h"` headers dump all their names into the global
1452
  namespace, whereas the newer forms keep their names in namespace
1453
  `std`. Therefore, the newer forms are the preferred forms for all
1454
  uses except for C++programs which are intended to be strictly
1455
  compatible with C.
1456
 
1457
+ [^19]: This is the same as the C standard library.
1458
 
1459
+ [^20]: The only reliable way to declare an object or function signature
1460
+ from the C standard library is by including the header that declares
1461
  it, notwithstanding the latitude granted in 7.1.4 of the C Standard.
1462
 
1463
+ [^21]: Any library code that instantiates other library templates must
1464
  be prepared to work adequately with any user-supplied specialization
1465
+ that meets the minimum requirements of this International Standard.
1466
 
1467
+ [^22]: The list of such reserved names includes `errno`, declared or
1468
  defined in `<cerrno>`.
1469
 
1470
+ [^23]: The list of such reserved function signatures with external
1471
  linkage includes `setjmp(jmp_buf)`, declared or defined in
1472
  `<csetjmp>`, and `va_end(va_list)`, declared or defined in
1473
  `<cstdarg>`.
1474
 
1475
+ [^24]: The function signatures declared in `<cuchar>`, `<cwchar>`, and
1476
  `<cwctype>` are always reserved, notwithstanding the restrictions
1477
  imposed in subclause 4.5.1 of Amendment 1 to the C Standard for
1478
  these headers.
1479
 
1480
+ [^25]: These types are `clock_t`, `div_t`, `FILE`, `fpos_t`, `lconv`,
1481
  `ldiv_t`, `mbstate_t`, `ptrdiff_t`, `sig_atomic_t`, `size_t`,
1482
  `time_t`, `tm`, `va_list`, `wctrans_t`, `wctype_t`, and `wint_t`.
1483
 
1484
+ [^26]: A valid C++program always calls the expected library non-member
1485
+ function. An implementation may also define additional non-member
1486
+ functions that would otherwise not be called by a valid C++program.
 
1487
 
1488
+ [^27]: There is an implicit exception to this rule for types that are
 
 
 
 
 
 
 
 
1489
  described as synonyms for basic integral types, such as `size_t` (
1490
  [[support.types]]) and `streamoff` ([[stream.types]]).
1491
 
1492
+ [^28]: That is, the C library functions can all be treated as if they
1493
  are marked `noexcept`. This allows implementations to make
1494
  performance optimizations based on the absence of exceptions at
1495
  runtime.
1496
 
1497
+ [^29]: The functions `qsort()` and `bsearch()` ([[alg.c.library]]) meet
1498
  this condition.
1499
 
1500
+ [^30]: In particular, they can report a failure to allocate storage by
1501
  throwing an exception of type `bad_alloc`, or a class derived from
1502
+ `bad_alloc` ([[bad.alloc]]).