From Jason Turner

[library]

Large diff (139.5 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp0njm40_m/{from.md → to.md} +1031 -699
tmp/tmp0njm40_m/{from.md → to.md} RENAMED
@@ -4,226 +4,354 @@
4
 
5
  This Clause describes the contents of the *C++ standard library*, how a
6
  well-formed C++ program makes use of the library, and how a conforming
7
  implementation may provide the entities in the library.
8
 
9
- The following subclauses describe the definitions ([[definitions]]),
10
- method of description ([[description]]), and organization (
11
- [[organization]]) of the library. Clause  [[requirements]], Clauses 
12
- [[language.support]] through  [[thread]], and Annex  [[depr]] specify
13
- the contents of the library, as well as library requirements and
14
- constraints on both well-formed C++programs and conforming
15
- implementations.
16
 
17
  Detailed specifications for each of the components in the library are in
18
- Clauses  [[language.support]]– [[thread]], as shown in Table 
19
- [[tab:library.categories]].
20
-
21
- The language support library (Clause  [[language.support]]) provides
22
- components that are required by certain parts of the C++language, such
23
- as memory allocation ([[expr.new]], [[expr.delete]]) and exception
24
- processing (Clause  [[except]]).
25
-
26
- The diagnostics library (Clause  [[diagnostics]]) provides a consistent
27
- framework for reporting errors in a C++program, including predefined
28
- exception classes.
29
-
30
- The general utilities library (Clause  [[utilities]]) includes
31
- components used by other library elements, such as a predefined storage
32
- allocator for dynamic storage management ([[basic.stc.dynamic]]), and
33
- components used as infrastructure in C++programs, such as tuples,
34
- function wrappers, and time facilities.
35
-
36
- The strings library (Clause  [[strings]]) provides support for
37
- manipulating text represented as sequences of type `char`, sequences of
38
- type `char16_t`, sequences of type `char32_t`, sequences of type
39
- `wchar_t`, and sequences of any other character-like type.
40
-
41
- The localization library (Clause  [[localization]]) provides extended
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
42
  internationalization support for text processing.
43
 
44
- The containers (Clause  [[containers]]), iterators (Clause 
45
- [[iterators]]), and algorithms (Clause  [[algorithms]]) libraries
46
- provide a C++program with access to a subset of the most widely used
47
- algorithms and data structures.
48
 
49
- The numerics library (Clause  [[numerics]]) provides numeric algorithms
50
- and complex number components that extend support for numeric
51
- processing. The `valarray` component provides support for *n*-at-a-time
52
- processing, potentially implemented as parallel operations on platforms
53
- that support such processing. The random number component provides
54
- facilities for generating pseudo-random numbers.
55
 
56
- The input/output library (Clause  [[input.output]]) provides the
57
- `iostream` components that are the primary mechanism for C++program
58
- input and output. They can be used with other elements of the library,
59
  particularly strings, locales, and iterators.
60
 
61
- The regular expressions library (Clause  [[re]]) provides regular
62
- expression matching and searching.
63
 
64
- The atomic operations library (Clause  [[atomics]]) allows more
65
- fine-grained concurrent access to shared data than is possible with
66
- locks.
67
 
68
- The thread support library (Clause  [[thread]]) provides components to
69
- create and manage threads, including mutual exclusion and interthread
70
  communication.
71
 
72
  ## The C standard library <a id="library.c">[[library.c]]</a>
73
 
74
  The C++ standard library also makes available the facilities of the C
75
  standard library, suitably adjusted to ensure static type safety.
76
 
77
  The descriptions of many library functions rely on the C standard
78
  library for the semantics of those functions. In some cases, the
79
- signatures specified in this International Standard may be different
80
- from the signatures in the C standard library, and additional overloads
81
- may be declared in this International Standard, but the behavior and the
82
- preconditions (including any preconditions implied by the use of an ISO
83
- C `restrict` qualifier) are the same unless otherwise stated.
84
 
85
  ## Definitions <a id="definitions">[[definitions]]</a>
86
 
87
- [*Note 1*: Clause [[intro.defs]] defines additional terms used
88
- elsewhere in this International Standard. — *end note*]
89
 
90
- a stream (described in Clause  [[input.output]]) that can seek to any
91
- integral position within the length of the stream
92
 
93
- [*Note 2*: Every arbitrary-positional stream is also a repositional
94
- stream. *end note*]
95
 
96
- \defncontext{Clauses~ [[strings]], [[localization]], [[input.output]], and~ [[re]]}
97
- any object which, when treated sequentially, can represent text
98
 
99
- [*Note 3*: The term does not mean only `char`, `char16_t`, `char32_t`,
100
- and `wchar_t` objects, but any value that can be represented by a type
101
- that provides the definitions specified in these Clauses. — *end note*]
102
 
103
- a class or a type used to represent a *character*
 
104
 
105
- [*Note 4*: It is used for one of the template parameters of the string,
106
- iostream, and regular expression class templates. A character container
107
- type is a POD ([[basic.types]]) type. *end note*]
 
108
 
109
- an operator function ([[over.oper]]) for any of the equality (
110
- [[expr.eq]]) or relational ([[expr.rel]]) operators
111
 
112
- a group of library entities directly related as members, parameters, or
 
 
 
 
 
 
 
 
 
 
 
 
 
 
113
  return types
114
 
115
- [*Note 5*: For example, the class template `basic_string` and the
116
- non-member function templates that operate on strings are referred to as
117
- the *string component*. — *end note*]
118
 
119
- an expression whose evaluation as subexpression of a
120
- *conditional-expression* `CE` ([[expr.cond]]) would not prevent `CE`
121
- from being a core constant expression ([[expr.const]])
122
 
123
- one or more threads are unable to continue execution because each is
124
- blocked waiting for one or more of the others to satisfy some condition
 
125
 
126
- any specific behavior provided by the implementation, within the scope
127
- of the *required behavior*
128
 
129
- a description of *replacement function* and *handler function* semantics
 
 
130
 
131
- a direct-initialization ([[dcl.init]]) that is not
132
- list-initialization ([[dcl.init.list]])
133
 
134
- a *non-reserved function* whose definition may be provided by a
135
- C++program
136
 
137
- [*Note 6*: A C++program may designate a handler function at various
138
- points in its execution by supplying a pointer to the function when
139
- calling any of the library functions that install handler functions
140
- (Clause  [[language.support]]). — *end note*]
141
 
142
- templates, defined in Clause  [[input.output]], that take two template
143
- arguments
144
 
145
- [*Note 7*: The arguments are named `charT` and `traits`. The argument
146
- `charT` is a character container class, and the argument `traits` is a
147
- class which defines additional characteristics and functions of the
148
- character type represented by `charT` necessary to implement the
149
- iostream class templates. — *end note*]
150
 
151
- a class member function ([[class.mfct]]) other than a constructor,
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
152
  assignment operator, or destructor that alters the state of an object of
153
  the class
154
 
 
 
155
  assignment of an rvalue of some object type to a modifiable lvalue of
156
  the same type
157
 
 
 
158
  direct-initialization of an object of some type with an rvalue of the
159
  same type
160
 
161
- a sequence of values that have *character type* that precede the
162
- terminating null character type value `charT()`
163
 
164
- a class member function ([[class.mfct]]) that accesses the state of an
 
 
 
 
 
165
  object of the class but does not alter that state
166
 
167
- [*Note 8*: Observer functions are specified as `const` member
168
- functions ([[class.this]]). — *end note*]
169
 
170
- an object type, a function type that does not have cv-qualifiers or a
171
- *ref-qualifier*, or a reference type
172
 
173
- [*Note 9*: The term describes a type to which a reference can be
174
- created, including reference types. *end note*]
175
 
176
- a *non-reserved function* whose definition is provided by a C++program
177
 
178
- [*Note 10*: Only one definition for such a function is in effect for
179
- the duration of the program’s execution, as the result of creating the
180
- program ([[lex.phases]]) and resolving the definitions of all
181
- translation units ([[basic.link]]). *end note*]
182
 
183
- a stream (described in Clause  [[input.output]]) that can seek to a
184
- position that was previously encountered
 
185
 
186
- a description of *replacement function* and *handler function* semantics
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
187
  applicable to both the behavior provided by the implementation and the
188
  behavior of any such function definition in the program
189
 
190
- [*Note 11*: If such a function defined in a C++program fails to meet
191
- the required behavior when it executes, the behavior is undefined.
192
- — *end note*]
193
 
194
- a function, specified as part of the C++standard library, that must be
195
- defined by the implementation
196
 
197
- [*Note 12*: If a C++program provides a definition for any reserved
198
- function, the results are undefined. — *end note*]
199
 
200
- an algorithm that preserves, as appropriate to the particular algorithm,
 
 
 
 
 
201
  the order of elements
202
 
203
- [*Note 13*: Requirements for stable algorithms are given in 
204
  [[algorithm.stable]]. — *end note*]
205
 
206
- a class that encapsulates a set of types and functions necessary for
207
- class templates and function templates to manipulate objects of types
208
- for which they are instantiated
209
 
210
- a value of an object that is not specified except that the object’s
 
 
 
 
 
 
211
  invariants are met and operations on the object behave as specified for
212
  its type
213
 
214
  [*Example 1*: If an object `x` of type `std::vector<int>` is in a valid
215
  but unspecified state, `x.empty()` can be called unconditionally, and
216
  `x.front()` can be called only if `x.empty()` returns
217
  `false`. — *end example*]
218
 
219
- ## Method of description (Informative) <a id="description">[[description]]</a>
220
 
221
- This subclause describes the conventions used to specify the C++standard
222
- library. [[structure]] describes the structure of the normative Clauses 
223
- [[language.support]] through  [[thread]] and Annex  [[depr]].
224
- [[conventions]] describes other editorial conventions.
225
 
226
  ### Structure of each clause <a id="structure">[[structure]]</a>
227
 
228
  #### Elements <a id="structure.elements">[[structure.elements]]</a>
229
 
@@ -239,59 +367,82 @@ Each library clause contains the following elements, as applicable:[^1]
239
  The Summary provides a synopsis of the category, and introduces the
240
  first-level subclauses. Each subclause also provides a summary, listing
241
  the headers specified in the subclause and the library entities provided
242
  in each header.
243
 
244
- Paragraphs labeled “Note(s):” or “Example(s):” are informative, other
245
- paragraphs are normative.
246
-
247
  The contents of the summary and the detailed specifications include:
248
 
249
  - macros
250
  - values
251
- - types
252
  - classes and class templates
253
  - functions and function templates
254
- - objects
 
255
 
256
  #### Requirements <a id="structure.requirements">[[structure.requirements]]</a>
257
 
258
- Requirements describe constraints that shall be met by a C++program that
259
- extends the standard library. Such extensions are generally one of the
260
- following:
261
 
262
  - Template arguments
263
  - Derived classes
264
  - Containers, iterators, and algorithms that meet an interface
265
- convention
266
 
267
  The string and iostream components use an explicit representation of
268
  operations required of template arguments. They use a class template
269
  `char_traits` to define these constraints.
270
 
271
  Interface convention requirements are stated as generally as possible.
272
- Instead of stating “class X has to define a member function
273
  `operator++()`”, the interface requires “for any object `x` of class
274
  `X`, `++x` is defined”. That is, whether the operator is a member is
275
  unspecified.
276
 
277
  Requirements are stated in terms of well-defined expressions that define
278
- valid terms of the types that satisfy the requirements. For every set of
279
- well-defined expression requirements there is a table that specifies an
280
- initial set of the valid expressions and their semantics. Any generic
281
- algorithm (Clause  [[algorithms]]) that uses the well-defined expression
282
- requirements is described in terms of the valid expressions for its
283
- template type parameters.
 
 
 
 
 
 
 
 
 
 
284
 
285
  Template argument requirements are sometimes referenced by name. See 
286
  [[type.descriptions]].
287
 
288
  In some cases the semantic requirements are presented as C++ code. Such
289
  code is intended as a specification of equivalence of a construct to
290
  another construct, not necessarily as the way the construct must be
291
  implemented.[^2]
292
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
293
  #### Detailed specifications <a id="structure.specifications">[[structure.specifications]]</a>
294
 
295
  The detailed specifications each contain the following elements:
296
 
297
  - name and brief description
@@ -311,89 +462,138 @@ appropriate):[^3]
311
  - operators and other non-member functions
312
 
313
  Descriptions of function semantics contain the following elements (as
314
  appropriate):[^4]
315
 
316
- - *Requires:* the preconditions for calling the function
317
- - *Effects:* the actions performed by the function
318
- - *Synchronization:* the synchronization operations (
319
- [[intro.multithread]]) applicable to the function
320
- - *Postconditions:* the observable results established by the function
321
- - *Returns:* a description of the value(s) returned by the function
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
322
  - *Throws:* any exceptions thrown by the function, and the conditions
323
- that would cause the exception
324
- - *Complexity:* the time and/or space complexity of the function
325
- - *Remarks:* additional semantic constraints on the function
326
  - *Error conditions:* the error conditions for error codes reported by
327
- the function
328
 
329
- Whenever the *Effects:* element specifies that the semantics of some
330
  function `F` are *Equivalent to* some code sequence, then the various
331
- elements are interpreted as follows. If `F`’s semantics specifies a
332
- *Requires:* element, then that requirement is logically imposed prior to
333
- the *equivalent-to* semantics. Next, the semantics of the code sequence
334
- are determined by the *Requires:* , *Effects:* , *Synchronization:* ,
335
- *Postconditions:* , *Returns:* , *Throws:* , *Complexity:* , *Remarks:*
336
- , and *Error conditions:* specified for the function invocations
337
- contained in the code sequence. The value returned from `F` is specified
338
- by `F`’s *Returns:* element, or if `F` has no *Returns:* element, a
339
- non-`void` return from `F` is specified by the `return` statements in
340
- the code sequence. If `F`’s semantics contains a *Throws:* ,
341
- *Postconditions:* , or *Complexity:* element, then that supersedes any
 
342
  occurrences of that element in the code sequence.
343
 
344
- For non-reserved replacement and handler functions, Clause 
345
- [[language.support]] specifies two behaviors for the functions in
346
- question: their required and default behavior. The *default behavior*
347
- describes a function definition provided by the implementation. The
348
- *required behavior* describes the semantics of a function definition
349
- provided by either the implementation or a C++program. Where no
350
- distinction is explicitly made in the description, the behavior
351
- described is the required behavior.
352
 
353
  If the formulation of a complexity requirement calls for a negative
354
  number of operations, the actual requirement is zero operations.[^5]
355
 
356
  Complexity requirements specified in the library clauses are upper
357
  bounds, and implementations that provide better complexity guarantees
358
- satisfy the requirements.
359
 
360
  Error conditions specify conditions where a function may fail. The
361
  conditions are listed, together with a suitable explanation, as the
362
- `enum class errc` constants ([[syserr]]).
363
 
364
  #### C library <a id="structure.see.also">[[structure.see.also]]</a>
365
 
366
- Paragraphs labeled “ contain cross-references to the relevant portions
367
- of this International Standard and the ISO C standard.
 
368
 
369
  ### Other conventions <a id="conventions">[[conventions]]</a>
370
 
371
  This subclause describes several editorial conventions used to describe
372
  the contents of the C++ standard library. These conventions are for
373
- describing implementation-defined types ([[type.descriptions]]), and
374
- member functions ([[functions.within.classes]]).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
375
 
376
  #### Type descriptions <a id="type.descriptions">[[type.descriptions]]</a>
377
 
378
  ##### General <a id="type.descriptions.general">[[type.descriptions.general]]</a>
379
 
380
  The Requirements subclauses may describe names that are used to specify
381
  constraints on template arguments.[^6] These names are used in library
382
- Clauses to describe the types that may be supplied as arguments by a
383
- C++program when instantiating template components from the library.
384
 
385
- Certain types defined in Clause  [[input.output]] are used to describe
386
  implementation-defined types. They are based on other types, but with
387
  added constraints.
388
 
389
  ##### Exposition-only types <a id="expos.only.types">[[expos.only.types]]</a>
390
 
391
- Several types defined in Clauses  [[language.support]] through 
392
- [[thread]] and Annex  [[depr]] that are used as function parameter or
393
- return types are defined for the purpose of exposition only in order to
394
- capture their language linkage. The declarations of such types are
395
  followed by a comment ending in *exposition only*.
396
 
397
  [*Example 1*:
398
 
399
  ``` cpp
@@ -407,73 +607,73 @@ function that takes a callback parameter with C language linkage.
407
 
408
  — *end example*]
409
 
410
  ##### Enumerated types <a id="enumerated.types">[[enumerated.types]]</a>
411
 
412
- Several types defined in Clause  [[input.output]] are *enumerated
413
- types*. Each enumerated type may be implemented as an enumeration or as
414
- a synonym for an enumeration.[^7]
415
 
416
  The enumerated type `enumerated` can be written:
417
 
418
  ``` cpp
419
- enum enumerated { V₀, V₁, V₂, V₃, ..... };
420
 
421
  inline const enumerated C₀(V₀);
422
  inline const enumerated C₁(V₁);
423
  inline const enumerated C₂(V₂);
424
  inline const enumerated C₃(V₃);
425
- .....
426
  ```
427
 
428
  Here, the names `C₀`, `C₁`, etc. represent *enumerated elements* for
429
  this particular enumerated type. All such elements have distinct values.
430
 
431
  ##### Bitmask types <a id="bitmask.types">[[bitmask.types]]</a>
432
 
433
- Several types defined in Clauses  [[language.support]] through 
434
- [[thread]] and Annex  [[depr]] are *bitmask types*. Each bitmask type
435
- can be implemented as an enumerated type that overloads certain
436
- operators, as an integer type, or as a `bitset` ([[template.bitset]]).
437
 
438
- The bitmask type *bitmask* can be written:
439
 
440
  ``` cpp
441
  // For exposition only.
442
  // int_type is an integral type capable of representing all values of the bitmask type.
443
  enum bitmask : int_type {
444
- V₀ = 1 << 0, V₁ = 1 << 1, V₂ = 1 << 2, V₃ = 1 << 3, .....
445
  };
446
 
447
  inline constexpr bitmask C₀(V₀{});
448
  inline constexpr bitmask C₁(V₁{});
449
  inline constexpr bitmask C₂(V₂{});
450
  inline constexpr bitmask C₃(V₃{});
451
- .....
452
 
453
- constexpr bitmask{} operator&(bitmask{} X, bitmask{} Y) {
454
- return static_cast<bitmask{}>(
455
  static_cast<int_type>(X) & static_cast<int_type>(Y));
456
  }
457
- constexpr bitmask{} operator|(bitmask{} X, bitmask{} Y) {
458
- return static_cast<bitmask{}>(
459
  static_cast<int_type>(X) | static_cast<int_type>(Y));
460
  }
461
- constexpr bitmask{} operator^(bitmask{} X, bitmask{} Y){
462
- return static_cast<bitmask{}>(
463
  static_cast<int_type>(X) ^ static_cast<int_type>(Y));
464
  }
465
- constexpr bitmask{} operator~(bitmask{} X){
466
- return static_cast<bitmask{}>(~static_cast<int_type>(X));
467
  }
468
- bitmask{}& operator&=(bitmask{}& X, bitmask{} Y){
469
  X = X & Y; return X;
470
  }
471
- bitmask{}& operator|=(bitmask{}& X, bitmask{} Y) {
472
  X = X | Y; return X;
473
  }
474
- bitmask{}& operator^=(bitmask{}& X, bitmask{} Y) {
475
  X = X ^ Y; return X;
476
  }
477
  ```
478
 
479
  Here, the names `C₀`, `C₁`, etc. represent *bitmask elements* for this
@@ -500,73 +700,99 @@ sequences that follow a few uniform conventions:
500
  basic execution character set.
501
  - The *decimal-point character* is the (single-byte) character used by
502
  functions that convert between a (single-byte) character sequence and
503
  a value of one of the floating-point types. It is used in the
504
  character sequence to denote the beginning of a fractional part. It is
505
- represented in Clauses  [[language.support]] through  [[thread]] and
506
- Annex  [[depr]] by a period, `'.'`, which is also its value in the
507
- `"C"` locale, but may change during program execution by a call to
508
  `setlocale(int, const char*)`,[^8] or by a change to a `locale`
509
- object, as described in Clauses  [[locales]] and  [[input.output]].
510
- - A *character sequence* is an array object ([[dcl.array]]) `A` that
511
- can be declared as `T A[N]`, where `T` is any of the types `char`,
512
- `unsigned char`, or `signed char` ([[basic.fundamental]]), optionally
513
  qualified by any combination of `const` or `volatile`. The initial
514
  elements of the array have defined contents up to and including an
515
  element determined by some predicate. A character sequence can be
516
  designated by a pointer value `S` that points to its first element.
517
 
518
  ###### Byte strings <a id="byte.strings">[[byte.strings]]</a>
519
 
520
  A *null-terminated byte string*, or NTBS, is a character sequence whose
521
  highest-addressed element with defined content has the value zero (the
522
- *terminating null* character); no other element in the sequence has the
523
  value zero. [^9]
524
 
525
- The *length* of an NTBS is the number of elements that precede the
526
- terminating null character. An *empty* NTBS has a length of zero.
527
 
528
- The *value* of an NTBS is the sequence of values of the elements up to
529
  and including the terminating null character.
530
 
531
- A *static* NTBS is an NTBSwith static storage duration.[^10]
532
 
533
  ###### Multibyte strings <a id="multibyte.strings">[[multibyte.strings]]</a>
534
 
535
  A *null-terminated multibyte string*, or NTMBS, is an NTBS that
536
  constitutes a sequence of valid multibyte characters, beginning and
537
  ending in the initial shift state.[^11]
538
 
539
- A *static* NTMBS is an NTMBSwith static storage duration.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
540
 
541
  #### Functions within classes <a id="functions.within.classes">[[functions.within.classes]]</a>
542
 
543
- For the sake of exposition, Clauses  [[language.support]] through 
544
- [[thread]] and Annex  [[depr]] do not describe copy/move constructors,
545
- assignment operators, or (non-virtual) destructors with the same
546
- apparent semantics as those that can be generated by default (
547
- [[class.ctor]], [[class.dtor]], [[class.copy]]). It is unspecified
548
- whether the implementation provides explicit definitions for such member
549
- function signatures, or for virtual destructors that can be generated by
550
- default.
551
-
552
- For the sake of exposition, the library clauses sometimes annotate
553
- constructors with \EXPLICIT. Such a constructor is conditionally
554
- declared as either explicit or non-explicit ([[class.conv.ctor]]).
555
-
556
- [*Note 1*: This is typically implemented by declaring two such
557
- constructors, of which at most one participates in overload
558
- resolution. — *end note*]
559
 
560
  #### Private members <a id="objects.within.classes">[[objects.within.classes]]</a>
561
 
562
- Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]] do
563
- not specify the representation of classes, and intentionally omit
564
- specification of class members ([[class.mem]]). An implementation may
565
- define static or non-static class members, or both, as needed to
566
- implement the semantics of the member functions specified in Clauses 
567
- [[language.support]] through  [[thread]] and Annex  [[depr]].
568
 
569
  For the sake of exposition, some subclauses provide representative
570
  declarations, and semantic requirements, for private members of classes
571
  that meet the external specifications of the classes. The declarations
572
  for such members are followed by a comment that ends with *exposition
@@ -579,14 +805,13 @@ streambuf* sb; // exposition only
579
  An implementation may use any technique that provides equivalent
580
  observable behavior.
581
 
582
  ## Library-wide requirements <a id="requirements">[[requirements]]</a>
583
 
584
- This subclause specifies requirements that apply to the entire
585
- C++standard library. Clauses  [[language.support]] through  [[thread]]
586
- and Annex  [[depr]] specify the requirements of individual entities
587
- within the library.
588
 
589
  Requirements specified in terms of interactions between threads do not
590
  apply to programs having only a single thread of execution.
591
 
592
  Within this subclause, [[organization]] describes the library’s contents
@@ -596,103 +821,85 @@ constraints on types and functions used with the C++standard library,
596
  [[constraints]] describes constraints on well-formed C++ programs, and
597
  [[conforming]] describes constraints on conforming implementations.
598
 
599
  ### Library contents and organization <a id="organization">[[organization]]</a>
600
 
601
- [[contents]] describes the entities and macros defined in the
602
- C++standard library. [[headers]] lists the standard library headers and
603
  some constraints on those headers. [[compliance]] lists requirements for
604
  a freestanding implementation of the C++ standard library.
605
 
606
  #### Library contents <a id="contents">[[contents]]</a>
607
 
608
- The C++standard library provides definitions for the entities and macros
609
- described in the synopses of the C++standard library headers (
610
- [[headers]]).
611
 
612
  All library entities except `operator new` and `operator delete` are
613
  defined within the namespace `std` or namespaces nested within namespace
614
  `std`.[^12] It is unspecified whether names declared in a specific
615
  namespace are declared directly in that namespace or in an inline
616
  namespace inside that namespace.[^13]
617
 
618
  Whenever a name `x` defined in the standard library is mentioned, the
619
  name `x` is assumed to be fully qualified as `::std::x`, unless
620
- explicitly described otherwise. For example, if the *Effects:* section
621
  for library function `F` is described as calling library function `G`,
622
  the function `::std::G` is meant.
623
 
624
  #### Headers <a id="headers">[[headers]]</a>
625
 
626
  Each element of the C++ standard library is declared or defined (as
627
  appropriate) in a *header*.[^14]
628
 
629
  The C++ standard library provides the *C++ library headers*, shown in
630
- Table  [[tab:cpp.library.headers]].
631
-
632
- **Table: C++library headers** <a id="tab:cpp.library.headers">[tab:cpp.library.headers]</a>
633
-
634
- | | | | |
635
- | ---------------------- | -------------------- | -------------------- | ----------------- |
636
- | `<algorithm>` | `<future>` | `<numeric>` | `<strstream>` |
637
- | `<any>` | `<initializer_list>` | `<optional>` | `<system_error>` |
638
- | `<array>` | `<iomanip>` | `<ostream>` | `<thread>` |
639
- | `<atomic>` | `<ios>` | `<queue>` | `<tuple>` |
640
- | `<bitset>` | `<iosfwd>` | `<random>` | `<type_traits>` |
641
- | `<chrono>` | `<iostream>` | `<ratio>` | `<typeindex>` |
642
- | `<codecvt>` | `<istream>` | `<regex>` | `<typeinfo>` |
643
- | `<complex>` | `<iterator>` | `<scoped_allocator>` | `<unordered_map>` |
644
- | `<condition_variable>` | `<limits>` | `<set>` | `<unordered_set>` |
645
- | `<deque>` | `<list>` | `<shared_mutex>` | `<utility>` |
646
- | `<exception>` | `<locale>` | `<sstream>` | `<valarray>` |
647
- | `<execution>` | `<map>` | `<stack>` | `<variant>` |
648
- | `<filesystem>` | `<memory>` | `<stdexcept>` | `<vector>` |
649
- | `<forward_list>` | `<memory_resource>` | `<streambuf>` | |
650
- | `<fstream>` | `<mutex>` | `<string>` | |
651
- | `<functional>` | `<new>` | `<string_view>` | |
652
-
653
 
654
  The facilities of the C standard library are provided in the additional
655
- headers shown in Table  [[tab:cpp.c.headers]]. [^15]
656
 
657
- **Table: C++headers for C library facilities** <a id="tab:cpp.c.headers">[tab:cpp.c.headers]</a>
 
 
 
658
 
659
- | | | | | |
660
- | ------------ | ------------- | ------------- | ----------- | ----------- |
661
- | `<cassert>` | `<cinttypes>` | `<csignal>` | `<cstdio>` | `<cwchar>` |
662
- | `<ccomplex>` | `<ciso646>` | `<cstdalign>` | `<cstdlib>` | `<cwctype>` |
663
- | `<cctype>` | `<climits>` | `<cstdarg>` | `<cstring>` | |
664
- | `<cerrno>` | `<clocale>` | `<cstdbool>` | `<ctgmath>` | |
665
- | `<cfenv>` | `<cmath>` | `<cstddef>` | `<ctime>` | |
666
- | `<cfloat>` | `<csetjmp>` | `<cstdint>` | `<cuchar>` | |
667
 
 
668
 
669
- Except as noted in Clauses  [[library]] through  [[thread]] and Annex 
670
- [[depr]], the contents of each header `cname` is the same as that of the
671
- corresponding header `name.h` as specified in the C standard library
672
- (Clause  [[intro.refs]]). In the C++standard library, however, the
673
- declarations (except for names which are defined as macros in C) are
674
- within namespace scope ([[basic.scope.namespace]]) of the namespace
675
- `std`. It is unspecified whether these names (including any overloads
676
- added in Clauses  [[language.support]] through  [[thread]] and Annex 
677
- [[depr]]) are first declared within the global namespace scope and are
678
- then injected into namespace `std` by explicit *using-declaration*s (
679
- [[namespace.udecl]]).
 
 
 
 
 
 
680
 
681
  Names which are defined as macros in C shall be defined as macros in the
682
  C++ standard library, even if C grants license for implementation as
683
  functions.
684
 
685
- [*Note 1*: The names defined as macros in C include the following:
686
  `assert`, `offsetof`, `setjmp`, `va_arg`, `va_end`, and
687
  `va_start`. — *end note*]
688
 
689
  Names that are defined as functions in C shall be defined as functions
690
  in the C++ standard library.[^16]
691
 
692
- Identifiers that are keywords or operators in C++shall not be defined as
693
- macros in C++standard library headers.[^17]
694
 
695
  [[depr.c.headers]], C standard library headers, describes the effects of
696
  using the `name.h` (C header) form in a C++ program.[^18]
697
 
698
  Annex K of the C standard describes a large number of functions, with
@@ -703,115 +910,103 @@ service as the C library function with the unsuffixed name, but
703
  generally take an additional argument whose value is the size of the
704
  result array. If any C++ header is included, it is
705
  *implementation-defined* whether any of these names is declared in the
706
  global namespace. (None of them is declared in namespace `std`.)
707
 
708
- Table  [[tab:c.annex.k.names]] lists the Annex K names that may be
709
- declared in some header. These names are also subject to the
710
- restrictions of  [[macro.names]].
711
-
712
- **Table: C standard Annex K names** <a id="tab:c.annex.k.names">[tab:c.annex.k.names]</a>
713
-
714
- | | | | |
715
- | ---------------------- | -------------------------- | -------------- | ------------- |
716
- | `abort_handler_s` | `mbstowcs_s` | `strncat_s` | `vswscanf_s` |
717
- | `asctime_s` | `memcpy_s` | `strncpy_s` | `vwprintf_s` |
718
- | `bsearch_s` | `memmove_s` | `strtok_s` | `vwscanf_s` |
719
- | `constraint_handler_t` | `memset_s` | `swprintf_s` | `wcrtomb_s` |
720
- | `ctime_s` | `printf_s` | `swscanf_s` | `wcscat_s` |
721
- | `errno_t` | `qsort_s` | `tmpfile_s` | `wcscpy_s` |
722
- | `fopen_s` | `RSIZE_MAX` | `TMP_MAX_S` | `wcsncat_s` |
723
- | `fprintf_s` | `rsize_t` | `tmpnam_s` | `wcsncpy_s` |
724
- | `freopen_s` | `scanf_s` | `vfprintf_s` | `wcsnlen_s` |
725
- | `fscanf_s` | `set_constraint_handler_s` | `vfscanf_s` | `wcsrtombs_s` |
726
- | `fwprintf_s` | `snprintf_s` | `vfwprintf_s` | `wcstok_s` |
727
- | `fwscanf_s` | `snwprintf_s` | `vfwscanf_s` | `wcstombs_s` |
728
- | `getenv_s` | `sprintf_s` | `vprintf_s` | `wctomb_s` |
729
- | `gets_s` | `sscanf_s` | `vscanf_s` | `wmemcpy_s` |
730
- | `gmtime_s` | `strcat_s` | `vsnprintf_s` | `wmemmove_s` |
731
- | `ignore_handler_s` | `strcpy_s` | `vsnwprintf_s` | `wprintf_s` |
732
- | `L_tmpnam_s` | `strerror_s` | `vsprintf_s` | `wscanf_s` |
733
- | `localtime_s` | `strerrorlen_s` | `vsscanf_s` | |
734
- | `mbsrtowcs_s` | `strlen_s` | `vswprintf_s` | |
735
-
736
 
737
  #### Freestanding implementations <a id="compliance">[[compliance]]</a>
738
 
739
- Two kinds of implementations are defined: *hosted* and *freestanding* (
740
- [[intro.compliance]]). For a hosted implementation, this International
741
- Standard describes the set of available headers.
 
742
 
743
  A freestanding implementation has an *implementation-defined* set of
744
- headers. This set shall include at least the headers shown in Table 
745
- [[tab:cpp.headers.freestanding]].
746
 
747
- **Table: C++headers for freestanding implementations** <a id="tab:cpp.headers.freestanding">[tab:cpp.headers.freestanding]</a>
748
 
749
  | Subclause | | Header |
750
- | --------------------------------------------- | ------------------------- | --------------------------------- |
751
- | | | `<ciso646>` |
752
  | [[support.types]] | Types | `<cstddef>` |
753
- | [[support.limits]] | Implementation properties | `<cfloat>` `<limits>` `<climits>` |
754
  | [[cstdint]] | Integer types | `<cstdint>` |
755
  | [[support.start.term]] | Start and termination | `<cstdlib>` |
756
  | [[support.dynamic]] | Dynamic memory management | `<new>` |
757
  | [[support.rtti]] | Type identification | `<typeinfo>` |
 
758
  | [[support.exception]] | Exception handling | `<exception>` |
759
  | [[support.initlist]] | Initializer lists | `<initializer_list>` |
 
 
760
  | [[support.runtime]] | Other runtime support | `<cstdarg>` |
 
761
  | [[meta]] | Type traits | `<type_traits>` |
 
762
  | [[atomics]] | Atomics | `<atomic>` |
763
- | [[depr.cstdalign.syn]], [[depr.cstdbool.syn]] | Deprecated headers | `<cstdalign>` `<cstdbool>` |
764
 
765
 
766
  The supplied version of the header `<cstdlib>` shall declare at least
767
  the functions `abort`, `atexit`, `at_quick_exit`, `exit`, and
768
- `quick_exit` ([[support.start.term]]). The other headers listed in this
769
- table shall meet the same requirements as for a hosted implementation.
 
 
 
 
 
 
770
 
771
  ### Using the library <a id="using">[[using]]</a>
772
 
773
  #### Overview <a id="using.overview">[[using.overview]]</a>
774
 
775
- This section describes how a C++program gains access to the facilities
776
- of the C++standard library. [[using.headers]] describes effects during
777
- translation phase 4, while  [[using.linkage]] describes effects during
778
- phase 8 ([[lex.phases]]).
779
 
780
  #### Headers <a id="using.headers">[[using.headers]]</a>
781
 
782
  The entities in the C++ standard library are defined in headers, whose
783
  contents are made available to a translation unit when it contains the
784
- appropriate `#include` preprocessing directive ([[cpp.include]]).
 
785
 
786
- A translation unit may include library headers in any order (Clause 
787
- [[lex]]). Each may be included more than once, with no effect different
788
- from being included exactly once, except that the effect of including
789
- either `<cassert>` or `<assert.h>` depends each time on the lexically
790
- current definition of `NDEBUG`.[^19]
791
 
792
  A translation unit shall include a header only outside of any
793
- declaration or definition, and shall include the header lexically before
794
- the first reference in that translation unit to any of the entities
795
- declared in that header. No diagnostic is required.
 
 
796
 
797
  #### Linkage <a id="using.linkage">[[using.linkage]]</a>
798
 
799
- Entities in the C++standard library have external linkage (
800
- [[basic.link]]). Unless otherwise specified, objects and functions have
801
- the default `extern "C++"` linkage ([[dcl.link]]).
802
 
803
  Whether a name from the C standard library declared with external
804
  linkage has `extern "C"` or `extern "C++"` linkage is
805
  *implementation-defined*. It is recommended that an implementation use
806
  `extern "C++"` linkage for this purpose.[^20]
807
 
808
- Objects and functions defined in the library and required by a
809
- C++program are included in the program prior to program startup.
810
 
811
- See also replacement functions ([[replacement.functions]]), runtime
812
- changes ([[handler.functions]]).
813
 
814
  ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
815
 
816
  [[utility.arg.requirements]] describes requirements on types and
817
  expressions used to instantiate templates defined in the C++ standard
@@ -825,74 +1020,74 @@ allocators.
825
 
826
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
827
 
828
  The template definitions in the C++ standard library refer to various
829
  named requirements whose details are set out in Tables 
830
- [[tab:equalitycomparable]]– [[tab:destructible]]. In these tables, `T`
831
- is an object or reference type to be supplied by a C++program
832
- instantiating a template; `a`, `b`, and `c` are values of type (possibly
833
- `const`) `T`; `s` and `t` are modifiable lvalues of type `T`; `u`
834
- denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
835
  lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
836
 
837
  In general, a default constructor is not required. Certain container
838
  class member function signatures specify `T()` as a default argument.
839
- `T()` shall be a well-defined expression ([[dcl.init]]) if one of those
840
- signatures is called using the default argument ([[dcl.fct.default]]).
841
 
842
- **Table: `EqualityComparable` requirements** <a id="equalitycomparable">[equalitycomparable]</a>
843
 
844
  | Expression | Return type |
845
  | ---------- | ----------- |
846
  | `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`. |
847
 
848
- **Table: `LessThanComparable` requirements** <a id="lessthancomparable">[lessthancomparable]</a>
 
849
 
850
  | Expression | Return type | Requirement |
851
- | ---------- | --------------------- | --------------------------------------------------------- |
852
- | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation~([[alg.sorting]]) |
853
 
854
- **Table: `DefaultConstructible` requirements** <a id="defaultconstructible">[defaultconstructible]</a>
 
855
 
856
  | Expression | Post-condition |
857
  | -------------- | ------------------------------------------------------------------- |
858
  | `T t;` | object `t` is default-initialized |
859
  | `T u{};` | object `u` is value-initialized or aggregate-initialized |
860
  | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
861
 
 
862
  [*Note 1*: `rv` must still meet the requirements of the library
863
  component that is using it. The operations listed in those requirements
864
  must work as specified whether `rv` has been moved from or
865
  not. — *end note*]
866
 
867
- **Table: `CopyConstructible` requirements (in addition to `MoveConstructible`)** <a id="copyconstructible">[copyconstructible]</a>
868
 
869
  | Expression | Post-condition |
870
  | ---------- | --------------------------------------------------------- |
871
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
872
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
873
 
 
874
  [*Note 2*:  `rv` must still meet the requirements of the library
875
  component that is using it, whether or not `t` and `rv` refer to the
876
  same object. The operations listed in those requirements must work as
877
  specified whether `rv` has been moved from or not. — *end note*]
878
 
879
- **Table: `CopyAssignable` requirements (in addition to `MoveAssignable`)** <a id="copyassignable">[copyassignable]</a>
880
 
881
  | Expression | Return type | Return value | Post-condition |
882
  | ---------- | ----------- | ------------ | ------------------------------------------------------- |
883
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
884
 
885
 
886
- **Table: `Destructible` requirements** <a id="destructible">[destructible]</a>
 
887
 
888
- | Expression | Post-condition |
889
- | ---------- | --------------------------------------------------------------------- |
890
- | `u.~T()` | All resources owned by `u` are reclaimed, no exception is propagated. |
891
-
892
-
893
- #### `Swappable` requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
894
 
895
  This subclause provides definitions for swappable types and expressions.
896
  In these definitions, let `t` denote an expression of type `T`, and let
897
  `u` denote an expression of type `U`.
898
 
@@ -905,16 +1100,15 @@ An object `t` is *swappable with* an object `u` if and only if:
905
  and
906
  - the object referred to by `u` has the value originally held by `t`.
907
 
908
  The context in which `swap(t, u)` and `swap(u, t)` are evaluated shall
909
  ensure that a binary non-member function named “swap” is selected via
910
- overload resolution ([[over.match]]) on a candidate set that includes:
911
 
912
- - the two `swap` function templates defined in `<utility>` (
913
- [[utility]]) and
914
- - the lookup set produced by argument-dependent lookup (
915
- [[basic.lookup.argdep]]).
916
 
917
  [*Note 1*: If `T` and `U` are both fundamental types or arrays of
918
  fundamental types and the declarations from the header `<utility>` are
919
  in scope, the overall lookup set described above is equivalent to that
920
  of the qualified name lookup applied to the expression `std::swap(t, u)`
@@ -925,14 +1119,13 @@ swappable requirement includes the header `<utility>` to ensure an
925
  appropriate evaluation context. — *end note*]
926
 
927
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
928
  with any rvalue or lvalue, respectively, of type `T`.
929
 
930
- A type `X` satisfying any of the iterator requirements (
931
- [[iterator.requirements]]) satisfies the requirements of
932
- `ValueSwappable` if, for any dereferenceable object `x` of type `X`,
933
- `*x` is swappable.
934
 
935
  [*Example 1*:
936
 
937
  User code can ensure that the evaluation of `swap` calls is performed in
938
  an appropriate context under the various conditions as follows:
@@ -950,12 +1143,12 @@ void value_swap(T&& t, U&& u) {
950
 
951
  // Requires: lvalues of T shall be swappable.
952
  template<class T>
953
  void lv_swap(T& t1, T& t2) {
954
  using std::swap;
955
- swap(t1, t2); // OK: uses swappable conditions for
956
- } // lvalues of type T
957
 
958
  namespace N {
959
  struct A { int m; };
960
  struct Proxy { A* a; };
961
  Proxy proxy(A& a) { return Proxy{ &a }; }
@@ -978,103 +1171,102 @@ int main() {
978
  }
979
  ```
980
 
981
  — *end example*]
982
 
983
- #### `NullablePointer` requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
984
 
985
- A `NullablePointer` type is a pointer-like type that supports null
986
- values. A type `P` meets the requirements of `NullablePointer` if:
987
 
988
- - `P` satisfies the requirements of `EqualityComparable`,
989
- `DefaultConstructible`, `CopyConstructible`, `CopyAssignable`, and
990
- `Destructible`,
991
- - lvalues of type `P` are swappable ([[swappable.requirements]]),
992
- - the expressions shown in Table  [[tab:nullablepointer]] are valid and
993
- have the indicated semantics, and
994
- - `P` satisfies all the other requirements of this subclause.
995
 
996
  A value-initialized object of type `P` produces the null value of the
997
  type. The null value shall be equivalent only to itself. A
998
  default-initialized object of type `P` may have an indeterminate value.
999
 
1000
  [*Note 1*: Operations involving indeterminate values may cause
1001
  undefined behavior. — *end note*]
1002
 
1003
  An object `p` of type `P` can be contextually converted to `bool`
1004
- (Clause  [[conv]]). The effect shall be as if `p != nullptr` had been
1005
- evaluated in place of `p`.
1006
 
1007
- No operation which is part of the `NullablePointer` requirements shall
1008
- exit via an exception.
1009
 
1010
- In Table  [[tab:nullablepointer]], `u` denotes an identifier, `t`
1011
- denotes a non-`const` lvalue of type `P`, `a` and `b` denote values of
1012
- type (possibly `const`) `P`, and `np` denotes a value of type (possibly
1013
  `const`) `std::nullptr_t`.
1014
 
1015
- **Table: `NullablePointer` requirements** <a id="nullablepointer">[nullablepointer]</a>
1016
 
1017
- | | | |
1018
- | -------------- | ---------------------------------- | ---------------------------------- |
1019
- | `P u(np);`<br> | | Postconditions: `u == nullptr` |
1020
  | `P u = np;` | | |
1021
- | `P(np)` | | Postconditions: `P(np) == nullptr` |
1022
- | `t = np` | `P&` | Postconditions: `t == nullptr` |
1023
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
1024
  | `a == np` | contextually convertible to `bool` | `a == P()` |
1025
  | `np == a` | | |
1026
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
1027
  | `np != a` | | |
1028
 
1029
 
1030
- #### Hash requirements <a id="hash.requirements">[[hash.requirements]]</a>
1031
 
1032
- A type `H` meets the `Hash` requirements if:
1033
 
1034
- - it is a function object type ([[function.objects]]),
1035
- - it satisfies the requirements of `CopyConstructible` and
1036
- `Destructible` ([[utility.arg.requirements]]), and
1037
- - the expressions shown in Table  [[tab:hash]] are valid and have the
1038
  indicated semantics.
1039
 
1040
  Given `Key` is an argument type for function objects of type `H`, in
1041
- Table  [[tab:hash]] `h` is a value of type (possibly `const`) `H`, `u`
1042
- is an lvalue of type `Key`, and `k` is a value of a type convertible to
1043
  (possibly `const`) `Key`.
1044
 
1045
  [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
1046
  value for `k` yield the same result for a given execution of the
1047
  program. — *end note*]
1048
 
1049
- #### Allocator requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
1050
 
1051
  The library describes a standard set of requirements for *allocators*,
1052
  which are class-type objects that encapsulate the information about an
1053
  allocation model. This information includes the knowledge of pointer
1054
  types, the type of their difference, the type of the size of objects in
1055
  this allocation model, as well as the memory allocation and deallocation
1056
- primitives for it. All of the string types (Clause  [[strings]]),
1057
- containers (Clause  [[containers]]) (except array), string buffers and
1058
- string streams (Clause  [[input.output]]), and `match_results` (Clause 
1059
- [[re]]) are parameterized in terms of allocators.
1060
 
1061
- The class template `allocator_traits` ([[allocator.traits]]) supplies a
1062
- uniform interface to all allocator types. Table  [[tab:desc.var.def]]
1063
- describes the types manipulated through allocators. Table 
1064
- [[tab:utilities.allocator.requirements]] describes the requirements on
1065
- allocator types and thus on types used to instantiate
1066
- `allocator_traits`. A requirement is optional if the last column of
1067
- Table  [[tab:utilities.allocator.requirements]] specifies a default for
1068
- a given expression. Within the standard library `allocator_traits`
1069
- template, an optional requirement that is not supplied by an allocator
1070
- is replaced by the specified default expression. A user specialization
1071
- of `allocator_traits` may provide different defaults and may provide
1072
  defaults for different requirements than the primary template. Within
1073
- Tables  [[tab:desc.var.def]] and 
1074
- [[tab:utilities.allocator.requirements]], the use of `move` and
1075
- `forward` always refers to `std::move` and `std::forward`, respectively.
1076
 
1077
  [*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
1078
 
1079
  Note A: The member class template `rebind` in the table above is
1080
  effectively a typedef template.
@@ -1090,29 +1282,36 @@ and `Allocator` does not supply a `rebind` member template, the standard
1090
  `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
1091
  `Allocator::{}rebind<U>::other` by default. For allocator types that are
1092
  not template instantiations of the above form, no default is provided.
1093
 
1094
  Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
1095
- `X` shall satisfy the `CopyAssignable` requirements (Table 
1096
- [[tab:copyassignable]]) and the copy operation shall not throw
1097
  exceptions. If `X::propagate_on_container_move_assignment::value` is
1098
- `true`, `X` shall satisfy the `MoveAssignable` requirements (Table 
1099
- [[tab:moveassignable]]) and the move operation shall not throw
1100
  exceptions. If `X::propagate_on_container_swap::value` is `true`,
1101
- lvalues of type `X` shall be swappable ([[swappable.requirements]]) and
1102
  the `swap` operation shall not throw exceptions.
1103
 
1104
- An allocator type `X` shall satisfy the requirements of
1105
- `CopyConstructible` ([[utility.arg.requirements]]). The `X::pointer`,
1106
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
1107
- shall satisfy the requirements of `NullablePointer` (
1108
- [[nullablepointer.requirements]]). No constructor, comparison function,
1109
- copy operation, move operation, or swap operation on these pointer types
1110
  shall exit via an exception. `X::pointer` and `X::const_pointer` shall
1111
- also satisfy the requirements for a random access iterator (
1112
- [[random.access.iterators]]) and of a contiguous iterator (
1113
- [[iterator.requirements.general]]).
 
 
 
 
 
 
 
1114
 
1115
  Let `x1` and `x2` denote objects of (possibly different) types
1116
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
1117
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
1118
  pointer values, if and only if both `x1` and `x2` can be explicitly
@@ -1151,25 +1350,32 @@ An allocator may constrain the types on which it can be instantiated and
1151
  the arguments for which its `construct` or `destroy` members may be
1152
  called. If a type cannot be used with a particular allocator, the
1153
  allocator class or the call to `construct` or `destroy` may fail to
1154
  instantiate.
1155
 
 
 
 
 
 
 
 
 
1156
  [*Example 1*:
1157
 
1158
  The following is an allocator class template supporting the minimal
1159
- interface that satisfies the requirements of Table 
1160
- [[tab:utilities.allocator.requirements]]:
1161
 
1162
  ``` cpp
1163
  template<class Tp>
1164
  struct SimpleAllocator {
1165
  typedef Tp value_type;
1166
  SimpleAllocator(ctor args);
1167
 
1168
  template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
1169
 
1170
- Tp* allocate(std::size_t n);
1171
  void deallocate(Tp* p, std::size_t n);
1172
  };
1173
 
1174
  template<class T, class U>
1175
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
@@ -1177,52 +1383,51 @@ template <class T, class U>
1177
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
1178
  ```
1179
 
1180
  — *end example*]
1181
 
1182
- If the alignment associated with a specific over-aligned type is not
1183
- supported by an allocator, instantiation of the allocator for that type
1184
- may fail. The allocator also may silently ignore the requested
1185
- alignment.
1186
-
1187
- [*Note 3*: Additionally, the member function `allocate` for that type
1188
- may fail by throwing an object of type `bad_alloc`. — *end note*]
1189
-
1190
  ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
1191
 
1192
- If `X` is an allocator class for type `T`, `X` additionally satisfies
1193
- the allocator completeness requirements if, whether or not `T` is a
1194
- complete type:
1195
 
1196
  - `X` is a complete type, and
1197
- - all the member types of `allocator_traits<X>` ([[allocator.traits]])
1198
  other than `value_type` are complete types.
1199
 
1200
  ### Constraints on programs <a id="constraints">[[constraints]]</a>
1201
 
1202
  #### Overview <a id="constraints.overview">[[constraints.overview]]</a>
1203
 
1204
- This section describes restrictions on C++programs that use the
1205
- facilities of the C++standard library. The following subclauses specify
1206
- constraints on the program’s use of namespaces ([[namespace.std]]), its
1207
- use of various reserved names ([[reserved.names]]), its use of
1208
- headers ([[alt.headers]]), its use of standard library classes as base
1209
- classes ([[derived.classes]]), its definitions of replacement
1210
- functions ([[replacement.functions]]), and its installation of handler
1211
- functions during execution ([[handler.functions]]).
1212
 
1213
  #### Namespace use <a id="namespace.constraints">[[namespace.constraints]]</a>
1214
 
1215
  ##### Namespace `std` <a id="namespace.std">[[namespace.std]]</a>
1216
 
1217
- The behavior of a C++program is undefined if it adds declarations or
1218
- definitions to namespace `std` or to a namespace within namespace `std`
1219
- unless otherwise specified. A program may add a template specialization
1220
- for any standard library template to namespace `std` only if the
1221
- declaration depends on a user-defined type and the specialization meets
1222
- the standard library requirements for the original template and is not
1223
- explicitly prohibited.[^21]
 
 
 
 
 
 
 
1224
 
1225
  The behavior of a C++ program is undefined if it declares
1226
 
1227
  - an explicit specialization of any member function of a standard
1228
  library class template, or
@@ -1230,33 +1435,62 @@ The behavior of a C++program is undefined if it declares
1230
  standard library class or class template, or
1231
  - an explicit or partial specialization of any member class template of
1232
  a standard library class or class template, or
1233
  - a deduction guide for any standard library class template.
1234
 
1235
- A program may explicitly instantiate a template defined in the standard
1236
- library only if the declaration depends on the name of a user-defined
1237
- type and the instantiation meets the standard library requirements for
1238
- the original template.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1239
 
1240
  A translation unit shall not declare namespace `std` to be an inline
1241
- namespace ([[namespace.def]]).
1242
 
1243
  ##### Namespace `posix` <a id="namespace.posix">[[namespace.posix]]</a>
1244
 
1245
  The behavior of a C++ program is undefined if it adds declarations or
1246
  definitions to namespace `posix` or to a namespace within namespace
1247
  `posix` unless otherwise specified. The namespace `posix` is reserved
1248
  for use by ISO/IEC 9945 and other POSIX standards.
1249
 
1250
  ##### Namespaces for future standardization <a id="namespace.future">[[namespace.future]]</a>
1251
 
1252
- Top level namespaces with a name starting with `std` and followed by a
1253
- non-empty sequence of digits are reserved for future standardization.
1254
- The behavior of a C++program is undefined if it adds declarations or
1255
- definitions to such a namespace.
1256
 
1257
- [*Example 1*: The top level namespace `std2` is reserved for use by
1258
  future revisions of this International Standard. — *end example*]
1259
 
1260
  #### Reserved names <a id="reserved.names">[[reserved.names]]</a>
1261
 
1262
  The C++ standard library reserves the following kinds of names:
@@ -1273,101 +1507,133 @@ is undefined.
1273
 
1274
  In namespace `std`, the following names are reserved for previous
1275
  standardization:
1276
 
1277
  - `auto_ptr`,
 
1278
  - `binary_function`,
 
1279
  - `bind1st`,
1280
  - `bind2nd`,
1281
  - `binder1st`,
1282
  - `binder2nd`,
1283
  - `const_mem_fun1_ref_t`,
1284
  - `const_mem_fun1_t`,
1285
  - `const_mem_fun_ref_t`,
1286
  - `const_mem_fun_t`,
 
1287
  - `get_unexpected`,
 
 
 
1288
  - `mem_fun1_ref_t`,
1289
  - `mem_fun1_t`,
1290
  - `mem_fun_ref_t`,
1291
  - `mem_fun_ref`,
1292
  - `mem_fun_t`,
1293
  - `mem_fun`,
 
 
1294
  - `pointer_to_binary_function`,
1295
  - `pointer_to_unary_function`,
1296
  - `ptr_fun`,
1297
  - `random_shuffle`,
 
 
 
 
1298
  - `set_unexpected`,
1299
  - `unary_function`,
 
 
1300
  - `unexpected`, and
1301
  - `unexpected_handler`.
1302
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1303
  ##### Macro names <a id="macro.names">[[macro.names]]</a>
1304
 
1305
  A translation unit that includes a standard library header shall not
1306
  `#define` or `#undef` names declared in any standard library header.
1307
 
1308
  A translation unit shall not `#define` or `#undef` names lexically
1309
- identical to keywords, to the identifiers listed in Table 
1310
- [[tab:identifiers.special]], or to the *attribute-token*s described in 
1311
- [[dcl.attr]].
 
1312
 
1313
  ##### External linkage <a id="extern.names">[[extern.names]]</a>
1314
 
1315
  Each name declared as an object with external linkage in a header is
1316
  reserved to the implementation to designate that library object with
1317
- external linkage, [^22] both in namespace `std` and in the global
1318
  namespace.
1319
 
1320
  Each global function signature declared with external linkage in a
1321
  header is reserved to the implementation to designate that function
1322
- signature with external linkage.[^23]
1323
 
1324
  Each name from the C standard library declared with external linkage is
1325
  reserved to the implementation for use as a name with `extern "C"`
1326
  linkage, both in namespace `std` and in the global namespace.
1327
 
1328
  Each function signature from the C standard library declared with
1329
  external linkage is reserved to the implementation for use as a function
1330
- signature with both `extern "C"` and `extern "C++"` linkage,[^24] or as
1331
  a name of namespace scope in the global namespace.
1332
 
1333
  ##### Types <a id="extern.types">[[extern.types]]</a>
1334
 
1335
- For each type T from the C standard library,[^25] the types `::T` and
1336
  `std::T` are reserved to the implementation and, when defined, `::T`
1337
  shall be identical to `std::T`.
1338
 
1339
  ##### User-defined literal suffixes <a id="usrlit.suffix">[[usrlit.suffix]]</a>
1340
 
1341
- Literal suffix identifiers ([[over.literal]]) that do not start with an
1342
  underscore are reserved for future standardization.
1343
 
1344
  #### Headers <a id="alt.headers">[[alt.headers]]</a>
1345
 
1346
  If a file with a name equivalent to the derived file name for one of the
1347
  C++ standard library headers is not provided as part of the
1348
  implementation, and a file with that name is placed in any of the
1349
- standard places for a source file to be included ([[cpp.include]]), the
1350
  behavior is undefined.
1351
 
1352
  #### Derived classes <a id="derived.classes">[[derived.classes]]</a>
1353
 
1354
- Virtual member function signatures defined for a base class in the
1355
- C++standard library may be overridden in a derived class defined in the
1356
- program ([[class.virtual]]).
1357
 
1358
  #### Replacement functions <a id="replacement.functions">[[replacement.functions]]</a>
1359
 
1360
- Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]]
1361
- describe the behavior of numerous functions defined by the C++standard
1362
- library. Under some circumstances, however, certain of these function
1363
- descriptions also apply to replacement functions defined in the
1364
- program ([[definitions]]).
1365
 
1366
- A C++program may provide the definition for any of the following dynamic
1367
- memory allocation function signatures declared in header `<new>` (
1368
- [[basic.stc.dynamic]], [[support.dynamic]]):
1369
 
1370
  ``` cpp
1371
  operator new(std::size_t)
1372
  operator new(std::size_t, std::align_val_t)
1373
  operator new(std::size_t, const std::nothrow_t&)
@@ -1398,19 +1664,19 @@ operator delete[](void*, std::size_t, std::align_val_t)
1398
  operator delete[](void*, const std::nothrow_t&)
1399
  operator delete[](void*, std::align_val_t, const std::nothrow_t&)
1400
  ```
1401
 
1402
  The program’s definitions are used instead of the default versions
1403
- supplied by the implementation ([[support.dynamic]]). Such replacement
1404
- occurs prior to program startup ([[basic.def.odr]], [[basic.start]]).
1405
- The program’s declarations shall not be specified as `inline`. No
1406
- diagnostic is required.
1407
 
1408
  #### Handler functions <a id="handler.functions">[[handler.functions]]</a>
1409
 
1410
  The C++ standard library provides a default version of the following
1411
- handler function (Clause  [[language.support]]):
1412
 
1413
  - `terminate_handler`
1414
 
1415
  A C++ program may install different handler functions during execution,
1416
  by supplying a pointer to a function defined in the program or the
@@ -1436,34 +1702,34 @@ function.
1436
  #### Other functions <a id="res.on.functions">[[res.on.functions]]</a>
1437
 
1438
  In certain cases (replacement functions, handler functions, operations
1439
  on types used to instantiate standard library template components), the
1440
  C++ standard library depends on components supplied by a C++ program. If
1441
- these components do not meet their requirements, this International
1442
- Standard places no requirements on the implementation.
1443
 
1444
  In particular, the effects are undefined in the following cases:
1445
 
1446
- - for replacement functions ([[new.delete]]), if the installed
1447
- replacement function does not implement the semantics of the
1448
- applicable *Required behavior:* paragraph.
1449
- - for handler functions ([[new.handler]], [[terminate.handler]]), if
1450
  the installed handler function does not implement the semantics of the
1451
- applicable *Required behavior:* paragraph
1452
- - for types used as template arguments when instantiating a template
1453
  component, if the operations on the type do not implement the
1454
  semantics of the applicable *Requirements* subclause (
1455
  [[allocator.requirements]], [[container.requirements]],
1456
  [[iterator.requirements]], [[algorithms.requirements]],
1457
  [[numeric.requirements]]). Operations on such types can report a
1458
  failure by throwing an exception unless otherwise specified.
1459
- - if any replacement function or handler function or destructor
1460
  operation exits via an exception, unless specifically allowed in the
1461
  applicable *Required behavior:* paragraph.
1462
- - if an incomplete type ([[basic.types]]) is used as a template
1463
- argument when instantiating a template component, unless specifically
1464
- allowed for that component.
1465
 
1466
  #### Function arguments <a id="res.on.arguments">[[res.on.arguments]]</a>
1467
 
1468
  Each of the following applies to all arguments to functions defined in
1469
  the C++ standard library, unless explicitly stated otherwise.
@@ -1478,74 +1744,85 @@ the C++standard library, unless explicitly stated otherwise.
1478
  fact valid.
1479
  - If a function argument binds to an rvalue reference parameter, the
1480
  implementation may assume that this parameter is a unique reference to
1481
  this argument. \[*Note 1*: If the parameter is a generic parameter of
1482
  the form `T&&` and an lvalue of type `A` is bound, the argument binds
1483
- to an lvalue reference ([[temp.deduct.call]]) and thus is not covered
1484
- by the previous sentence. — *end note*] \[*Note 2*: If a program
1485
- casts an lvalue to an xvalue while passing that lvalue to a library
1486
- function (e.g. by calling the function with the argument
1487
- `std::move(x)`), the program is effectively asking that function to
1488
- treat that lvalue as a temporary. The implementation is free to
1489
- optimize away aliasing checks which might be needed if the argument
1490
- was an lvalue. — *end note*]
1491
 
1492
  #### Library object access <a id="res.on.objects">[[res.on.objects]]</a>
1493
 
1494
  The behavior of a program is undefined if calls to standard library
1495
  functions from different threads may introduce a data race. The
1496
  conditions under which this may occur are specified in 
1497
  [[res.on.data.races]].
1498
 
1499
  [*Note 1*: Modifying an object of a standard library type that is
1500
  shared between threads risks undefined behavior unless objects of that
1501
- type are explicitly specified as being sharable without data races or
1502
  the user supplies a locking mechanism. — *end note*]
1503
 
1504
  If an object of a standard library type is accessed, and the beginning
1505
- of the object’s lifetime ([[basic.life]]) does not happen before the
1506
  access, or the access does not happen before the end of the object’s
1507
  lifetime, the behavior is undefined unless otherwise specified.
1508
 
1509
  [*Note 2*: This applies even to objects such as mutexes intended for
1510
  thread synchronization. — *end note*]
1511
 
1512
- #### Requires paragraph <a id="res.on.required">[[res.on.required]]</a>
1513
 
1514
- Violation of the preconditions specified in a function’s *Requires:*
1515
- paragraph results in undefined behavior unless the function’s *Throws:*
1516
- paragraph specifies throwing an exception when the precondition is
1517
- violated.
 
 
 
 
 
 
 
 
 
 
 
 
1518
 
1519
  ### Conforming implementations <a id="conforming">[[conforming]]</a>
1520
 
1521
  #### Overview <a id="conforming.overview">[[conforming.overview]]</a>
1522
 
1523
- This section describes the constraints upon, and latitude of,
1524
- implementations of the C++standard library.
1525
 
1526
  An implementation’s use of headers is discussed in  [[res.on.headers]],
1527
  its use of macros in  [[res.on.macro.definitions]], non-member functions
1528
  in  [[global.functions]], member functions in  [[member.functions]],
1529
  data race avoidance in  [[res.on.data.races]], access specifiers in 
1530
  [[protection.within.classes]], class derivation in  [[derivation]], and
1531
  exceptions in  [[res.on.exception.handling]].
1532
 
1533
  #### Headers <a id="res.on.headers">[[res.on.headers]]</a>
1534
 
1535
- A C++header may include other C++headers. A C++header shall provide the
1536
- declarations and definitions that appear in its synopsis. A C++header
1537
- shown in its synopsis as including other C++headers shall provide the
1538
- declarations and definitions that appear in the synopses of those other
1539
- headers.
1540
 
1541
  Certain types and macros are defined in more than one header. Every such
1542
  entity shall be defined such that any header that defines it may be
1543
- included after any other header that also defines it (
1544
- [[basic.def.odr]]).
1545
 
1546
- The C standard library headers ([[depr.c.headers]]) shall include only
1547
  their corresponding C++ standard library header, as described in 
1548
  [[headers]].
1549
 
1550
  #### Restrictions on macro definitions <a id="res.on.macro.definitions">[[res.on.macro.definitions]]</a>
1551
 
@@ -1558,31 +1835,30 @@ suitable for use in `#if` preprocessing directives, unless explicitly
1558
  stated otherwise.
1559
 
1560
  #### Non-member functions <a id="global.functions">[[global.functions]]</a>
1561
 
1562
  It is unspecified whether any non-member functions in the C++ standard
1563
- library are defined as `inline` ([[dcl.inline]]).
1564
 
1565
- A call to a non-member function signature described in Clauses 
1566
- [[language.support]] through  [[thread]] and Annex  [[depr]] shall
1567
- behave as if the implementation declared no additional non-member
1568
- function signatures.[^26]
1569
 
1570
  An implementation shall not declare a non-member function signature with
1571
  additional default arguments.
1572
 
1573
  Unless otherwise specified, calls made by functions in the standard
1574
  library to non-operator, non-member functions do not use functions from
1575
- another namespace which are found through *argument-dependent name
1576
- lookup* ([[basic.lookup.argdep]]).
1577
 
1578
  [*Note 1*:
1579
 
1580
  The phrase “unless otherwise specified” applies to cases such as the
1581
- swappable with requirements ([[swappable.requirements]]). The exception
1582
  for overloaded operators allows argument-dependent lookup in cases like
1583
- that of `ostream_iterator::operator=` ([[ostream.iterator.ops]]):
1584
 
1585
  *Effects:*
1586
 
1587
  ``` cpp
1588
  *out_stream << value;
@@ -1594,75 +1870,90 @@ return *this;
1594
  — *end note*]
1595
 
1596
  #### Member functions <a id="member.functions">[[member.functions]]</a>
1597
 
1598
  It is unspecified whether any member functions in the C++ standard
1599
- library are defined as `inline` ([[dcl.inline]]).
1600
 
1601
  For a non-virtual member function described in the C++ standard library,
1602
  an implementation may declare a different set of member function
1603
  signatures, provided that any call to the member function that would
1604
  select an overload from the set of declarations described in this
1605
- International Standard behaves as if that overload were selected.
1606
 
1607
  [*Note 1*: For instance, an implementation may add parameters with
1608
  default values, or replace a member function with default arguments with
1609
  two or more member functions with equivalent behavior, or add additional
1610
  signatures for a member function name. — *end note*]
1611
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1612
  #### Constexpr functions and constructors <a id="constexpr.functions">[[constexpr.functions]]</a>
1613
 
1614
- This International Standard explicitly requires that certain standard
1615
- library functions are `constexpr` ([[dcl.constexpr]]). An
1616
- implementation shall not declare any standard library function signature
1617
- as `constexpr` except for those where it is explicitly required. Within
1618
- any header that provides any non-defining declarations of constexpr
1619
- functions or constructors an implementation shall provide corresponding
1620
- definitions.
1621
 
1622
  #### Requirements for stable algorithms <a id="algorithm.stable">[[algorithm.stable]]</a>
1623
 
1624
  When the requirements for an algorithm state that it is “stable” without
1625
  further elaboration, it means:
1626
 
1627
- - For the *sort* algorithms the relative order of equivalent elements is
1628
  preserved.
1629
- - For the *remove* and *copy* algorithms the relative order of the
1630
- elements that are not removed is preserved.
1631
- - For the *merge* algorithms, for equivalent elements in the original
1632
- two ranges, the elements from the first range (preserving their
1633
- original order) precede the elements from the second range (preserving
1634
- their original order).
1635
 
1636
  #### Reentrancy <a id="reentrancy">[[reentrancy]]</a>
1637
 
1638
- Except where explicitly specified in this International Standard, it is
1639
  *implementation-defined* which functions in the C++ standard library may
1640
  be recursively reentered.
1641
 
1642
  #### Data race avoidance <a id="res.on.data.races">[[res.on.data.races]]</a>
1643
 
1644
- This section specifies requirements that implementations shall meet to
1645
- prevent data races ([[intro.multithread]]). Every standard library
1646
  function shall meet each requirement unless otherwise specified.
1647
  Implementations may prevent data races in cases other than those
1648
  specified below.
1649
 
1650
  A C++ standard library function shall not directly or indirectly access
1651
- objects ([[intro.multithread]]) accessible by threads other than the
1652
  current thread unless the objects are accessed directly or indirectly
1653
  via the function’s arguments, including `this`.
1654
 
1655
  A C++ standard library function shall not directly or indirectly modify
1656
- objects ([[intro.multithread]]) accessible by threads other than the
1657
  current thread unless the objects are accessed directly or indirectly
1658
  via the function’s non-const arguments, including `this`.
1659
 
1660
- [*Note 1*: This means, for example, that implementations can’t use a
1661
- static object for internal purposes without synchronization because it
1662
- could cause a data race even in programs that do not explicitly share
1663
- objects between threads. — *end note*]
1664
 
1665
  A C++ standard library function shall not access objects indirectly
1666
  accessible via its arguments or via elements of its container arguments
1667
  except by invoking functions required by its specification on those
1668
  container elements.
@@ -1679,31 +1970,31 @@ Implementations may share their own internal objects between threads if
1679
  the objects are not visible to users and are protected against data
1680
  races.
1681
 
1682
  Unless otherwise specified, C++ standard library functions shall perform
1683
  all operations solely within the current thread if those operations have
1684
- effects that are visible ([[intro.multithread]]) to users.
1685
 
1686
  [*Note 3*: This allows implementations to parallelize operations if
1687
  there are no visible side effects. — *end note*]
1688
 
1689
  #### Protection within classes <a id="protection.within.classes">[[protection.within.classes]]</a>
1690
 
1691
  It is unspecified whether any function signature or class described in
1692
- Clauses  [[language.support]] through  [[thread]] and Annex  [[depr]] is
1693
- a `friend` of another class in the C++standard library.
1694
 
1695
  #### Derived classes <a id="derivation">[[derivation]]</a>
1696
 
1697
- An implementation may derive any class in the C++standard library from a
1698
- class with a name reserved to the implementation.
1699
 
1700
  Certain classes defined in the C++ standard library are required to be
1701
- derived from other classes in the C++standard library. An implementation
1702
- may derive such a class directly from the required base or indirectly
1703
- through a hierarchy of base classes with names reserved to the
1704
- implementation.
1705
 
1706
  In any case:
1707
 
1708
  - Every base class described as `virtual` shall be virtual;
1709
  - Every base class not specified as `virtual` shall not be virtual;
@@ -1723,13 +2014,13 @@ type.
1723
 
1724
  Functions from the C standard library shall not throw exceptions [^28]
1725
  except when such a function calls a program-supplied function that
1726
  throws an exception.[^29]
1727
 
1728
- Destructor operations defined in the C++standard library shall not throw
1729
- exceptions. Every destructor in the C++standard library shall behave as
1730
- if it had a non-throwing exception specification.
1731
 
1732
  Functions defined in the C++ standard library that do not have a
1733
  *Throws:* paragraph but do have a potentially-throwing exception
1734
  specification may throw *implementation-defined* exceptions. [^30]
1735
  Implementations should report errors by throwing exceptions of or
@@ -1741,157 +2032,189 @@ non-virtual function by adding a non-throwing exception specification.
1741
 
1742
  #### Restrictions on storage of pointers <a id="res.on.pointer.storage">[[res.on.pointer.storage]]</a>
1743
 
1744
  Objects constructed by the standard library that may hold a
1745
  user-supplied pointer value or an integer of type `std::intptr_t` shall
1746
- store such values in a traceable pointer location (
1747
- [[basic.stc.dynamic.safety]]).
1748
 
1749
  [*Note 1*: Other libraries are strongly encouraged to do the same,
1750
  since not doing so may result in accidental use of pointers that are not
1751
  safely derived. Libraries that store pointers outside the user’s address
1752
  space should make it appear that they are stored and retrieved from a
1753
  traceable pointer location. — *end note*]
1754
 
1755
  #### Value of error codes <a id="value.error.codes">[[value.error.codes]]</a>
1756
 
1757
  Certain functions in the C++ standard library report errors via a
1758
- `std::error_code` ([[syserr.errcode.overview]]) object. That object’s
1759
  `category()` member shall return `std::system_category()` for errors
1760
  originating from the operating system, or a reference to an
1761
  *implementation-defined* `error_category` object for errors originating
1762
  elsewhere. The implementation shall define the possible values of
1763
  `value()` for each of these error categories.
1764
 
1765
  [*Example 1*: For operating systems that are based on POSIX,
1766
- implementations are encouraged to define the `std::system_category()`
1767
- values as identical to the POSIX `errno` values, with additional values
1768
- as defined by the operating system’s documentation. Implementations for
1769
- operating systems that are not based on POSIX are encouraged to define
1770
- values identical to the operating system’s values. For errors that do
1771
- not originate from the operating system, the implementation may provide
1772
- enums for the associated values. — *end example*]
1773
 
1774
  #### Moved-from state of library types <a id="lib.types.movedfrom">[[lib.types.movedfrom]]</a>
1775
 
1776
- Objects of types defined in the C++standard library may be moved from (
1777
- [[class.copy]]). Move operations may be explicitly specified or
1778
  implicitly generated. Unless otherwise specified, such moved-from
1779
  objects shall be placed in a valid but unspecified state.
1780
 
1781
  <!-- Link reference definitions -->
1782
  [alg.c.library]: algorithms.md#alg.c.library
1783
  [alg.sorting]: algorithms.md#alg.sorting
1784
  [algorithm.stable]: #algorithm.stable
1785
  [algorithms]: algorithms.md#algorithms
1786
  [algorithms.requirements]: algorithms.md#algorithms.requirements
1787
- [alloc.errors]: language.md#alloc.errors
 
1788
  [allocator.requirements]: #allocator.requirements
1789
  [allocator.requirements.completeness]: #allocator.requirements.completeness
1790
  [allocator.traits]: utilities.md#allocator.traits
1791
  [alt.headers]: #alt.headers
1792
  [atomics]: atomics.md#atomics
1793
- [bad.alloc]: language.md#bad.alloc
 
 
1794
  [basic.def.odr]: basic.md#basic.def.odr
1795
  [basic.fundamental]: basic.md#basic.fundamental
1796
  [basic.life]: basic.md#basic.life
1797
  [basic.link]: basic.md#basic.link
1798
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
 
 
1799
  [basic.scope.namespace]: basic.md#basic.scope.namespace
1800
  [basic.start]: basic.md#basic.start
1801
  [basic.stc.dynamic]: basic.md#basic.stc.dynamic
1802
  [basic.stc.dynamic.safety]: basic.md#basic.stc.dynamic.safety
1803
  [basic.types]: basic.md#basic.types
 
1804
  [bitmask.types]: #bitmask.types
1805
  [byte.strings]: #byte.strings
1806
- [c.locales]: localization.md#c.locales
1807
- [c.strings]: strings.md#c.strings
1808
  [character.seq]: #character.seq
1809
- [class.conv.ctor]: special.md#class.conv.ctor
1810
- [class.copy]: special.md#class.copy
1811
- [class.ctor]: special.md#class.ctor
1812
- [class.dtor]: special.md#class.dtor
1813
  [class.mem]: class.md#class.mem
1814
  [class.mfct]: class.md#class.mfct
1815
  [class.this]: class.md#class.this
1816
  [class.virtual]: class.md#class.virtual
 
1817
  [compliance]: #compliance
 
 
 
 
 
 
1818
  [conforming]: #conforming
1819
  [conforming.overview]: #conforming.overview
1820
  [constexpr.functions]: #constexpr.functions
1821
  [constraints]: #constraints
1822
  [constraints.overview]: #constraints.overview
1823
  [container.requirements]: containers.md#container.requirements
1824
  [containers]: containers.md#containers
1825
  [contents]: #contents
1826
- [conv]: conv.md#conv
 
1827
  [conventions]: #conventions
1828
  [cpp.include]: cpp.md#cpp.include
1829
- [cstdint]: language.md#cstdint
 
 
 
 
 
 
 
 
 
1830
  [dcl.array]: dcl.md#dcl.array
1831
  [dcl.attr]: dcl.md#dcl.attr
1832
  [dcl.constexpr]: dcl.md#dcl.constexpr
1833
  [dcl.fct.default]: dcl.md#dcl.fct.default
1834
  [dcl.init]: dcl.md#dcl.init
1835
  [dcl.init.list]: dcl.md#dcl.init.list
1836
  [dcl.inline]: dcl.md#dcl.inline
1837
  [dcl.link]: dcl.md#dcl.link
 
1838
  [definitions]: #definitions
1839
  [depr]: future.md#depr
1840
  [depr.c.headers]: future.md#depr.c.headers
1841
- [depr.cstdalign.syn]: future.md#depr.cstdalign.syn
1842
- [depr.cstdbool.syn]: future.md#depr.cstdbool.syn
1843
  [derivation]: #derivation
1844
  [derived.classes]: #derived.classes
1845
  [description]: #description
1846
  [diagnostics]: diagnostics.md#diagnostics
1847
  [enumerated.types]: #enumerated.types
1848
  [except]: except.md#except
 
 
1849
  [expos.only.types]: #expos.only.types
1850
  [expr.cond]: expr.md#expr.cond
1851
  [expr.const]: expr.md#expr.const
1852
  [expr.delete]: expr.md#expr.delete
1853
  [expr.eq]: expr.md#expr.eq
1854
  [expr.new]: expr.md#expr.new
1855
  [expr.rel]: expr.md#expr.rel
 
 
1856
  [extern.names]: #extern.names
1857
  [extern.types]: #extern.types
1858
  [function.objects]: utilities.md#function.objects
1859
  [functions.within.classes]: #functions.within.classes
1860
  [global.functions]: #global.functions
1861
  [handler.functions]: #handler.functions
1862
  [hash.requirements]: #hash.requirements
1863
  [headers]: #headers
 
 
 
 
1864
  [input.output]: input.md#input.output
1865
  [intro.compliance]: intro.md#intro.compliance
1866
  [intro.defs]: intro.md#intro.defs
1867
- [intro.multithread]: intro.md#intro.multithread
 
1868
  [intro.refs]: intro.md#intro.refs
1869
  [iterator.requirements]: iterators.md#iterator.requirements
1870
- [iterator.requirements.general]: iterators.md#iterator.requirements.general
1871
  [iterators]: iterators.md#iterators
1872
- [language.support]: language.md#language.support
1873
- [lex]: lex.md#lex
1874
  [lex.phases]: lex.md#lex.phases
 
1875
  [lib.types.movedfrom]: #lib.types.movedfrom
1876
  [library]: #library
1877
  [library.c]: #library.c
 
1878
  [library.general]: #library.general
1879
  [locales]: localization.md#locales
1880
  [localization]: localization.md#localization
1881
  [macro.names]: #macro.names
1882
  [member.functions]: #member.functions
1883
  [meta]: utilities.md#meta
 
1884
  [multibyte.strings]: #multibyte.strings
1885
  [namespace.constraints]: #namespace.constraints
1886
  [namespace.def]: dcl.md#namespace.def
1887
  [namespace.future]: #namespace.future
1888
  [namespace.posix]: #namespace.posix
1889
  [namespace.std]: #namespace.std
1890
  [namespace.udecl]: dcl.md#namespace.udecl
1891
- [new.delete]: language.md#new.delete
1892
- [new.handler]: language.md#new.handler
 
1893
  [nullablepointer.requirements]: #nullablepointer.requirements
1894
  [numeric.requirements]: numerics.md#numeric.requirements
1895
  [numerics]: numerics.md#numerics
1896
  [objects.within.classes]: #objects.within.classes
1897
  [organization]: #organization
@@ -1899,71 +2222,73 @@ objects shall be placed in a valid but unspecified state.
1899
  [over.literal]: over.md#over.literal
1900
  [over.match]: over.md#over.match
1901
  [over.oper]: over.md#over.oper
1902
  [protection.within.classes]: #protection.within.classes
1903
  [random.access.iterators]: iterators.md#random.access.iterators
 
1904
  [re]: re.md#re
1905
  [reentrancy]: #reentrancy
1906
  [replacement.functions]: #replacement.functions
1907
  [requirements]: #requirements
1908
  [res.on.arguments]: #res.on.arguments
1909
  [res.on.data.races]: #res.on.data.races
1910
  [res.on.exception.handling]: #res.on.exception.handling
 
1911
  [res.on.functions]: #res.on.functions
1912
  [res.on.headers]: #res.on.headers
1913
  [res.on.macro.definitions]: #res.on.macro.definitions
1914
  [res.on.objects]: #res.on.objects
1915
  [res.on.pointer.storage]: #res.on.pointer.storage
1916
- [res.on.required]: #res.on.required
1917
  [reserved.names]: #reserved.names
 
1918
  [std.exceptions]: diagnostics.md#std.exceptions
 
1919
  [stream.types]: input.md#stream.types
1920
  [strings]: strings.md#strings
1921
  [structure]: #structure
1922
  [structure.elements]: #structure.elements
1923
  [structure.requirements]: #structure.requirements
1924
  [structure.see.also]: #structure.see.also
1925
  [structure.specifications]: #structure.specifications
1926
  [structure.summary]: #structure.summary
1927
- [support.dynamic]: language.md#support.dynamic
1928
- [support.exception]: language.md#support.exception
1929
- [support.initlist]: language.md#support.initlist
1930
- [support.limits]: language.md#support.limits
1931
- [support.rtti]: language.md#support.rtti
1932
- [support.runtime]: language.md#support.runtime
1933
- [support.start.term]: language.md#support.start.term
1934
- [support.types]: language.md#support.types
 
 
 
1935
  [swappable.requirements]: #swappable.requirements
1936
  [syserr]: diagnostics.md#syserr
1937
  [syserr.errcode.overview]: diagnostics.md#syserr.errcode.overview
1938
- [tab:c.annex.k.names]: #tab:c.annex.k.names
1939
- [tab:copyassignable]: #tab:copyassignable
1940
- [tab:cpp.c.headers]: #tab:cpp.c.headers
1941
- [tab:cpp.headers.freestanding]: #tab:cpp.headers.freestanding
1942
- [tab:cpp.library.headers]: #tab:cpp.library.headers
1943
- [tab:desc.var.def]: #tab:desc.var.def
1944
- [tab:destructible]: #tab:destructible
1945
- [tab:equalitycomparable]: #tab:equalitycomparable
1946
- [tab:hash]: #tab:hash
1947
- [tab:identifiers.special]: lex.md#tab:identifiers.special
1948
- [tab:library.categories]: #tab:library.categories
1949
- [tab:moveassignable]: #tab:moveassignable
1950
- [tab:nullablepointer]: #tab:nullablepointer
1951
- [tab:utilities.allocator.requirements]: #tab:utilities.allocator.requirements
1952
  [temp.deduct.call]: temp.md#temp.deduct.call
 
1953
  [template.bitset]: utilities.md#template.bitset
1954
- [terminate.handler]: language.md#terminate.handler
1955
  [thread]: thread.md#thread
 
1956
  [type.descriptions]: #type.descriptions
1957
  [type.descriptions.general]: #type.descriptions.general
1958
  [using]: #using
1959
  [using.headers]: #using.headers
1960
  [using.linkage]: #using.linkage
1961
  [using.overview]: #using.overview
1962
  [usrlit.suffix]: #usrlit.suffix
1963
  [utilities]: utilities.md#utilities
1964
- [utility]: utilities.md#utility
1965
  [utility.arg.requirements]: #utility.arg.requirements
1966
  [utility.requirements]: #utility.requirements
1967
  [value.error.codes]: #value.error.codes
1968
  [zombie.names]: #zombie.names
1969
 
@@ -1976,60 +2301,60 @@ objects shall be placed in a valid but unspecified state.
1976
 
1977
  [^3]: To save space, items that do not apply to a class are omitted. For
1978
  example, if a class does not specify any comparison functions, there
1979
  will be no “Comparison functions” subclause.
1980
 
1981
- [^4]: To save space, items that do not apply to a function are omitted.
1982
- For example, if a function does not specify any further
1983
- preconditions, there will be no *Requires:* paragraph.
1984
 
1985
  [^5]: This simplifies the presentation of complexity requirements in
1986
  some cases.
1987
 
1988
  [^6]: Examples from  [[utility.requirements]] include:
1989
- `EqualityComparable`, `LessThanComparable`, `CopyConstructible`.
1990
- Examples from  [[iterator.requirements]] include: `InputIterator`,
1991
- `ForwardIterator`.
1992
 
1993
- [^7]: Such as an integer type, with constant integer values (
1994
- [[basic.fundamental]]).
1995
 
1996
- [^8]: declared in `<clocale>` ([[c.locales]]).
1997
 
1998
  [^9]: Many of the objects manipulated by function signatures declared in
1999
- `<cstring>` ([[c.strings]]) are character sequences or NTBSs. The
2000
- size of some of these character sequences is limited by a length
2001
- value, maintained separately from the character sequence.
2002
 
2003
- [^10]: A string literal, such as `"abc"`, is a static NTBS.
2004
 
2005
  [^11]: An NTBS that contains characters only from the basic execution
2006
  character set is also an NTMBS. Each multibyte character then
2007
  consists of a single byte.
2008
 
2009
- [^12]: The C standard library headers (Annex  [[depr.c.headers]]) also
2010
- define names within the global namespace, while the C++headers for C
2011
- library facilities ([[headers]]) may also define names within the
2012
  global namespace.
2013
 
2014
  [^13]: This gives implementers freedom to use inline namespaces to
2015
  support multiple configurations of the library.
2016
 
2017
  [^14]: A header is not necessarily a source file, nor are the sequences
2018
  delimited by `<` and `>` in header names necessarily valid source
2019
- file names ([[cpp.include]]).
2020
 
2021
  [^15]: It is intentional that there is no C++ header for any of these C
2022
  headers: `<stdatomic.h>`, `<stdnoreturn.h>`, `<threads.h>`.
2023
 
2024
  [^16]: This disallows the practice, allowed in C, of providing a masking
2025
  macro in addition to the function prototype. The only way to achieve
2026
  equivalent inline behavior in C++ is to provide a definition as an
2027
  extern inline function.
2028
 
2029
- [^17]: In particular, including the standard header `<iso646.h>` or
2030
- `<ciso646>` has no effect.
2031
 
2032
  [^18]: The `".h"` headers dump all their names into the global
2033
  namespace, whereas the newer forms keep their names in namespace
2034
  `std`. Therefore, the newer forms are the preferred forms for all
2035
  uses except for C++ programs which are intended to be strictly
@@ -2041,43 +2366,50 @@ objects shall be placed in a valid but unspecified state.
2041
  from the C standard library is by including the header that declares
2042
  it, notwithstanding the latitude granted in 7.1.4 of the C Standard.
2043
 
2044
  [^21]: Any library code that instantiates other library templates must
2045
  be prepared to work adequately with any user-supplied specialization
2046
- that meets the minimum requirements of this International Standard.
2047
 
2048
- [^22]: The list of such reserved names includes `errno`, declared or
 
 
 
 
 
 
 
 
 
 
 
2049
  defined in `<cerrno>`.
2050
 
2051
- [^23]: The list of such reserved function signatures with external
2052
  linkage includes `setjmp(jmp_buf)`, declared or defined in
2053
  `<csetjmp>`, and `va_end(va_list)`, declared or defined in
2054
  `<cstdarg>`.
2055
 
2056
- [^24]: The function signatures declared in `<cuchar>`, `<cwchar>`, and
2057
  `<cwctype>` are always reserved, notwithstanding the restrictions
2058
  imposed in subclause 4.5.1 of Amendment 1 to the C Standard for
2059
  these headers.
2060
 
2061
- [^25]: These types are `clock_t`, `div_t`, `FILE`, `fpos_t`, `lconv`,
2062
- `ldiv_t`, `mbstate_t`, `ptrdiff_t`, `sig_atomic_t`, `size_t`,
2063
- `time_t`, `tm`, `va_list`, `wctrans_t`, `wctype_t`, and `wint_t`.
2064
-
2065
  [^26]: A valid C++ program always calls the expected library non-member
2066
  function. An implementation may also define additional non-member
2067
  functions that would otherwise not be called by a valid C++ program.
2068
 
2069
  [^27]: There is an implicit exception to this rule for types that are
2070
- described as synonyms for basic integral types, such as `size_t` (
2071
- [[support.types]]) and `streamoff` ([[stream.types]]).
2072
 
2073
  [^28]: That is, the C library functions can all be treated as if they
2074
  are marked `noexcept`. This allows implementations to make
2075
  performance optimizations based on the absence of exceptions at
2076
  runtime.
2077
 
2078
- [^29]: The functions `qsort()` and `bsearch()` ([[alg.c.library]]) meet
2079
  this condition.
2080
 
2081
  [^30]: In particular, they can report a failure to allocate storage by
2082
  throwing an exception of type `bad_alloc`, or a class derived from
2083
- `bad_alloc` ([[bad.alloc]]).
 
4
 
5
  This Clause describes the contents of the *C++ standard library*, how a
6
  well-formed C++ program makes use of the library, and how a conforming
7
  implementation may provide the entities in the library.
8
 
9
+ The following subclauses describe the definitions [[definitions]],
10
+ method of description [[description]], and organization [[organization]]
11
+ of the library. [[requirements]], [[support]] through [[thread]], and
12
+ [[depr]] specify the contents of the library, as well as library
13
+ requirements and constraints on both well-formed C++ programs and
14
+ conforming implementations.
 
15
 
16
  Detailed specifications for each of the components in the library are in
17
+ [[support]]– [[thread]], as shown in [[library.categories]].
18
+
19
+ **Table: Library categories** <a id="library.categories">[library.categories]</a>
20
+
21
+ | Clause | Category |
22
+ | ---------------- | --------------------------- |
23
+ | [[support]] | Language support library |
24
+ | [[concepts]] | Concepts library |
25
+ | [[diagnostics]] | Diagnostics library |
26
+ | [[utilities]] | General utilities library |
27
+ | [[strings]] | Strings library |
28
+ | [[containers]] | Containers library |
29
+ | [[iterators]] | Iterators library |
30
+ | [[ranges]] | Ranges library |
31
+ | [[algorithms]] | Algorithms library |
32
+ | [[numerics]] | Numerics library |
33
+ | [[time]] | Time library |
34
+ | [[localization]] | Localization library |
35
+ | [[input.output]] | Input/output library |
36
+ | [[re]] | Regular expressions library |
37
+ | [[atomics]] | Atomic operations library |
38
+ | [[thread]] | Thread support library |
39
+
40
+
41
+ The language support library [[support]] provides components that are
42
+ required by certain parts of the C++ language, such as memory
43
+ allocation ([[expr.new]], [[expr.delete]]) and exception processing
44
+ [[except]].
45
+
46
+ The concepts library [[concepts]] describes library components that C++
47
+ programs may use to perform compile-time validation of template
48
+ arguments and perform function dispatch based on properties of types.
49
+
50
+ The diagnostics library [[diagnostics]] provides a consistent framework
51
+ for reporting errors in a C++ program, including predefined exception
52
+ classes.
53
+
54
+ The general utilities library [[utilities]] includes components used by
55
+ other library elements, such as a predefined storage allocator for
56
+ dynamic storage management [[basic.stc.dynamic]], and components used as
57
+ infrastructure in C++ programs, such as tuples, function wrappers, and
58
+ time facilities.
59
+
60
+ The strings library [[strings]] provides support for manipulating text
61
+ represented as sequences of type `char`, sequences of type `char8_t`,
62
+ sequences of type `char16_t`, sequences of type `char32_t`, sequences of
63
+ type `wchar_t`, and sequences of any other character-like type.
64
+
65
+ The localization library [[localization]] provides extended
66
  internationalization support for text processing.
67
 
68
+ The containers [[containers]], iterators [[iterators]], ranges
69
+ [[ranges]], and algorithms [[algorithms]] libraries provide a C++
70
+ program with access to a subset of the most widely used algorithms and
71
+ data structures.
72
 
73
+ The numerics library [[numerics]] provides numeric algorithms and
74
+ complex number components that extend support for numeric processing.
75
+ The `valarray` component provides support for *n*-at-a-time processing,
76
+ potentially implemented as parallel operations on platforms that support
77
+ such processing. The random number component provides facilities for
78
+ generating pseudo-random numbers.
79
 
80
+ The input/output library [[input.output]] provides the `iostream`
81
+ components that are the primary mechanism for C++ program input and
82
+ output. They can be used with other elements of the library,
83
  particularly strings, locales, and iterators.
84
 
85
+ The regular expressions library [[re]] provides regular expression
86
+ matching and searching.
87
 
88
+ The atomic operations library [[atomics]] allows more fine-grained
89
+ concurrent access to shared data than is possible with locks.
 
90
 
91
+ The thread support library [[thread]] provides components to create and
92
+ manage threads, including mutual exclusion and interthread
93
  communication.
94
 
95
  ## The C standard library <a id="library.c">[[library.c]]</a>
96
 
97
  The C++ standard library also makes available the facilities of the C
98
  standard library, suitably adjusted to ensure static type safety.
99
 
100
  The descriptions of many library functions rely on the C standard
101
  library for the semantics of those functions. In some cases, the
102
+ signatures specified in this document may be different from the
103
+ signatures in the C standard library, and additional overloads may be
104
+ declared in this document, but the behavior and the preconditions
105
+ (including any preconditions implied by the use of an ISO C `restrict`
106
+ qualifier) are the same unless otherwise stated.
107
 
108
  ## Definitions <a id="definitions">[[definitions]]</a>
109
 
110
+ [*Note 1*: [[intro.defs]] defines additional terms used elsewhere in
111
+ this document. — *end note*]
112
 
113
+ #### 1 arbitrary-positional stream <a id="defns.arbitrary.stream">[[defns.arbitrary.stream]]</a>
 
114
 
115
+ stream (described in [[input.output]]) that can seek to any integral
116
+ position within the length of the stream
117
 
118
+ [*Note 1 to entry*: Every arbitrary-positional stream is also a
119
+ repositional stream. *end note*]
120
 
121
+ #### 2 character <a id="defns.character">[[defns.character]]</a>
 
 
122
 
123
+ ⟨[[strings]], [[localization]], [[input.output]], and~ [[re]]⟩
124
+ object which, when treated sequentially, can represent text
125
 
126
+ [*Note 1 to entry*: The term does not mean only `char`, `char8_t`,
127
+ `char16_t`, `char32_t`, and `wchar_t` objects, but any value that can be
128
+ represented by a type that provides the definitions specified in these
129
+ Clauses. — *end note*]
130
 
131
+ #### 3 character container type <a id="defns.character.container">[[defns.character.container]]</a>
 
132
 
133
+ class or a type used to represent a character
134
+
135
+ [*Note 1 to entry*: It is used for one of the template parameters of
136
+ the string, iostream, and regular expression class
137
+ templates. — *end note*]
138
+
139
+ #### 4 comparison function <a id="defns.comparison">[[defns.comparison]]</a>
140
+
141
+ operator function [[over.oper]] for any of the equality [[expr.eq]],
142
+ relational [[expr.rel]], or three-way comparison [[expr.spaceship]]
143
+ operators
144
+
145
+ #### 5 component <a id="defns.component">[[defns.component]]</a>
146
+
147
+ group of library entities directly related as members, parameters, or
148
  return types
149
 
150
+ [*Note 1 to entry*: For example, the class template `basic_string` and
151
+ the non-member function templates that operate on strings are referred
152
+ to as the *string component*. — *end note*]
153
 
154
+ #### 6 constant subexpression <a id="defns.const.subexpr">[[defns.const.subexpr]]</a>
 
 
155
 
156
+ expression whose evaluation as subexpression of a
157
+ *conditional-expression* `CE` [[expr.cond]] would not prevent `CE` from
158
+ being a core constant expression [[expr.const]]
159
 
160
+ #### 7 deadlock <a id="defns.deadlock">[[defns.deadlock]]</a>
 
161
 
162
+ situation wherein one or more threads are unable to continue execution
163
+ because each is blocked waiting for one or more of the others to satisfy
164
+ some condition
165
 
166
+ #### 8 default behavior <a id="defns.default.behavior.impl">[[defns.default.behavior.impl]]</a>
 
167
 
168
+ ⟨implementation⟩ specific behavior provided by the implementation,
169
+ within the scope of the required behavior
170
 
171
+ #### 9 default behavior <a id="defns.default.behavior.func">[[defns.default.behavior.func]]</a>
 
 
 
172
 
173
+ ⟨specification⟩ description of replacement function and handler function
174
+ semantics
175
 
176
+ #### 10 direct-non-list-initialization <a id="defns.direct-non-list-init">[[defns.direct-non-list-init]]</a>
 
 
 
 
177
 
178
+ direct-initialization [[dcl.init]] that is not list-initialization
179
+ [[dcl.init.list]]
180
+
181
+ #### 11 expression-equivalent <a id="defns.expression-equivalent">[[defns.expression-equivalent]]</a>
182
+
183
+ expressions that all have the same effects, either are all
184
+ potentially-throwing [[except.spec]] or are all not
185
+ potentially-throwing, and either are all constant subexpressions or are
186
+ all not constant subexpressions
187
+
188
+ [*Example 1*: For a value `x` of type `int` and a function `f` that
189
+ accepts integer arguments, the expressions `f(x + 2)`, `f(2 + x)`, and
190
+ `f(1 + x + 1)` are expression-equivalent. — *end example*]
191
+
192
+ #### 12 handler function <a id="defns.handler">[[defns.handler]]</a>
193
+
194
+ non-reserved function whose definition may be provided by a C++ program
195
+
196
+ [*Note 1 to entry*: A C++ program may designate a handler function at
197
+ various points in its execution by supplying a pointer to the function
198
+ when calling any of the library functions that install handler functions
199
+ [[support]]. — *end note*]
200
+
201
+ #### 13 implementation-defined strict total order over pointers <a id="defns.order.ptr">[[defns.order.ptr]]</a>
202
+
203
+ *implementation-defined* strict total ordering over all pointer values
204
+ such that the ordering is consistent with the partial order imposed by
205
+ the builtin operators `<`, `>`, `<=`, `>=`, and `<=>`
206
+
207
+ #### 14 iostream class templates <a id="defns.iostream.templates">[[defns.iostream.templates]]</a>
208
+
209
+ templates, defined in [[input.output]], that take two template arguments
210
+
211
+ [*Note 1 to entry*: The arguments are named `charT` and `traits`. The
212
+ argument `charT` is a character container class, and the argument
213
+ `traits` is a class which defines additional characteristics and
214
+ functions of the character type represented by `charT` necessary to
215
+ implement the iostream class templates. — *end note*]
216
+
217
+ #### 15 modifier function <a id="defns.modifier">[[defns.modifier]]</a>
218
+
219
+ class member function [[class.mfct]] other than a constructor,
220
  assignment operator, or destructor that alters the state of an object of
221
  the class
222
 
223
+ #### 16 move assignment <a id="defns.move.assign">[[defns.move.assign]]</a>
224
+
225
  assignment of an rvalue of some object type to a modifiable lvalue of
226
  the same type
227
 
228
+ #### 17 move construction <a id="defns.move.constr">[[defns.move.constr]]</a>
229
+
230
  direct-initialization of an object of some type with an rvalue of the
231
  same type
232
 
233
+ #### 18 NTCTS <a id="defns.ntcts">[[defns.ntcts]]</a>
 
234
 
235
+ sequence of values that have character type that precede the terminating
236
+ null character type value `charT()`
237
+
238
+ #### 19 observer function <a id="defns.observer">[[defns.observer]]</a>
239
+
240
+ class member function [[class.mfct]] that accesses the state of an
241
  object of the class but does not alter that state
242
 
243
+ [*Note 1 to entry*: Observer functions are specified as `const` member
244
+ functions [[class.this]]. — *end note*]
245
 
246
+ #### 20 program-defined specialization <a id="defns.prog.def.spec">[[defns.prog.def.spec]]</a>
 
247
 
248
+ explicit template specialization or partial specialization that is not
249
+ part of the C++ standard library and not defined by the implementation
250
 
251
+ #### 21 program-defined type <a id="defns.prog.def.type">[[defns.prog.def.type]]</a>
252
 
253
+ non-closure class type or enumeration type that is not part of the C++
254
+ standard library and not defined by the implementation, or a closure
255
+ type of a non-implementation-provided lambda expression, or an
256
+ instantiation of a program-defined specialization
257
 
258
+ [*Note 1 to entry*: Types defined by the implementation include
259
+ extensions [[intro.compliance]] and internal types used by the
260
+ library. — *end note*]
261
 
262
+ #### 22 projection <a id="defns.projection">[[defns.projection]]</a>
263
+
264
+ ⟨function object argument⟩ transformation that an algorithm applies
265
+ before inspecting the values of elements
266
+
267
+ [*Example 1*:
268
+
269
+ ``` cpp
270
+ std::pair<int, std::string_view> pairs[] = {{2, "foo"}, {1, "bar"}, {0, "baz"}};
271
+ std::ranges::sort(pairs, std::ranges::less{}, [](auto const& p) { return p.first; });
272
+ ```
273
+
274
+ sorts the pairs in increasing order of their `first` members:
275
+
276
+ ``` cpp
277
+ {{0, "baz"}, {1, "bar"}, {2, "foo"}}
278
+ ```
279
+
280
+ — *end example*]
281
+
282
+ #### 23 referenceable type <a id="defns.referenceable">[[defns.referenceable]]</a>
283
+
284
+ type that is either an object type, a function type that does not have
285
+ cv-qualifiers or a *ref-qualifier*, or a reference type
286
+
287
+ [*Note 1 to entry*: The term describes a type to which a reference can
288
+ be created, including reference types. — *end note*]
289
+
290
+ #### 24 replacement function <a id="defns.replacement">[[defns.replacement]]</a>
291
+
292
+ non-reserved function whose definition is provided by a C++ program
293
+
294
+ [*Note 1 to entry*: Only one definition for such a function is in
295
+ effect for the duration of the program’s execution, as the result of
296
+ creating the program [[lex.phases]] and resolving the definitions of all
297
+ translation units [[basic.link]]. — *end note*]
298
+
299
+ #### 25 repositional stream <a id="defns.repositional.stream">[[defns.repositional.stream]]</a>
300
+
301
+ stream (described in [[input.output]]) that can seek to a position that
302
+ was previously encountered
303
+
304
+ #### 26 required behavior <a id="defns.required.behavior">[[defns.required.behavior]]</a>
305
+
306
+ description of replacement function and handler function semantics
307
  applicable to both the behavior provided by the implementation and the
308
  behavior of any such function definition in the program
309
 
310
+ [*Note 1 to entry*: If such a function defined in a C++ program fails
311
+ to meet the required behavior when it executes, the behavior is
312
+ undefined. — *end note*]
313
 
314
+ #### 27 reserved function <a id="defns.reserved.function">[[defns.reserved.function]]</a>
 
315
 
316
+ function, specified as part of the C++ standard library, that is defined
317
+ by the implementation
318
 
319
+ [*Note 1 to entry*: If a C++ program provides a definition for any
320
+ reserved function, the results are undefined. — *end note*]
321
+
322
+ #### 28 stable algorithm <a id="defns.stable">[[defns.stable]]</a>
323
+
324
+ algorithm that preserves, as appropriate to the particular algorithm,
325
  the order of elements
326
 
327
+ [*Note 1 to entry*: Requirements for stable algorithms are given in
328
  [[algorithm.stable]]. — *end note*]
329
 
330
+ #### 29 traits class <a id="defns.traits">[[defns.traits]]</a>
 
 
331
 
332
+ class that encapsulates a set of types and functions necessary for class
333
+ templates and function templates to manipulate objects of types for
334
+ which they are instantiated
335
+
336
+ #### 30 valid but unspecified state <a id="defns.valid">[[defns.valid]]</a>
337
+
338
+ value of an object that is not specified except that the object’s
339
  invariants are met and operations on the object behave as specified for
340
  its type
341
 
342
  [*Example 1*: If an object `x` of type `std::vector<int>` is in a valid
343
  but unspecified state, `x.empty()` can be called unconditionally, and
344
  `x.front()` can be called only if `x.empty()` returns
345
  `false`. — *end example*]
346
 
347
+ ## Method of description <a id="description">[[description]]</a>
348
 
349
+ This subclause describes the conventions used to specify the C++
350
+ standard library. [[structure]] describes the structure of the normative
351
+ [[support]] through [[thread]] and [[depr]]. [[conventions]] describes
352
+ other editorial conventions.
353
 
354
  ### Structure of each clause <a id="structure">[[structure]]</a>
355
 
356
  #### Elements <a id="structure.elements">[[structure.elements]]</a>
357
 
 
367
  The Summary provides a synopsis of the category, and introduces the
368
  first-level subclauses. Each subclause also provides a summary, listing
369
  the headers specified in the subclause and the library entities provided
370
  in each header.
371
 
 
 
 
372
  The contents of the summary and the detailed specifications include:
373
 
374
  - macros
375
  - values
376
+ - types and alias templates
377
  - classes and class templates
378
  - functions and function templates
379
+ - objects and variable templates
380
+ - concepts
381
 
382
  #### Requirements <a id="structure.requirements">[[structure.requirements]]</a>
383
 
384
+ Requirements describe constraints that shall be met by a C++ program
385
+ that extends the standard library. Such extensions are generally one of
386
+ the following:
387
 
388
  - Template arguments
389
  - Derived classes
390
  - Containers, iterators, and algorithms that meet an interface
391
+ convention or model a concept
392
 
393
  The string and iostream components use an explicit representation of
394
  operations required of template arguments. They use a class template
395
  `char_traits` to define these constraints.
396
 
397
  Interface convention requirements are stated as generally as possible.
398
+ Instead of stating “class `X` has to define a member function
399
  `operator++()`”, the interface requires “for any object `x` of class
400
  `X`, `++x` is defined”. That is, whether the operator is a member is
401
  unspecified.
402
 
403
  Requirements are stated in terms of well-defined expressions that define
404
+ valid terms of the types that meet the requirements. For every set of
405
+ well-defined expression requirements there is either a named concept or
406
+ a table that specifies an initial set of the valid expressions and their
407
+ semantics. Any generic algorithm [[algorithms]] that uses the
408
+ well-defined expression requirements is described in terms of the valid
409
+ expressions for its template type parameters.
410
+
411
+ The library specification uses a typographical convention for naming
412
+ requirements. Names in *italic* type that begin with the prefix *Cpp17*
413
+ refer to sets of well-defined expression requirements typically
414
+ presented in tabular form, possibly with additional prose semantic
415
+ requirements. For example, *Cpp17Destructible* ([[cpp17.destructible]])
416
+ is such a named requirement. Names in `constant width` type refer to
417
+ library concepts which are presented as a concept definition [[temp]],
418
+ possibly with additional prose semantic requirements. For example,
419
+ `destructible` [[concept.destructible]] is such a named requirement.
420
 
421
  Template argument requirements are sometimes referenced by name. See 
422
  [[type.descriptions]].
423
 
424
  In some cases the semantic requirements are presented as C++ code. Such
425
  code is intended as a specification of equivalence of a construct to
426
  another construct, not necessarily as the way the construct must be
427
  implemented.[^2]
428
 
429
+ Required operations of any concept defined in this document need not be
430
+ total functions; that is, some arguments to a required operation may
431
+ result in the required semantics failing to be met.
432
+
433
+ [*Example 1*: The required `<` operator of the `totally_ordered`
434
+ concept [[concept.totallyordered]] does not meet the semantic
435
+ requirements of that concept when operating on NaNs. — *end example*]
436
+
437
+ This does not affect whether a type models the concept.
438
+
439
+ A declaration may explicitly impose requirements through its associated
440
+ constraints [[temp.constr.decl]]. When the associated constraints refer
441
+ to a concept [[temp.concept]], the semantic constraints specified for
442
+ that concept are additionally imposed on the use of the declaration.
443
+
444
  #### Detailed specifications <a id="structure.specifications">[[structure.specifications]]</a>
445
 
446
  The detailed specifications each contain the following elements:
447
 
448
  - name and brief description
 
462
  - operators and other non-member functions
463
 
464
  Descriptions of function semantics contain the following elements (as
465
  appropriate):[^4]
466
 
467
+ - *Constraints:* the conditions for the function’s participation in
468
+ overload resolution [[over.match]]. \[*Note 1*: Failure to meet such a
469
+ condition results in the function’s silent
470
+ non-viability. — *end note*] \[*Example 1*: An implementation might
471
+ express such a condition via a *constraint-expression*
472
+ [[temp.constr.decl]]. *end example*]
473
+ - *Mandates:* the conditions that, if not met, render the program
474
+ ill-formed. \[*Example 2*: An implementation might express such a
475
+ condition via the *constant-expression* in a
476
+ *static_assert-declaration* [[dcl.pre]]. If the diagnostic is to be
477
+ emitted only after the function has been selected by overload
478
+ resolution, an implementation might express such a condition via a
479
+ *constraint-expression* [[temp.constr.decl]] and also define the
480
+ function as deleted. — *end example*]
481
+ - *Preconditions:* the conditions that the function assumes to hold
482
+ whenever it is called.
483
+ - *Effects:* the actions performed by the function.
484
+ - *Synchronization:* the synchronization operations
485
+ [[intro.multithread]] applicable to the function.
486
+ - *Ensures:* the conditions (sometimes termed observable results)
487
+ established by the function.
488
+ - *Returns:* a description of the value(s) returned by the function.
489
  - *Throws:* any exceptions thrown by the function, and the conditions
490
+ that would cause the exception.
491
+ - *Complexity:* the time and/or space complexity of the function.
492
+ - *Remarks:* additional semantic constraints on the function.
493
  - *Error conditions:* the error conditions for error codes reported by
494
+ the function.
495
 
496
+ Whenever the *Effects* element specifies that the semantics of some
497
  function `F` are *Equivalent to* some code sequence, then the various
498
+ elements are interpreted as follows. If `F`’s semantics specifies any
499
+ *Constraints* or *Mandates* elements, then those requirements are
500
+ logically imposed prior to the *equivalent-to* semantics. Next, the
501
+ semantics of the code sequence are determined by the *Constraints*,
502
+ *Mandates*, *Preconditions*, *Effects*, *Synchronization*,
503
+ *Postconditions*, *Returns*, *Throws*, *Complexity*, *Remarks*, and
504
+ *Error conditions* specified for the function invocations contained in
505
+ the code sequence. The value returned from `F` is specified by `F`’s
506
+ *Returns* element, or if `F` has no *Returns* element, a non-`void`
507
+ return from `F` is specified by the `return` statements [[stmt.return]]
508
+ in the code sequence. If `F`’s semantics contains a *Throws*,
509
+ *Postconditions*, or *Complexity* element, then that supersedes any
510
  occurrences of that element in the code sequence.
511
 
512
+ For non-reserved replacement and handler functions, [[support]]
513
+ specifies two behaviors for the functions in question: their required
514
+ and default behavior. The *default behavior* describes a function
515
+ definition provided by the implementation. The *required behavior*
516
+ describes the semantics of a function definition provided by either the
517
+ implementation or a C++ program. Where no distinction is explicitly made
518
+ in the description, the behavior described is the required behavior.
 
519
 
520
  If the formulation of a complexity requirement calls for a negative
521
  number of operations, the actual requirement is zero operations.[^5]
522
 
523
  Complexity requirements specified in the library clauses are upper
524
  bounds, and implementations that provide better complexity guarantees
525
+ meet the requirements.
526
 
527
  Error conditions specify conditions where a function may fail. The
528
  conditions are listed, together with a suitable explanation, as the
529
+ `enum class errc` constants [[syserr]].
530
 
531
  #### C library <a id="structure.see.also">[[structure.see.also]]</a>
532
 
533
+ Paragraphs labeled “<span class="smallcaps">See also</span>” contain
534
+ cross-references to the relevant portions of other standards
535
+ [[intro.refs]].
536
 
537
  ### Other conventions <a id="conventions">[[conventions]]</a>
538
 
539
  This subclause describes several editorial conventions used to describe
540
  the contents of the C++ standard library. These conventions are for
541
+ describing implementation-defined types [[type.descriptions]], and
542
+ member functions [[functions.within.classes]].
543
+
544
+ #### Exposition-only functions <a id="expos.only.func">[[expos.only.func]]</a>
545
+
546
+ Several function templates defined in [[support]] through [[thread]] and
547
+ [[depr]] are only defined for the purpose of exposition. The declaration
548
+ of such a function is followed by a comment ending in *exposition only*.
549
+
550
+ The following are defined for exposition only to aid in the
551
+ specification of the library:
552
+
553
+ ``` cpp
554
+ template<class T> constexpr decay_t<T> decay-copy(T&& v)
555
+ noexcept(is_nothrow_convertible_v<T, decay_t<T>>) // exposition only
556
+ { return std::forward<T>(v); }
557
+
558
+ constexpr auto synth-three-way =
559
+ []<class T, class U>(const T& t, const U& u)
560
+ requires requires {
561
+ { t < u } -> boolean-testable;
562
+ { u < t } -> boolean-testable;
563
+ }
564
+ {
565
+ if constexpr (three_way_comparable_with<T, U>) {
566
+ return t <=> u;
567
+ } else {
568
+ if (t < u) return weak_ordering::less;
569
+ if (u < t) return weak_ordering::greater;
570
+ return weak_ordering::equivalent;
571
+ }
572
+ };
573
+
574
+ template<class T, class U=T>
575
+ using synth-three-way-result = decltype(synth-three-way(declval<T&>(), declval<U&>()));
576
+ ```
577
 
578
  #### Type descriptions <a id="type.descriptions">[[type.descriptions]]</a>
579
 
580
  ##### General <a id="type.descriptions.general">[[type.descriptions.general]]</a>
581
 
582
  The Requirements subclauses may describe names that are used to specify
583
  constraints on template arguments.[^6] These names are used in library
584
+ Clauses to describe the types that may be supplied as arguments by a C++
585
+ program when instantiating template components from the library.
586
 
587
+ Certain types defined in [[input.output]] are used to describe
588
  implementation-defined types. They are based on other types, but with
589
  added constraints.
590
 
591
  ##### Exposition-only types <a id="expos.only.types">[[expos.only.types]]</a>
592
 
593
+ Several types defined in [[support]] through [[thread]] and [[depr]] are
594
+ defined for the purpose of exposition. The declaration of such a type is
 
 
595
  followed by a comment ending in *exposition only*.
596
 
597
  [*Example 1*:
598
 
599
  ``` cpp
 
607
 
608
  — *end example*]
609
 
610
  ##### Enumerated types <a id="enumerated.types">[[enumerated.types]]</a>
611
 
612
+ Several types defined in [[input.output]] are *enumerated types*. Each
613
+ enumerated type may be implemented as an enumeration or as a synonym for
614
+ an enumeration.[^7]
615
 
616
  The enumerated type `enumerated` can be written:
617
 
618
  ``` cpp
619
+ enum enumerated { V₀, V₁, V₂, V₃, };
620
 
621
  inline const enumerated C₀(V₀);
622
  inline const enumerated C₁(V₁);
623
  inline const enumerated C₂(V₂);
624
  inline const enumerated C₃(V₃);
625
+
626
  ```
627
 
628
  Here, the names `C₀`, `C₁`, etc. represent *enumerated elements* for
629
  this particular enumerated type. All such elements have distinct values.
630
 
631
  ##### Bitmask types <a id="bitmask.types">[[bitmask.types]]</a>
632
 
633
+ Several types defined in [[support]] through [[thread]] and [[depr]] are
634
+ *bitmask types*. Each bitmask type can be implemented as an enumerated
635
+ type that overloads certain operators, as an integer type, or as a
636
+ `bitset` [[template.bitset]].
637
 
638
+ The bitmask type `bitmask` can be written:
639
 
640
  ``` cpp
641
  // For exposition only.
642
  // int_type is an integral type capable of representing all values of the bitmask type.
643
  enum bitmask : int_type {
644
+ V₀ = 1 << 0, V₁ = 1 << 1, V₂ = 1 << 2, V₃ = 1 << 3,
645
  };
646
 
647
  inline constexpr bitmask C₀(V₀{});
648
  inline constexpr bitmask C₁(V₁{});
649
  inline constexpr bitmask C₂(V₂{});
650
  inline constexpr bitmask C₃(V₃{});
651
+
652
 
653
+ constexpr bitmask operator&(bitmask X, bitmask Y) {
654
+ return static_cast<bitmask>(
655
  static_cast<int_type>(X) & static_cast<int_type>(Y));
656
  }
657
+ constexpr bitmask operator|(bitmask X, bitmask Y) {
658
+ return static_cast<bitmask>(
659
  static_cast<int_type>(X) | static_cast<int_type>(Y));
660
  }
661
+ constexpr bitmask operator^(bitmask X, bitmask Y){
662
+ return static_cast<bitmask>(
663
  static_cast<int_type>(X) ^ static_cast<int_type>(Y));
664
  }
665
+ constexpr bitmask operator~(bitmask X){
666
+ return static_cast<bitmask>(~static_cast<int_type>(X));
667
  }
668
+ bitmask& operator&=(bitmask& X, bitmask Y){
669
  X = X & Y; return X;
670
  }
671
+ bitmask& operator|=(bitmask& X, bitmask Y) {
672
  X = X | Y; return X;
673
  }
674
+ bitmask& operator^=(bitmask& X, bitmask Y) {
675
  X = X ^ Y; return X;
676
  }
677
  ```
678
 
679
  Here, the names `C₀`, `C₁`, etc. represent *bitmask elements* for this
 
700
  basic execution character set.
701
  - The *decimal-point character* is the (single-byte) character used by
702
  functions that convert between a (single-byte) character sequence and
703
  a value of one of the floating-point types. It is used in the
704
  character sequence to denote the beginning of a fractional part. It is
705
+ represented in [[support]] through [[thread]] and [[depr]] by a
706
+ period, `'.'`, which is also its value in the `"C"` locale, but may
707
+ change during program execution by a call to
708
  `setlocale(int, const char*)`,[^8] or by a change to a `locale`
709
+ object, as described in [[locales]] and [[input.output]].
710
+ - A *character sequence* is an array object [[dcl.array]] `A` that can
711
+ be declared as `T A[N]`, where `T` is any of the types `char`,
712
+ `unsigned char`, or `signed char` [[basic.fundamental]], optionally
713
  qualified by any combination of `const` or `volatile`. The initial
714
  elements of the array have defined contents up to and including an
715
  element determined by some predicate. A character sequence can be
716
  designated by a pointer value `S` that points to its first element.
717
 
718
  ###### Byte strings <a id="byte.strings">[[byte.strings]]</a>
719
 
720
  A *null-terminated byte string*, or NTBS, is a character sequence whose
721
  highest-addressed element with defined content has the value zero (the
722
+ *terminating null character*); no other element in the sequence has the
723
  value zero. [^9]
724
 
725
+ The *length of an NTBS* is the number of elements that precede the
726
+ terminating null character. An *empty NTBS* has a length of zero.
727
 
728
+ The *value of an NTBS* is the sequence of values of the elements up to
729
  and including the terminating null character.
730
 
731
+ A *static NTBS* is an NTBS with static storage duration.[^10]
732
 
733
  ###### Multibyte strings <a id="multibyte.strings">[[multibyte.strings]]</a>
734
 
735
  A *null-terminated multibyte string*, or NTMBS, is an NTBS that
736
  constitutes a sequence of valid multibyte characters, beginning and
737
  ending in the initial shift state.[^11]
738
 
739
+ A *static NTMBS* is an NTMBS with static storage duration.
740
+
741
+ ##### Customization Point Object types <a id="customization.point.object">[[customization.point.object]]</a>
742
+
743
+ A *customization point object* is a function object [[function.objects]]
744
+ with a literal class type that interacts with program-defined types
745
+ while enforcing semantic requirements on that interaction.
746
+
747
+ The type of a customization point object, ignoring cv-qualifiers, shall
748
+ model `semiregular` [[concepts.object]].
749
+
750
+ All instances of a specific customization point object type shall be
751
+ equal [[concepts.equality]].
752
+
753
+ The type `T` of a customization point object shall model
754
+ `invocable<const T&, Args...>` [[concept.invocable]] when the types in
755
+ `Args...` meet the requirements specified in that customization point
756
+ object’s definition. When the types of `Args...` do not meet the
757
+ customization point object’s requirements, `T` shall not have a function
758
+ call operator that participates in overload resolution.
759
+
760
+ Each customization point object type constrains its return type to model
761
+ a particular concept.
762
+
763
+ [*Note 1*: Many of the customization point objects in the library
764
+ evaluate function call expressions with an unqualified name which
765
+ results in a call to a program-defined function found by argument
766
+ dependent name lookup [[basic.lookup.argdep]]. To preclude such an
767
+ expression resulting in a call to unconstrained functions with the same
768
+ name in namespace `std`, customization point objects specify that lookup
769
+ for these expressions is performed in a context that includes deleted
770
+ overloads matching the signatures of overloads defined in namespace
771
+ `std`. When the deleted overloads are viable, program-defined overloads
772
+ need be more specialized [[temp.func.order]] or more constrained
773
+ [[temp.constr.order]] to be used by a customization point
774
+ object. — *end note*]
775
 
776
  #### Functions within classes <a id="functions.within.classes">[[functions.within.classes]]</a>
777
 
778
+ For the sake of exposition, [[support]] through [[thread]] and [[depr]]
779
+ do not describe copy/move constructors, assignment operators, or
780
+ (non-virtual) destructors with the same apparent semantics as those that
781
+ can be generated by default ([[class.copy.ctor]],
782
+ [[class.copy.assign]], [[class.dtor]]). It is unspecified whether the
783
+ implementation provides explicit definitions for such member function
784
+ signatures, or for virtual destructors that can be generated by default.
 
 
 
 
 
 
 
 
 
785
 
786
  #### Private members <a id="objects.within.classes">[[objects.within.classes]]</a>
787
 
788
+ [[support]] through [[thread]] and [[depr]] do not specify the
789
+ representation of classes, and intentionally omit specification of class
790
+ members [[class.mem]]. An implementation may define static or non-static
791
+ class members, or both, as needed to implement the semantics of the
792
+ member functions specified in [[support]] through [[thread]] and
793
+ [[depr]].
794
 
795
  For the sake of exposition, some subclauses provide representative
796
  declarations, and semantic requirements, for private members of classes
797
  that meet the external specifications of the classes. The declarations
798
  for such members are followed by a comment that ends with *exposition
 
805
  An implementation may use any technique that provides equivalent
806
  observable behavior.
807
 
808
  ## Library-wide requirements <a id="requirements">[[requirements]]</a>
809
 
810
+ This subclause specifies requirements that apply to the entire C++
811
+ standard library. [[support]] through [[thread]] and [[depr]] specify
812
+ the requirements of individual entities within the library.
 
813
 
814
  Requirements specified in terms of interactions between threads do not
815
  apply to programs having only a single thread of execution.
816
 
817
  Within this subclause, [[organization]] describes the library’s contents
 
821
  [[constraints]] describes constraints on well-formed C++ programs, and
822
  [[conforming]] describes constraints on conforming implementations.
823
 
824
  ### Library contents and organization <a id="organization">[[organization]]</a>
825
 
826
+ [[contents]] describes the entities and macros defined in the C++
827
+ standard library. [[headers]] lists the standard library headers and
828
  some constraints on those headers. [[compliance]] lists requirements for
829
  a freestanding implementation of the C++ standard library.
830
 
831
  #### Library contents <a id="contents">[[contents]]</a>
832
 
833
+ The C++ standard library provides definitions for the entities and
834
+ macros described in the synopses of the C++ standard library headers
835
+ [[headers]], unless otherwise specified.
836
 
837
  All library entities except `operator new` and `operator delete` are
838
  defined within the namespace `std` or namespaces nested within namespace
839
  `std`.[^12] It is unspecified whether names declared in a specific
840
  namespace are declared directly in that namespace or in an inline
841
  namespace inside that namespace.[^13]
842
 
843
  Whenever a name `x` defined in the standard library is mentioned, the
844
  name `x` is assumed to be fully qualified as `::std::x`, unless
845
+ explicitly described otherwise. For example, if the *Effects:* element
846
  for library function `F` is described as calling library function `G`,
847
  the function `::std::G` is meant.
848
 
849
  #### Headers <a id="headers">[[headers]]</a>
850
 
851
  Each element of the C++ standard library is declared or defined (as
852
  appropriate) in a *header*.[^14]
853
 
854
  The C++ standard library provides the *C++ library headers*, shown in
855
+ [[headers.cpp]].
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
856
 
857
  The facilities of the C standard library are provided in the additional
858
+ headers shown in [[headers.cpp.c]]. [^15]
859
 
860
+ The headers listed in [[headers.cpp]], or, for a freestanding
861
+ implementation, the subset of such headers that are provided by the
862
+ implementation, are collectively known as the
863
+ *importable C++ library headers*.
864
 
865
+ [*Note 1*: Importable C++ library headers can be imported as module
866
+ units [[module.import]]. *end note*]
 
 
 
 
 
 
867
 
868
+ [*Example 1*:
869
 
870
+ ``` cpp
871
+ import <vector>; // imports the <vector> header unit
872
+ std::vector<int> vi; // OK
873
+ ```
874
+
875
+ *end example*]
876
+
877
+ Except as noted in [[library]] through [[thread]] and [[depr]], the
878
+ contents of each header `cname` is the same as that of the corresponding
879
+ header `name.h` as specified in the C standard library [[intro.refs]].
880
+ In the C++ standard library, however, the declarations (except for names
881
+ which are defined as macros in C) are within namespace scope
882
+ [[basic.scope.namespace]] of the namespace `std`. It is unspecified
883
+ whether these names (including any overloads added in [[support]]
884
+ through [[thread]] and [[depr]]) are first declared within the global
885
+ namespace scope and are then injected into namespace `std` by explicit
886
+ *using-declaration*s [[namespace.udecl]].
887
 
888
  Names which are defined as macros in C shall be defined as macros in the
889
  C++ standard library, even if C grants license for implementation as
890
  functions.
891
 
892
+ [*Note 2*: The names defined as macros in C include the following:
893
  `assert`, `offsetof`, `setjmp`, `va_arg`, `va_end`, and
894
  `va_start`. — *end note*]
895
 
896
  Names that are defined as functions in C shall be defined as functions
897
  in the C++ standard library.[^16]
898
 
899
+ Identifiers that are keywords or operators in C++ shall not be defined
900
+ as macros in C++ standard library headers.[^17]
901
 
902
  [[depr.c.headers]], C standard library headers, describes the effects of
903
  using the `name.h` (C header) form in a C++ program.[^18]
904
 
905
  Annex K of the C standard describes a large number of functions, with
 
910
  generally take an additional argument whose value is the size of the
911
  result array. If any C++ header is included, it is
912
  *implementation-defined* whether any of these names is declared in the
913
  global namespace. (None of them is declared in namespace `std`.)
914
 
915
+ [[c.annex.k.names]] lists the Annex K names that may be declared in some
916
+ header. These names are also subject to the restrictions of 
917
+ [[macro.names]].
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
918
 
919
  #### Freestanding implementations <a id="compliance">[[compliance]]</a>
920
 
921
+ Two kinds of implementations are defined: *hosted* and *freestanding*
922
+ [[intro.compliance]]; the kind of the implementation is
923
+ *implementation-defined*. For a hosted implementation, this document
924
+ describes the set of available headers.
925
 
926
  A freestanding implementation has an *implementation-defined* set of
927
+ headers. This set shall include at least the headers shown in
928
+ [[headers.cpp.fs]].
929
 
930
+ **Table: C++ headers for freestanding implementations** <a id="headers.cpp.fs">[headers.cpp.fs]</a>
931
 
932
  | Subclause | | Header |
933
+ | ---------------------- | ------------------------- | ------------------------------------------------ |
 
934
  | [[support.types]] | Types | `<cstddef>` |
935
+ | [[support.limits]] | Implementation properties | `<cfloat>`, `<climits>`, `<limits>`, `<version>` |
936
  | [[cstdint]] | Integer types | `<cstdint>` |
937
  | [[support.start.term]] | Start and termination | `<cstdlib>` |
938
  | [[support.dynamic]] | Dynamic memory management | `<new>` |
939
  | [[support.rtti]] | Type identification | `<typeinfo>` |
940
+ | [[support.srcloc]] | Source location | `<source_location>` |
941
  | [[support.exception]] | Exception handling | `<exception>` |
942
  | [[support.initlist]] | Initializer lists | `<initializer_list>` |
943
+ | [[cmp]] | Comparisons | `<compare>` |
944
+ | [[support.coroutine]] | Coroutines support | `<coroutine>` |
945
  | [[support.runtime]] | Other runtime support | `<cstdarg>` |
946
+ | [[concepts]] | Concepts library | `<concepts>` |
947
  | [[meta]] | Type traits | `<type_traits>` |
948
+ | [[bit]] | Bit manipulation | `<bit>` |
949
  | [[atomics]] | Atomics | `<atomic>` |
 
950
 
951
 
952
  The supplied version of the header `<cstdlib>` shall declare at least
953
  the functions `abort`, `atexit`, `at_quick_exit`, `exit`, and
954
+ `quick_exit` [[support.start.term]]. The supplied version of the header
955
+ `<atomic>` shall meet the same requirements as for a hosted
956
+ implementation except that support for always lock-free integral atomic
957
+ types [[atomics.lockfree]] is *implementation-defined*, and whether or
958
+ not the type aliases `atomic_signed_lock_free` and
959
+ `atomic_unsigned_lock_free` are defined [[atomics.alias]] is
960
+ *implementation-defined*. The other headers listed in this table shall
961
+ meet the same requirements as for a hosted implementation.
962
 
963
  ### Using the library <a id="using">[[using]]</a>
964
 
965
  #### Overview <a id="using.overview">[[using.overview]]</a>
966
 
967
+ Subclause [[using]] describes how a C++ program gains access to the
968
+ facilities of the C++ standard library. [[using.headers]] describes
969
+ effects during translation phase 4, while  [[using.linkage]] describes
970
+ effects during phase 8 [[lex.phases]].
971
 
972
  #### Headers <a id="using.headers">[[using.headers]]</a>
973
 
974
  The entities in the C++ standard library are defined in headers, whose
975
  contents are made available to a translation unit when it contains the
976
+ appropriate `#include` preprocessing directive [[cpp.include]] or the
977
+ appropriate `import` declaration [[module.import]].
978
 
979
+ A translation unit may include library headers in any order
980
+ [[lex.separate]]. Each may be included more than once, with no effect
981
+ different from being included exactly once, except that the effect of
982
+ including either `<cassert>` or `<assert.h>` depends each time on the
983
+ lexically current definition of `NDEBUG`.[^19]
984
 
985
  A translation unit shall include a header only outside of any
986
+ declaration or definition and, in the case of a module unit, only in its
987
+ *global-module-fragment*, and shall include the header or import the
988
+ corresponding header unit lexically before the first reference in that
989
+ translation unit to any of the entities declared in that header. No
990
+ diagnostic is required.
991
 
992
  #### Linkage <a id="using.linkage">[[using.linkage]]</a>
993
 
994
+ Entities in the C++ standard library have external linkage
995
+ [[basic.link]]. Unless otherwise specified, objects and functions have
996
+ the default `extern "C++"` linkage [[dcl.link]].
997
 
998
  Whether a name from the C standard library declared with external
999
  linkage has `extern "C"` or `extern "C++"` linkage is
1000
  *implementation-defined*. It is recommended that an implementation use
1001
  `extern "C++"` linkage for this purpose.[^20]
1002
 
1003
+ Objects and functions defined in the library and required by a C++
1004
+ program are included in the program prior to program startup.
1005
 
1006
+ See also replacement functions [[replacement.functions]], runtime
1007
+ changes [[handler.functions]].
1008
 
1009
  ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
1010
 
1011
  [[utility.arg.requirements]] describes requirements on types and
1012
  expressions used to instantiate templates defined in the C++ standard
 
1020
 
1021
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
1022
 
1023
  The template definitions in the C++ standard library refer to various
1024
  named requirements whose details are set out in Tables 
1025
+ [[tab:cpp17.equalitycomparable]]– [[tab:cpp17.destructible]]. In these
1026
+ tables, `T` is an object or reference type to be supplied by a C++
1027
+ program instantiating a template; `a`, `b`, and `c` are values of type
1028
+ (possibly `const`) `T`; `s` and `t` are modifiable lvalues of type `T`;
1029
+ `u` denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
1030
  lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
1031
 
1032
  In general, a default constructor is not required. Certain container
1033
  class member function signatures specify `T()` as a default argument.
1034
+ `T()` shall be a well-defined expression [[dcl.init]] if one of those
1035
+ signatures is called using the default argument [[dcl.fct.default]].
1036
 
1037
+ **Table: Cpp17EqualityComparable requirements** <a id="cpp17.equalitycomparable">[cpp17.equalitycomparable]</a>
1038
 
1039
  | Expression | Return type |
1040
  | ---------- | ----------- |
1041
  | `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`. |
1042
 
1043
+
1044
+ **Table: Cpp17LessThanComparable requirements** <a id="cpp17.lessthancomparable">[cpp17.lessthancomparable]</a>
1045
 
1046
  | Expression | Return type | Requirement |
1047
+ | ---------- | --------------------- | ------------------------------------------------------ |
1048
+ | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation [[alg.sorting]] |
1049
 
1050
+
1051
+ **Table: Cpp17DefaultConstructible requirements** <a id="cpp17.defaultconstructible">[cpp17.defaultconstructible]</a>
1052
 
1053
  | Expression | Post-condition |
1054
  | -------------- | ------------------------------------------------------------------- |
1055
  | `T t;` | object `t` is default-initialized |
1056
  | `T u{};` | object `u` is value-initialized or aggregate-initialized |
1057
  | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
1058
 
1059
+
1060
  [*Note 1*: `rv` must still meet the requirements of the library
1061
  component that is using it. The operations listed in those requirements
1062
  must work as specified whether `rv` has been moved from or
1063
  not. — *end note*]
1064
 
1065
+ **Table: Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible)** <a id="cpp17.copyconstructible">[cpp17.copyconstructible]</a>
1066
 
1067
  | Expression | Post-condition |
1068
  | ---------- | --------------------------------------------------------- |
1069
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
1070
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
1071
 
1072
+
1073
  [*Note 2*:  `rv` must still meet the requirements of the library
1074
  component that is using it, whether or not `t` and `rv` refer to the
1075
  same object. The operations listed in those requirements must work as
1076
  specified whether `rv` has been moved from or not. — *end note*]
1077
 
1078
+ **Table: Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable)** <a id="cpp17.copyassignable">[cpp17.copyassignable]</a>
1079
 
1080
  | Expression | Return type | Return value | Post-condition |
1081
  | ---------- | ----------- | ------------ | ------------------------------------------------------- |
1082
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
1083
 
1084
 
1085
+ [*Note 3*: Array types and non-object types are not
1086
+ *Cpp17Destructible*. — *end note*]
1087
 
1088
+ #### Swappable requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
 
 
 
 
 
1089
 
1090
  This subclause provides definitions for swappable types and expressions.
1091
  In these definitions, let `t` denote an expression of type `T`, and let
1092
  `u` denote an expression of type `U`.
1093
 
 
1100
  and
1101
  - the object referred to by `u` has the value originally held by `t`.
1102
 
1103
  The context in which `swap(t, u)` and `swap(u, t)` are evaluated shall
1104
  ensure that a binary non-member function named “swap” is selected via
1105
+ overload resolution [[over.match]] on a candidate set that includes:
1106
 
1107
+ - the two `swap` function templates defined in `<utility>` and
1108
+ - the lookup set produced by argument-dependent lookup
1109
+ [[basic.lookup.argdep]].
 
1110
 
1111
  [*Note 1*: If `T` and `U` are both fundamental types or arrays of
1112
  fundamental types and the declarations from the header `<utility>` are
1113
  in scope, the overall lookup set described above is equivalent to that
1114
  of the qualified name lookup applied to the expression `std::swap(t, u)`
 
1119
  appropriate evaluation context. — *end note*]
1120
 
1121
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
1122
  with any rvalue or lvalue, respectively, of type `T`.
1123
 
1124
+ A type `X` meeting any of the iterator requirements
1125
+ [[iterator.requirements]] meets the *Cpp17ValueSwappable* requirements
1126
+ if, for any dereferenceable object `x` of type `X`, `*x` is swappable.
 
1127
 
1128
  [*Example 1*:
1129
 
1130
  User code can ensure that the evaluation of `swap` calls is performed in
1131
  an appropriate context under the various conditions as follows:
 
1143
 
1144
  // Requires: lvalues of T shall be swappable.
1145
  template<class T>
1146
  void lv_swap(T& t1, T& t2) {
1147
  using std::swap;
1148
+ swap(t1, t2); // OK: uses swappable conditions for lvalues of type T
1149
+ }
1150
 
1151
  namespace N {
1152
  struct A { int m; };
1153
  struct Proxy { A* a; };
1154
  Proxy proxy(A& a) { return Proxy{ &a }; }
 
1171
  }
1172
  ```
1173
 
1174
  — *end example*]
1175
 
1176
+ #### *Cpp17NullablePointer* requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
1177
 
1178
+ A *Cpp17NullablePointer* type is a pointer-like type that supports null
1179
+ values. A type `P` meets the *Cpp17NullablePointer* requirements if:
1180
 
1181
+ - `P` meets the *Cpp17EqualityComparable*, *Cpp17DefaultConstructible*,
1182
+ *Cpp17CopyConstructible*, *Cpp17CopyAssignable*, and
1183
+ *Cpp17Destructible* requirements,
1184
+ - lvalues of type `P` are swappable [[swappable.requirements]],
1185
+ - the expressions shown in [[cpp17.nullablepointer]] are valid and have
1186
+ the indicated semantics, and
1187
+ - `P` meets all the other requirements of this subclause.
1188
 
1189
  A value-initialized object of type `P` produces the null value of the
1190
  type. The null value shall be equivalent only to itself. A
1191
  default-initialized object of type `P` may have an indeterminate value.
1192
 
1193
  [*Note 1*: Operations involving indeterminate values may cause
1194
  undefined behavior. — *end note*]
1195
 
1196
  An object `p` of type `P` can be contextually converted to `bool`
1197
+ [[conv]]. The effect shall be as if `p != nullptr` had been evaluated in
1198
+ place of `p`.
1199
 
1200
+ No operation which is part of the *Cpp17NullablePointer* requirements
1201
+ shall exit via an exception.
1202
 
1203
+ In [[cpp17.nullablepointer]], `u` denotes an identifier, `t` denotes a
1204
+ non-`const` lvalue of type `P`, `a` and `b` denote values of type
1205
+ (possibly `const`) `P`, and `np` denotes a value of type (possibly
1206
  `const`) `std::nullptr_t`.
1207
 
1208
+ **Table: Cpp17NullablePointer requirements** <a id="cpp17.nullablepointer">[cpp17.nullablepointer]</a>
1209
 
1210
+ | Expression | Return type | Operational semantics |
1211
+ | -------------- | ---------------------------------- | --------------------------- |
1212
+ | `P u(np);`<br> | | Ensures: `u == nullptr` |
1213
  | `P u = np;` | | |
1214
+ | `P(np)` | | Ensures: `P(np) == nullptr` |
1215
+ | `t = np` | `P&` | Ensures: `t == nullptr` |
1216
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
1217
  | `a == np` | contextually convertible to `bool` | `a == P()` |
1218
  | `np == a` | | |
1219
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
1220
  | `np != a` | | |
1221
 
1222
 
1223
+ #### *Cpp17Hash* requirements <a id="hash.requirements">[[hash.requirements]]</a>
1224
 
1225
+ A type `H` meets the requirements if:
1226
 
1227
+ - it is a function object type [[function.objects]],
1228
+ - it meets the *Cpp17CopyConstructible* ([[cpp17.copyconstructible]])
1229
+ and *Cpp17Destructible* ([[cpp17.destructible]]) requirements, and
1230
+ - the expressions shown in [[cpp17.hash]] are valid and have the
1231
  indicated semantics.
1232
 
1233
  Given `Key` is an argument type for function objects of type `H`, in
1234
+ [[cpp17.hash]] `h` is a value of type (possibly `const`) `H`, `u` is an
1235
+ lvalue of type `Key`, and `k` is a value of a type convertible to
1236
  (possibly `const`) `Key`.
1237
 
1238
  [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
1239
  value for `k` yield the same result for a given execution of the
1240
  program. — *end note*]
1241
 
1242
+ #### *Cpp17Allocator* requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
1243
 
1244
  The library describes a standard set of requirements for *allocators*,
1245
  which are class-type objects that encapsulate the information about an
1246
  allocation model. This information includes the knowledge of pointer
1247
  types, the type of their difference, the type of the size of objects in
1248
  this allocation model, as well as the memory allocation and deallocation
1249
+ primitives for it. All of the string types [[strings]], containers
1250
+ [[containers]] (except `array`), string buffers and string streams
1251
+ [[input.output]], and `match_results` [[re]] are parameterized in terms
1252
+ of allocators.
1253
 
1254
+ The class template `allocator_traits` [[allocator.traits]] supplies a
1255
+ uniform interface to all allocator types. [[allocator.req.var]]
1256
+ describes the types manipulated through allocators. [[cpp17.allocator]]
1257
+ describes the requirements on allocator types and thus on types used to
1258
+ instantiate `allocator_traits`. A requirement is optional if the last
1259
+ column of [[cpp17.allocator]] specifies a default for a given
1260
+ expression. Within the standard library `allocator_traits` template, an
1261
+ optional requirement that is not supplied by an allocator is replaced by
1262
+ the specified default expression. A user specialization of
1263
+ `allocator_traits` may provide different defaults and may provide
 
1264
  defaults for different requirements than the primary template. Within
1265
+ Tables  [[tab:allocator.req.var]] and  [[tab:cpp17.allocator]], the use
1266
+ of `move` and `forward` always refers to `std::move` and `std::forward`,
1267
+ respectively.
1268
 
1269
  [*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
1270
 
1271
  Note A: The member class template `rebind` in the table above is
1272
  effectively a typedef template.
 
1282
  `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
1283
  `Allocator::{}rebind<U>::other` by default. For allocator types that are
1284
  not template instantiations of the above form, no default is provided.
1285
 
1286
  Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
1287
+ `X` shall meet the *Cpp17CopyAssignable* requirements (
1288
+ [[cpp17.copyassignable]]) and the copy operation shall not throw
1289
  exceptions. If `X::propagate_on_container_move_assignment::value` is
1290
+ `true`, `X` shall meet the *Cpp17MoveAssignable* requirements (
1291
+ [[cpp17.moveassignable]]) and the move operation shall not throw
1292
  exceptions. If `X::propagate_on_container_swap::value` is `true`,
1293
+ lvalues of type `X` shall be swappable [[swappable.requirements]] and
1294
  the `swap` operation shall not throw exceptions.
1295
 
1296
+ An allocator type `X` shall meet the *Cpp17CopyConstructible*
1297
+ requirements ([[cpp17.copyconstructible]]). The `X::pointer`,
1298
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
1299
+ shall meet the *Cpp17NullablePointer* requirements (
1300
+ [[cpp17.nullablepointer]]). No constructor, comparison function, copy
1301
+ operation, move operation, or swap operation on these pointer types
1302
  shall exit via an exception. `X::pointer` and `X::const_pointer` shall
1303
+ also meet the requirements for a *Cpp17RandomAccessIterator*
1304
+ [[random.access.iterators]] and the additional requirement that, when
1305
+ `a` and `(a + n)` are dereferenceable pointer values for some integral
1306
+ value `n`,
1307
+
1308
+ ``` cpp
1309
+ addressof(*(a + n)) == addressof(*a) + n
1310
+ ```
1311
+
1312
+ is `true`.
1313
 
1314
  Let `x1` and `x2` denote objects of (possibly different) types
1315
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
1316
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
1317
  pointer values, if and only if both `x1` and `x2` can be explicitly
 
1350
  the arguments for which its `construct` or `destroy` members may be
1351
  called. If a type cannot be used with a particular allocator, the
1352
  allocator class or the call to `construct` or `destroy` may fail to
1353
  instantiate.
1354
 
1355
+ If the alignment associated with a specific over-aligned type is not
1356
+ supported by an allocator, instantiation of the allocator for that type
1357
+ may fail. The allocator also may silently ignore the requested
1358
+ alignment.
1359
+
1360
+ [*Note 3*: Additionally, the member function `allocate` for that type
1361
+ may fail by throwing an object of type `bad_alloc`. — *end note*]
1362
+
1363
  [*Example 1*:
1364
 
1365
  The following is an allocator class template supporting the minimal
1366
+ interface that meets the requirements of [[cpp17.allocator]]:
 
1367
 
1368
  ``` cpp
1369
  template<class Tp>
1370
  struct SimpleAllocator {
1371
  typedef Tp value_type;
1372
  SimpleAllocator(ctor args);
1373
 
1374
  template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
1375
 
1376
+ [[nodiscard]] Tp* allocate(std::size_t n);
1377
  void deallocate(Tp* p, std::size_t n);
1378
  };
1379
 
1380
  template<class T, class U>
1381
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
 
1383
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
1384
  ```
1385
 
1386
  — *end example*]
1387
 
 
 
 
 
 
 
 
 
1388
  ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
1389
 
1390
+ If `X` is an allocator class for type `T`, `X` additionally meets the
1391
+ allocator completeness requirements if, whether or not `T` is a complete
1392
+ type:
1393
 
1394
  - `X` is a complete type, and
1395
+ - all the member types of `allocator_traits<X>` [[allocator.traits]]
1396
  other than `value_type` are complete types.
1397
 
1398
  ### Constraints on programs <a id="constraints">[[constraints]]</a>
1399
 
1400
  #### Overview <a id="constraints.overview">[[constraints.overview]]</a>
1401
 
1402
+ Subclause [[constraints]] describes restrictions on C++ programs that
1403
+ use the facilities of the C++ standard library. The following subclauses
1404
+ specify constraints on the program’s use of namespaces
1405
+ [[namespace.std]], its use of various reserved names [[reserved.names]],
1406
+ its use of headers [[alt.headers]], its use of standard library classes
1407
+ as base classes [[derived.classes]], its definitions of replacement
1408
+ functions [[replacement.functions]], and its installation of handler
1409
+ functions during execution [[handler.functions]].
1410
 
1411
  #### Namespace use <a id="namespace.constraints">[[namespace.constraints]]</a>
1412
 
1413
  ##### Namespace `std` <a id="namespace.std">[[namespace.std]]</a>
1414
 
1415
+ Unless otherwise specified, the behavior of a C++ program is undefined
1416
+ if it adds declarations or definitions to namespace `std` or to a
1417
+ namespace within namespace `std`.
1418
+
1419
+ Unless explicitly prohibited, a program may add a template
1420
+ specialization for any standard library class template to namespace
1421
+ `std` provided that (a) the added declaration depends on at least one
1422
+ program-defined type and (b) the specialization meets the standard
1423
+ library requirements for the original template.[^21]
1424
+
1425
+ The behavior of a C++ program is undefined if it declares an explicit or
1426
+ partial specialization of any standard library variable template, except
1427
+ where explicitly permitted by the specification of that variable
1428
+ template.
1429
 
1430
  The behavior of a C++ program is undefined if it declares
1431
 
1432
  - an explicit specialization of any member function of a standard
1433
  library class template, or
 
1435
  standard library class or class template, or
1436
  - an explicit or partial specialization of any member class template of
1437
  a standard library class or class template, or
1438
  - a deduction guide for any standard library class template.
1439
 
1440
+ A program may explicitly instantiate a class template defined in the
1441
+ standard library only if the declaration (a) depends on the name of at
1442
+ least one program-defined type and (b) the instantiation meets the
1443
+ standard library requirements for the original template.
1444
+
1445
+ Let `F` denote a standard library function [[global.functions]], a
1446
+ standard library static member function, or an instantiation of a
1447
+ standard library function template. Unless `F` is designated an
1448
+ *addressable function*, the behavior of a C++ program is unspecified
1449
+ (possibly ill-formed) if it explicitly or implicitly attempts to form a
1450
+ pointer to `F`.
1451
+
1452
+ [*Note 1*: Possible means of forming such pointers include application
1453
+ of the unary `&` operator [[expr.unary.op]], `addressof`
1454
+ [[specialized.addressof]], or a function-to-pointer standard conversion
1455
+ [[conv.func]]. — *end note*]
1456
+
1457
+ Moreover, the behavior of a C++ program is unspecified (possibly
1458
+ ill-formed) if it attempts to form a reference to `F` or if it attempts
1459
+ to form a pointer-to-member designating either a standard library
1460
+ non-static member function [[member.functions]] or an instantiation of a
1461
+ standard library member function template.
1462
+
1463
+ Other than in namespace `std` or in a namespace within namespace `std`,
1464
+ a program may provide an overload for any library function template
1465
+ designated as a *customization point*, provided that (a) the overload’s
1466
+ declaration depends on at least one user-defined type and (b) the
1467
+ overload meets the standard library requirements for the customization
1468
+ point. [^22]
1469
+
1470
+ [*Note 2*: This permits a (qualified or unqualified) call to the
1471
+ customization point to invoke the most appropriate overload for the
1472
+ given arguments. — *end note*]
1473
 
1474
  A translation unit shall not declare namespace `std` to be an inline
1475
+ namespace [[namespace.def]].
1476
 
1477
  ##### Namespace `posix` <a id="namespace.posix">[[namespace.posix]]</a>
1478
 
1479
  The behavior of a C++ program is undefined if it adds declarations or
1480
  definitions to namespace `posix` or to a namespace within namespace
1481
  `posix` unless otherwise specified. The namespace `posix` is reserved
1482
  for use by ISO/IEC 9945 and other POSIX standards.
1483
 
1484
  ##### Namespaces for future standardization <a id="namespace.future">[[namespace.future]]</a>
1485
 
1486
+ Top-level namespaces whose *namespace-name* consists of `std` followed
1487
+ by one or more *digit*s [[lex.name]] are reserved for future
1488
+ standardization. The behavior of a C++ program is undefined if it adds
1489
+ declarations or definitions to such a namespace.
1490
 
1491
+ [*Example 1*: The top-level namespace `std2` is reserved for use by
1492
  future revisions of this International Standard. — *end example*]
1493
 
1494
  #### Reserved names <a id="reserved.names">[[reserved.names]]</a>
1495
 
1496
  The C++ standard library reserves the following kinds of names:
 
1507
 
1508
  In namespace `std`, the following names are reserved for previous
1509
  standardization:
1510
 
1511
  - `auto_ptr`,
1512
+ - `auto_ptr_ref`,
1513
  - `binary_function`,
1514
+ - `binary_negate`,
1515
  - `bind1st`,
1516
  - `bind2nd`,
1517
  - `binder1st`,
1518
  - `binder2nd`,
1519
  - `const_mem_fun1_ref_t`,
1520
  - `const_mem_fun1_t`,
1521
  - `const_mem_fun_ref_t`,
1522
  - `const_mem_fun_t`,
1523
+ - `get_temporary_buffer`,
1524
  - `get_unexpected`,
1525
+ - `gets`,
1526
+ - `is_literal_type`,
1527
+ - `is_literal_type_v`,
1528
  - `mem_fun1_ref_t`,
1529
  - `mem_fun1_t`,
1530
  - `mem_fun_ref_t`,
1531
  - `mem_fun_ref`,
1532
  - `mem_fun_t`,
1533
  - `mem_fun`,
1534
+ - `not1`,
1535
+ - `not2`,
1536
  - `pointer_to_binary_function`,
1537
  - `pointer_to_unary_function`,
1538
  - `ptr_fun`,
1539
  - `random_shuffle`,
1540
+ - `raw_storage_iterator`,
1541
+ - `result_of`,
1542
+ - `result_of_t`,
1543
+ - `return_temporary_buffer`,
1544
  - `set_unexpected`,
1545
  - `unary_function`,
1546
+ - `unary_negate`,
1547
+ - `uncaught_exception`,
1548
  - `unexpected`, and
1549
  - `unexpected_handler`.
1550
 
1551
+ The following names are reserved as member types for previous
1552
+ standardization, and may not be used as a name for object-like macros in
1553
+ portable code:
1554
+
1555
+ - `argument_type`,
1556
+ - `first_argument_type`,
1557
+ - `io_state`,
1558
+ - `open_mode`,
1559
+ - `second_argument_type`, and
1560
+ - `seek_dir`.
1561
+
1562
+ The name `stossc` is reserved as a member function for previous
1563
+ standardization, and may not be used as a name for function-like macros
1564
+ in portable code.
1565
+
1566
+ The header names `<ccomplex>`, `<ciso646>`, `<cstdalign>`, `<cstdbool>`,
1567
+ and `<ctgmath>` are reserved for previous standardization.
1568
+
1569
  ##### Macro names <a id="macro.names">[[macro.names]]</a>
1570
 
1571
  A translation unit that includes a standard library header shall not
1572
  `#define` or `#undef` names declared in any standard library header.
1573
 
1574
  A translation unit shall not `#define` or `#undef` names lexically
1575
+ identical to keywords, to the identifiers listed in
1576
+ [[lex.name.special]], or to the *attribute-token*s described in 
1577
+ [[dcl.attr]], except that the names `likely` and `unlikely` may be
1578
+ defined as function-like macros  [[cpp.replace]].
1579
 
1580
  ##### External linkage <a id="extern.names">[[extern.names]]</a>
1581
 
1582
  Each name declared as an object with external linkage in a header is
1583
  reserved to the implementation to designate that library object with
1584
+ external linkage, [^23] both in namespace `std` and in the global
1585
  namespace.
1586
 
1587
  Each global function signature declared with external linkage in a
1588
  header is reserved to the implementation to designate that function
1589
+ signature with external linkage.[^24]
1590
 
1591
  Each name from the C standard library declared with external linkage is
1592
  reserved to the implementation for use as a name with `extern "C"`
1593
  linkage, both in namespace `std` and in the global namespace.
1594
 
1595
  Each function signature from the C standard library declared with
1596
  external linkage is reserved to the implementation for use as a function
1597
+ signature with both `extern "C"` and `extern "C++"` linkage,[^25] or as
1598
  a name of namespace scope in the global namespace.
1599
 
1600
  ##### Types <a id="extern.types">[[extern.types]]</a>
1601
 
1602
+ For each type `T` from the C standard library, the types `::T` and
1603
  `std::T` are reserved to the implementation and, when defined, `::T`
1604
  shall be identical to `std::T`.
1605
 
1606
  ##### User-defined literal suffixes <a id="usrlit.suffix">[[usrlit.suffix]]</a>
1607
 
1608
+ Literal suffix identifiers [[over.literal]] that do not start with an
1609
  underscore are reserved for future standardization.
1610
 
1611
  #### Headers <a id="alt.headers">[[alt.headers]]</a>
1612
 
1613
  If a file with a name equivalent to the derived file name for one of the
1614
  C++ standard library headers is not provided as part of the
1615
  implementation, and a file with that name is placed in any of the
1616
+ standard places for a source file to be included [[cpp.include]], the
1617
  behavior is undefined.
1618
 
1619
  #### Derived classes <a id="derived.classes">[[derived.classes]]</a>
1620
 
1621
+ Virtual member function signatures defined for a base class in the C++
1622
+ standard library may be overridden in a derived class defined in the
1623
+ program [[class.virtual]].
1624
 
1625
  #### Replacement functions <a id="replacement.functions">[[replacement.functions]]</a>
1626
 
1627
+ [[support]] through [[thread]] and [[depr]] describe the behavior of
1628
+ numerous functions defined by the C++ standard library. Under some
1629
+ circumstances, however, certain of these function descriptions also
1630
+ apply to replacement functions defined in the program [[definitions]].
 
1631
 
1632
+ A C++ program may provide the definition for any of the following
1633
+ dynamic memory allocation function signatures declared in header
1634
+ `<new>` ([[basic.stc.dynamic]], [[new.syn]]):
1635
 
1636
  ``` cpp
1637
  operator new(std::size_t)
1638
  operator new(std::size_t, std::align_val_t)
1639
  operator new(std::size_t, const std::nothrow_t&)
 
1664
  operator delete[](void*, const std::nothrow_t&)
1665
  operator delete[](void*, std::align_val_t, const std::nothrow_t&)
1666
  ```
1667
 
1668
  The program’s definitions are used instead of the default versions
1669
+ supplied by the implementation [[new.delete]]. Such replacement occurs
1670
+ prior to program startup ([[basic.def.odr]], [[basic.start]]). The
1671
+ program’s declarations shall not be specified as `inline`. No diagnostic
1672
+ is required.
1673
 
1674
  #### Handler functions <a id="handler.functions">[[handler.functions]]</a>
1675
 
1676
  The C++ standard library provides a default version of the following
1677
+ handler function [[support]]:
1678
 
1679
  - `terminate_handler`
1680
 
1681
  A C++ program may install different handler functions during execution,
1682
  by supplying a pointer to a function defined in the program or the
 
1702
  #### Other functions <a id="res.on.functions">[[res.on.functions]]</a>
1703
 
1704
  In certain cases (replacement functions, handler functions, operations
1705
  on types used to instantiate standard library template components), the
1706
  C++ standard library depends on components supplied by a C++ program. If
1707
+ these components do not meet their requirements, this document places no
1708
+ requirements on the implementation.
1709
 
1710
  In particular, the effects are undefined in the following cases:
1711
 
1712
+ - For replacement functions [[new.delete]], if the installed replacement
1713
+ function does not implement the semantics of the applicable *Required
1714
+ behavior:* paragraph.
1715
+ - For handler functions ([[new.handler]], [[terminate.handler]]), if
1716
  the installed handler function does not implement the semantics of the
1717
+ applicable *Required behavior:* paragraph.
1718
+ - For types used as template arguments when instantiating a template
1719
  component, if the operations on the type do not implement the
1720
  semantics of the applicable *Requirements* subclause (
1721
  [[allocator.requirements]], [[container.requirements]],
1722
  [[iterator.requirements]], [[algorithms.requirements]],
1723
  [[numeric.requirements]]). Operations on such types can report a
1724
  failure by throwing an exception unless otherwise specified.
1725
+ - If any replacement function or handler function or destructor
1726
  operation exits via an exception, unless specifically allowed in the
1727
  applicable *Required behavior:* paragraph.
1728
+ - If an incomplete type [[basic.types]] is used as a template argument
1729
+ when instantiating a template component or evaluating a concept,
1730
+ unless specifically allowed for that component.
1731
 
1732
  #### Function arguments <a id="res.on.arguments">[[res.on.arguments]]</a>
1733
 
1734
  Each of the following applies to all arguments to functions defined in
1735
  the C++ standard library, unless explicitly stated otherwise.
 
1744
  fact valid.
1745
  - If a function argument binds to an rvalue reference parameter, the
1746
  implementation may assume that this parameter is a unique reference to
1747
  this argument. \[*Note 1*: If the parameter is a generic parameter of
1748
  the form `T&&` and an lvalue of type `A` is bound, the argument binds
1749
+ to an lvalue reference [[temp.deduct.call]] and thus is not covered by
1750
+ the previous sentence. — *end note*] \[*Note 2*: If a program casts
1751
+ an lvalue to an xvalue while passing that lvalue to a library function
1752
+ (e.g., by calling the function with the argument `std::move(x)`), the
1753
+ program is effectively asking that function to treat that lvalue as a
1754
+ temporary object. The implementation is free to optimize away aliasing
1755
+ checks which might be needed if the argument was an
1756
+ lvalue. — *end note*]
1757
 
1758
  #### Library object access <a id="res.on.objects">[[res.on.objects]]</a>
1759
 
1760
  The behavior of a program is undefined if calls to standard library
1761
  functions from different threads may introduce a data race. The
1762
  conditions under which this may occur are specified in 
1763
  [[res.on.data.races]].
1764
 
1765
  [*Note 1*: Modifying an object of a standard library type that is
1766
  shared between threads risks undefined behavior unless objects of that
1767
+ type are explicitly specified as being shareable without data races or
1768
  the user supplies a locking mechanism. — *end note*]
1769
 
1770
  If an object of a standard library type is accessed, and the beginning
1771
+ of the object’s lifetime [[basic.life]] does not happen before the
1772
  access, or the access does not happen before the end of the object’s
1773
  lifetime, the behavior is undefined unless otherwise specified.
1774
 
1775
  [*Note 2*: This applies even to objects such as mutexes intended for
1776
  thread synchronization. — *end note*]
1777
 
1778
+ #### Expects paragraph <a id="res.on.expects">[[res.on.expects]]</a>
1779
 
1780
+ Violation of any preconditions specified in a function’s
1781
+ *Preconditions:* element results in undefined behavior.
1782
+
1783
+ #### Semantic requirements <a id="res.on.requirements">[[res.on.requirements]]</a>
1784
+
1785
+ A sequence `Args` of template arguments is said to *model* a concept `C`
1786
+ if `Args` satisfies `C` [[temp.constr.decl]] and meets all semantic
1787
+ requirements (if any) given in the specification of `C`.
1788
+
1789
+ If the validity or meaning of a program depends on whether a sequence of
1790
+ template arguments models a concept, and the concept is satisfied but
1791
+ not modeled, the program is ill-formed, no diagnostic required.
1792
+
1793
+ If the semantic requirements of a declaration’s constraints
1794
+ [[structure.requirements]] are not modeled at the point of use, the
1795
+ program is ill-formed, no diagnostic required.
1796
 
1797
  ### Conforming implementations <a id="conforming">[[conforming]]</a>
1798
 
1799
  #### Overview <a id="conforming.overview">[[conforming.overview]]</a>
1800
 
1801
+ Subclause [[conforming]] describes the constraints upon, and latitude
1802
+ of, implementations of the C++ standard library.
1803
 
1804
  An implementation’s use of headers is discussed in  [[res.on.headers]],
1805
  its use of macros in  [[res.on.macro.definitions]], non-member functions
1806
  in  [[global.functions]], member functions in  [[member.functions]],
1807
  data race avoidance in  [[res.on.data.races]], access specifiers in 
1808
  [[protection.within.classes]], class derivation in  [[derivation]], and
1809
  exceptions in  [[res.on.exception.handling]].
1810
 
1811
  #### Headers <a id="res.on.headers">[[res.on.headers]]</a>
1812
 
1813
+ A C++ header may include other C++ headers. A C++ header shall provide
1814
+ the declarations and definitions that appear in its synopsis. A C++
1815
+ header shown in its synopsis as including other C++ headers shall
1816
+ provide the declarations and definitions that appear in the synopses of
1817
+ those other headers.
1818
 
1819
  Certain types and macros are defined in more than one header. Every such
1820
  entity shall be defined such that any header that defines it may be
1821
+ included after any other header that also defines it [[basic.def.odr]].
 
1822
 
1823
+ The C standard library headers [[depr.c.headers]] shall include only
1824
  their corresponding C++ standard library header, as described in 
1825
  [[headers]].
1826
 
1827
  #### Restrictions on macro definitions <a id="res.on.macro.definitions">[[res.on.macro.definitions]]</a>
1828
 
 
1835
  stated otherwise.
1836
 
1837
  #### Non-member functions <a id="global.functions">[[global.functions]]</a>
1838
 
1839
  It is unspecified whether any non-member functions in the C++ standard
1840
+ library are defined as inline [[dcl.inline]].
1841
 
1842
+ A call to a non-member function signature described in [[support]]
1843
+ through [[thread]] and [[depr]] shall behave as if the implementation
1844
+ declared no additional non-member function signatures.[^26]
 
1845
 
1846
  An implementation shall not declare a non-member function signature with
1847
  additional default arguments.
1848
 
1849
  Unless otherwise specified, calls made by functions in the standard
1850
  library to non-operator, non-member functions do not use functions from
1851
+ another namespace which are found through argument-dependent name lookup
1852
+ [[basic.lookup.argdep]].
1853
 
1854
  [*Note 1*:
1855
 
1856
  The phrase “unless otherwise specified” applies to cases such as the
1857
+ swappable with requirements [[swappable.requirements]]. The exception
1858
  for overloaded operators allows argument-dependent lookup in cases like
1859
+ that of `ostream_iterator::operator=` [[ostream.iterator.ops]]:
1860
 
1861
  *Effects:*
1862
 
1863
  ``` cpp
1864
  *out_stream << value;
 
1870
  — *end note*]
1871
 
1872
  #### Member functions <a id="member.functions">[[member.functions]]</a>
1873
 
1874
  It is unspecified whether any member functions in the C++ standard
1875
+ library are defined as inline [[dcl.inline]].
1876
 
1877
  For a non-virtual member function described in the C++ standard library,
1878
  an implementation may declare a different set of member function
1879
  signatures, provided that any call to the member function that would
1880
  select an overload from the set of declarations described in this
1881
+ document behaves as if that overload were selected.
1882
 
1883
  [*Note 1*: For instance, an implementation may add parameters with
1884
  default values, or replace a member function with default arguments with
1885
  two or more member functions with equivalent behavior, or add additional
1886
  signatures for a member function name. — *end note*]
1887
 
1888
+ #### Friend functions <a id="hidden.friends">[[hidden.friends]]</a>
1889
+
1890
+ Whenever this document specifies a friend declaration of a function or
1891
+ function template within a class or class template definition, that
1892
+ declaration shall be the only declaration of that function or function
1893
+ template provided by an implementation.
1894
+
1895
+ [*Note 1*: In particular, an implementation is not allowed to provide
1896
+ an additional declaration of that function or function template at
1897
+ namespace scope. — *end note*]
1898
+
1899
+ [*Note 2*: Such a friend function or function template declaration is
1900
+ known as a hidden friend, as it is visible neither to ordinary
1901
+ unqualified lookup [[basic.lookup.unqual]] nor to qualified lookup
1902
+ [[basic.lookup.qual]]. — *end note*]
1903
+
1904
  #### Constexpr functions and constructors <a id="constexpr.functions">[[constexpr.functions]]</a>
1905
 
1906
+ This document explicitly requires that certain standard library
1907
+ functions are `constexpr` [[dcl.constexpr]]. An implementation shall not
1908
+ declare any standard library function signature as `constexpr` except
1909
+ for those where it is explicitly required. Within any header that
1910
+ provides any non-defining declarations of constexpr functions or
1911
+ constructors an implementation shall provide corresponding definitions.
 
1912
 
1913
  #### Requirements for stable algorithms <a id="algorithm.stable">[[algorithm.stable]]</a>
1914
 
1915
  When the requirements for an algorithm state that it is “stable” without
1916
  further elaboration, it means:
1917
 
1918
+ - For the sort algorithms the relative order of equivalent elements is
1919
  preserved.
1920
+ - For the remove and copy algorithms the relative order of the elements
1921
+ that are not removed is preserved.
1922
+ - For the merge algorithms, for equivalent elements in the original two
1923
+ ranges, the elements from the first range (preserving their original
1924
+ order) precede the elements from the second range (preserving their
1925
+ original order).
1926
 
1927
  #### Reentrancy <a id="reentrancy">[[reentrancy]]</a>
1928
 
1929
+ Except where explicitly specified in this document, it is
1930
  *implementation-defined* which functions in the C++ standard library may
1931
  be recursively reentered.
1932
 
1933
  #### Data race avoidance <a id="res.on.data.races">[[res.on.data.races]]</a>
1934
 
1935
+ This subclause specifies requirements that implementations shall meet to
1936
+ prevent data races [[intro.multithread]]. Every standard library
1937
  function shall meet each requirement unless otherwise specified.
1938
  Implementations may prevent data races in cases other than those
1939
  specified below.
1940
 
1941
  A C++ standard library function shall not directly or indirectly access
1942
+ objects [[intro.multithread]] accessible by threads other than the
1943
  current thread unless the objects are accessed directly or indirectly
1944
  via the function’s arguments, including `this`.
1945
 
1946
  A C++ standard library function shall not directly or indirectly modify
1947
+ objects [[intro.multithread]] accessible by threads other than the
1948
  current thread unless the objects are accessed directly or indirectly
1949
  via the function’s non-const arguments, including `this`.
1950
 
1951
+ [*Note 1*: This means, for example, that implementations can’t use an
1952
+ object with static storage duration for internal purposes without
1953
+ synchronization because it could cause a data race even in programs that
1954
+ do not explicitly share objects between threads. — *end note*]
1955
 
1956
  A C++ standard library function shall not access objects indirectly
1957
  accessible via its arguments or via elements of its container arguments
1958
  except by invoking functions required by its specification on those
1959
  container elements.
 
1970
  the objects are not visible to users and are protected against data
1971
  races.
1972
 
1973
  Unless otherwise specified, C++ standard library functions shall perform
1974
  all operations solely within the current thread if those operations have
1975
+ effects that are visible [[intro.multithread]] to users.
1976
 
1977
  [*Note 3*: This allows implementations to parallelize operations if
1978
  there are no visible side effects. — *end note*]
1979
 
1980
  #### Protection within classes <a id="protection.within.classes">[[protection.within.classes]]</a>
1981
 
1982
  It is unspecified whether any function signature or class described in
1983
+ [[support]] through [[thread]] and [[depr]] is a friend of another class
1984
+ in the C++ standard library.
1985
 
1986
  #### Derived classes <a id="derivation">[[derivation]]</a>
1987
 
1988
+ An implementation may derive any class in the C++ standard library from
1989
+ a class with a name reserved to the implementation.
1990
 
1991
  Certain classes defined in the C++ standard library are required to be
1992
+ derived from other classes in the C++ standard library. An
1993
+ implementation may derive such a class directly from the required base
1994
+ or indirectly through a hierarchy of base classes with names reserved to
1995
+ the implementation.
1996
 
1997
  In any case:
1998
 
1999
  - Every base class described as `virtual` shall be virtual;
2000
  - Every base class not specified as `virtual` shall not be virtual;
 
2014
 
2015
  Functions from the C standard library shall not throw exceptions [^28]
2016
  except when such a function calls a program-supplied function that
2017
  throws an exception.[^29]
2018
 
2019
+ Destructor operations defined in the C++ standard library shall not
2020
+ throw exceptions. Every destructor in the C++ standard library shall
2021
+ behave as if it had a non-throwing exception specification.
2022
 
2023
  Functions defined in the C++ standard library that do not have a
2024
  *Throws:* paragraph but do have a potentially-throwing exception
2025
  specification may throw *implementation-defined* exceptions. [^30]
2026
  Implementations should report errors by throwing exceptions of or
 
2032
 
2033
  #### Restrictions on storage of pointers <a id="res.on.pointer.storage">[[res.on.pointer.storage]]</a>
2034
 
2035
  Objects constructed by the standard library that may hold a
2036
  user-supplied pointer value or an integer of type `std::intptr_t` shall
2037
+ store such values in a traceable pointer location
2038
+ [[basic.stc.dynamic.safety]].
2039
 
2040
  [*Note 1*: Other libraries are strongly encouraged to do the same,
2041
  since not doing so may result in accidental use of pointers that are not
2042
  safely derived. Libraries that store pointers outside the user’s address
2043
  space should make it appear that they are stored and retrieved from a
2044
  traceable pointer location. — *end note*]
2045
 
2046
  #### Value of error codes <a id="value.error.codes">[[value.error.codes]]</a>
2047
 
2048
  Certain functions in the C++ standard library report errors via a
2049
+ `std::error_code` [[syserr.errcode.overview]] object. That object’s
2050
  `category()` member shall return `std::system_category()` for errors
2051
  originating from the operating system, or a reference to an
2052
  *implementation-defined* `error_category` object for errors originating
2053
  elsewhere. The implementation shall define the possible values of
2054
  `value()` for each of these error categories.
2055
 
2056
  [*Example 1*: For operating systems that are based on POSIX,
2057
+ implementations should define the `std::system_category()` values as
2058
+ identical to the POSIX `errno` values, with additional values as defined
2059
+ by the operating system’s documentation. Implementations for operating
2060
+ systems that are not based on POSIX should define values identical to
2061
+ the operating system’s values. For errors that do not originate from the
2062
+ operating system, the implementation may provide enums for the
2063
+ associated values. — *end example*]
2064
 
2065
  #### Moved-from state of library types <a id="lib.types.movedfrom">[[lib.types.movedfrom]]</a>
2066
 
2067
+ Objects of types defined in the C++ standard library may be moved from
2068
+ [[class.copy.ctor]]. Move operations may be explicitly specified or
2069
  implicitly generated. Unless otherwise specified, such moved-from
2070
  objects shall be placed in a valid but unspecified state.
2071
 
2072
  <!-- Link reference definitions -->
2073
  [alg.c.library]: algorithms.md#alg.c.library
2074
  [alg.sorting]: algorithms.md#alg.sorting
2075
  [algorithm.stable]: #algorithm.stable
2076
  [algorithms]: algorithms.md#algorithms
2077
  [algorithms.requirements]: algorithms.md#algorithms.requirements
2078
+ [alloc.errors]: support.md#alloc.errors
2079
+ [allocator.req.var]: #allocator.req.var
2080
  [allocator.requirements]: #allocator.requirements
2081
  [allocator.requirements.completeness]: #allocator.requirements.completeness
2082
  [allocator.traits]: utilities.md#allocator.traits
2083
  [alt.headers]: #alt.headers
2084
  [atomics]: atomics.md#atomics
2085
+ [atomics.alias]: atomics.md#atomics.alias
2086
+ [atomics.lockfree]: atomics.md#atomics.lockfree
2087
+ [bad.alloc]: support.md#bad.alloc
2088
  [basic.def.odr]: basic.md#basic.def.odr
2089
  [basic.fundamental]: basic.md#basic.fundamental
2090
  [basic.life]: basic.md#basic.life
2091
  [basic.link]: basic.md#basic.link
2092
  [basic.lookup.argdep]: basic.md#basic.lookup.argdep
2093
+ [basic.lookup.qual]: basic.md#basic.lookup.qual
2094
+ [basic.lookup.unqual]: basic.md#basic.lookup.unqual
2095
  [basic.scope.namespace]: basic.md#basic.scope.namespace
2096
  [basic.start]: basic.md#basic.start
2097
  [basic.stc.dynamic]: basic.md#basic.stc.dynamic
2098
  [basic.stc.dynamic.safety]: basic.md#basic.stc.dynamic.safety
2099
  [basic.types]: basic.md#basic.types
2100
+ [bit]: numerics.md#bit
2101
  [bitmask.types]: #bitmask.types
2102
  [byte.strings]: #byte.strings
2103
+ [c.annex.k.names]: #c.annex.k.names
 
2104
  [character.seq]: #character.seq
2105
+ [class.copy.assign]: class.md#class.copy.assign
2106
+ [class.copy.ctor]: class.md#class.copy.ctor
2107
+ [class.dtor]: class.md#class.dtor
 
2108
  [class.mem]: class.md#class.mem
2109
  [class.mfct]: class.md#class.mfct
2110
  [class.this]: class.md#class.this
2111
  [class.virtual]: class.md#class.virtual
2112
+ [cmp]: support.md#cmp
2113
  [compliance]: #compliance
2114
+ [concept.destructible]: concepts.md#concept.destructible
2115
+ [concept.invocable]: concepts.md#concept.invocable
2116
+ [concept.totallyordered]: concepts.md#concept.totallyordered
2117
+ [concepts]: concepts.md#concepts
2118
+ [concepts.equality]: concepts.md#concepts.equality
2119
+ [concepts.object]: concepts.md#concepts.object
2120
  [conforming]: #conforming
2121
  [conforming.overview]: #conforming.overview
2122
  [constexpr.functions]: #constexpr.functions
2123
  [constraints]: #constraints
2124
  [constraints.overview]: #constraints.overview
2125
  [container.requirements]: containers.md#container.requirements
2126
  [containers]: containers.md#containers
2127
  [contents]: #contents
2128
+ [conv]: expr.md#conv
2129
+ [conv.func]: expr.md#conv.func
2130
  [conventions]: #conventions
2131
  [cpp.include]: cpp.md#cpp.include
2132
+ [cpp.replace]: cpp.md#cpp.replace
2133
+ [cpp17.allocator]: #cpp17.allocator
2134
+ [cpp17.copyassignable]: #cpp17.copyassignable
2135
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
2136
+ [cpp17.destructible]: #cpp17.destructible
2137
+ [cpp17.hash]: #cpp17.hash
2138
+ [cpp17.moveassignable]: #cpp17.moveassignable
2139
+ [cpp17.nullablepointer]: #cpp17.nullablepointer
2140
+ [cstdint]: support.md#cstdint
2141
+ [customization.point.object]: #customization.point.object
2142
  [dcl.array]: dcl.md#dcl.array
2143
  [dcl.attr]: dcl.md#dcl.attr
2144
  [dcl.constexpr]: dcl.md#dcl.constexpr
2145
  [dcl.fct.default]: dcl.md#dcl.fct.default
2146
  [dcl.init]: dcl.md#dcl.init
2147
  [dcl.init.list]: dcl.md#dcl.init.list
2148
  [dcl.inline]: dcl.md#dcl.inline
2149
  [dcl.link]: dcl.md#dcl.link
2150
+ [dcl.pre]: dcl.md#dcl.pre
2151
  [definitions]: #definitions
2152
  [depr]: future.md#depr
2153
  [depr.c.headers]: future.md#depr.c.headers
 
 
2154
  [derivation]: #derivation
2155
  [derived.classes]: #derived.classes
2156
  [description]: #description
2157
  [diagnostics]: diagnostics.md#diagnostics
2158
  [enumerated.types]: #enumerated.types
2159
  [except]: except.md#except
2160
+ [except.spec]: except.md#except.spec
2161
+ [expos.only.func]: #expos.only.func
2162
  [expos.only.types]: #expos.only.types
2163
  [expr.cond]: expr.md#expr.cond
2164
  [expr.const]: expr.md#expr.const
2165
  [expr.delete]: expr.md#expr.delete
2166
  [expr.eq]: expr.md#expr.eq
2167
  [expr.new]: expr.md#expr.new
2168
  [expr.rel]: expr.md#expr.rel
2169
+ [expr.spaceship]: expr.md#expr.spaceship
2170
+ [expr.unary.op]: expr.md#expr.unary.op
2171
  [extern.names]: #extern.names
2172
  [extern.types]: #extern.types
2173
  [function.objects]: utilities.md#function.objects
2174
  [functions.within.classes]: #functions.within.classes
2175
  [global.functions]: #global.functions
2176
  [handler.functions]: #handler.functions
2177
  [hash.requirements]: #hash.requirements
2178
  [headers]: #headers
2179
+ [headers.cpp]: #headers.cpp
2180
+ [headers.cpp.c]: #headers.cpp.c
2181
+ [headers.cpp.fs]: #headers.cpp.fs
2182
+ [hidden.friends]: #hidden.friends
2183
  [input.output]: input.md#input.output
2184
  [intro.compliance]: intro.md#intro.compliance
2185
  [intro.defs]: intro.md#intro.defs
2186
+ [intro.execution]: basic.md#intro.execution
2187
+ [intro.multithread]: basic.md#intro.multithread
2188
  [intro.refs]: intro.md#intro.refs
2189
  [iterator.requirements]: iterators.md#iterator.requirements
 
2190
  [iterators]: iterators.md#iterators
2191
+ [lex.name]: lex.md#lex.name
2192
+ [lex.name.special]: #lex.name.special
2193
  [lex.phases]: lex.md#lex.phases
2194
+ [lex.separate]: lex.md#lex.separate
2195
  [lib.types.movedfrom]: #lib.types.movedfrom
2196
  [library]: #library
2197
  [library.c]: #library.c
2198
+ [library.categories]: #library.categories
2199
  [library.general]: #library.general
2200
  [locales]: localization.md#locales
2201
  [localization]: localization.md#localization
2202
  [macro.names]: #macro.names
2203
  [member.functions]: #member.functions
2204
  [meta]: utilities.md#meta
2205
+ [module.import]: module.md#module.import
2206
  [multibyte.strings]: #multibyte.strings
2207
  [namespace.constraints]: #namespace.constraints
2208
  [namespace.def]: dcl.md#namespace.def
2209
  [namespace.future]: #namespace.future
2210
  [namespace.posix]: #namespace.posix
2211
  [namespace.std]: #namespace.std
2212
  [namespace.udecl]: dcl.md#namespace.udecl
2213
+ [new.delete]: support.md#new.delete
2214
+ [new.handler]: support.md#new.handler
2215
+ [new.syn]: support.md#new.syn
2216
  [nullablepointer.requirements]: #nullablepointer.requirements
2217
  [numeric.requirements]: numerics.md#numeric.requirements
2218
  [numerics]: numerics.md#numerics
2219
  [objects.within.classes]: #objects.within.classes
2220
  [organization]: #organization
 
2222
  [over.literal]: over.md#over.literal
2223
  [over.match]: over.md#over.match
2224
  [over.oper]: over.md#over.oper
2225
  [protection.within.classes]: #protection.within.classes
2226
  [random.access.iterators]: iterators.md#random.access.iterators
2227
+ [ranges]: ranges.md#ranges
2228
  [re]: re.md#re
2229
  [reentrancy]: #reentrancy
2230
  [replacement.functions]: #replacement.functions
2231
  [requirements]: #requirements
2232
  [res.on.arguments]: #res.on.arguments
2233
  [res.on.data.races]: #res.on.data.races
2234
  [res.on.exception.handling]: #res.on.exception.handling
2235
+ [res.on.expects]: #res.on.expects
2236
  [res.on.functions]: #res.on.functions
2237
  [res.on.headers]: #res.on.headers
2238
  [res.on.macro.definitions]: #res.on.macro.definitions
2239
  [res.on.objects]: #res.on.objects
2240
  [res.on.pointer.storage]: #res.on.pointer.storage
2241
+ [res.on.requirements]: #res.on.requirements
2242
  [reserved.names]: #reserved.names
2243
+ [specialized.addressof]: utilities.md#specialized.addressof
2244
  [std.exceptions]: diagnostics.md#std.exceptions
2245
+ [stmt.return]: stmt.md#stmt.return
2246
  [stream.types]: input.md#stream.types
2247
  [strings]: strings.md#strings
2248
  [structure]: #structure
2249
  [structure.elements]: #structure.elements
2250
  [structure.requirements]: #structure.requirements
2251
  [structure.see.also]: #structure.see.also
2252
  [structure.specifications]: #structure.specifications
2253
  [structure.summary]: #structure.summary
2254
+ [support]: support.md#support
2255
+ [support.coroutine]: support.md#support.coroutine
2256
+ [support.dynamic]: support.md#support.dynamic
2257
+ [support.exception]: support.md#support.exception
2258
+ [support.initlist]: support.md#support.initlist
2259
+ [support.limits]: support.md#support.limits
2260
+ [support.rtti]: support.md#support.rtti
2261
+ [support.runtime]: support.md#support.runtime
2262
+ [support.srcloc]: support.md#support.srcloc
2263
+ [support.start.term]: support.md#support.start.term
2264
+ [support.types]: support.md#support.types
2265
  [swappable.requirements]: #swappable.requirements
2266
  [syserr]: diagnostics.md#syserr
2267
  [syserr.errcode.overview]: diagnostics.md#syserr.errcode.overview
2268
+ [tab:allocator.req.var]: #tab:allocator.req.var
2269
+ [tab:cpp17.allocator]: #tab:cpp17.allocator
2270
+ [tab:cpp17.destructible]: #tab:cpp17.destructible
2271
+ [tab:cpp17.equalitycomparable]: #tab:cpp17.equalitycomparable
2272
+ [temp]: temp.md#temp
2273
+ [temp.concept]: temp.md#temp.concept
2274
+ [temp.constr.decl]: temp.md#temp.constr.decl
2275
+ [temp.constr.order]: temp.md#temp.constr.order
 
 
 
 
 
 
2276
  [temp.deduct.call]: temp.md#temp.deduct.call
2277
+ [temp.func.order]: temp.md#temp.func.order
2278
  [template.bitset]: utilities.md#template.bitset
2279
+ [terminate.handler]: support.md#terminate.handler
2280
  [thread]: thread.md#thread
2281
+ [time]: time.md#time
2282
  [type.descriptions]: #type.descriptions
2283
  [type.descriptions.general]: #type.descriptions.general
2284
  [using]: #using
2285
  [using.headers]: #using.headers
2286
  [using.linkage]: #using.linkage
2287
  [using.overview]: #using.overview
2288
  [usrlit.suffix]: #usrlit.suffix
2289
  [utilities]: utilities.md#utilities
 
2290
  [utility.arg.requirements]: #utility.arg.requirements
2291
  [utility.requirements]: #utility.requirements
2292
  [value.error.codes]: #value.error.codes
2293
  [zombie.names]: #zombie.names
2294
 
 
2301
 
2302
  [^3]: To save space, items that do not apply to a class are omitted. For
2303
  example, if a class does not specify any comparison functions, there
2304
  will be no “Comparison functions” subclause.
2305
 
2306
+ [^4]: To save space, elements that do not apply to a function are
2307
+ omitted. For example, if a function specifies no preconditions,
2308
+ there will be no *Preconditions:* element.
2309
 
2310
  [^5]: This simplifies the presentation of complexity requirements in
2311
  some cases.
2312
 
2313
  [^6]: Examples from  [[utility.requirements]] include:
2314
+ *Cpp17EqualityComparable*, *Cpp17LessThanComparable*,
2315
+ *Cpp17CopyConstructible*. Examples from  [[iterator.requirements]]
2316
+ include: *Cpp17InputIterator*, *Cpp17ForwardIterator*.
2317
 
2318
+ [^7]: Such as an integer type, with constant integer values
2319
+ [[basic.fundamental]].
2320
 
2321
+ [^8]: declared in `<clocale>`.
2322
 
2323
  [^9]: Many of the objects manipulated by function signatures declared in
2324
+ `<cstring>` are character sequences or NTBSs. The size of some of
2325
+ these character sequences is limited by a length value, maintained
2326
+ separately from the character sequence.
2327
 
2328
+ [^10]: A *string-literal*, such as `"abc"`, is a static NTBS.
2329
 
2330
  [^11]: An NTBS that contains characters only from the basic execution
2331
  character set is also an NTMBS. Each multibyte character then
2332
  consists of a single byte.
2333
 
2334
+ [^12]: The C standard library headers [[depr.c.headers]] also define
2335
+ names within the global namespace, while the C++ headers for C
2336
+ library facilities [[headers]] may also define names within the
2337
  global namespace.
2338
 
2339
  [^13]: This gives implementers freedom to use inline namespaces to
2340
  support multiple configurations of the library.
2341
 
2342
  [^14]: A header is not necessarily a source file, nor are the sequences
2343
  delimited by `<` and `>` in header names necessarily valid source
2344
+ file names [[cpp.include]].
2345
 
2346
  [^15]: It is intentional that there is no C++ header for any of these C
2347
  headers: `<stdatomic.h>`, `<stdnoreturn.h>`, `<threads.h>`.
2348
 
2349
  [^16]: This disallows the practice, allowed in C, of providing a masking
2350
  macro in addition to the function prototype. The only way to achieve
2351
  equivalent inline behavior in C++ is to provide a definition as an
2352
  extern inline function.
2353
 
2354
+ [^17]: In particular, including the standard header `<iso646.h>` has no
2355
+ effect.
2356
 
2357
  [^18]: The `".h"` headers dump all their names into the global
2358
  namespace, whereas the newer forms keep their names in namespace
2359
  `std`. Therefore, the newer forms are the preferred forms for all
2360
  uses except for C++ programs which are intended to be strictly
 
2366
  from the C standard library is by including the header that declares
2367
  it, notwithstanding the latitude granted in 7.1.4 of the C Standard.
2368
 
2369
  [^21]: Any library code that instantiates other library templates must
2370
  be prepared to work adequately with any user-supplied specialization
2371
+ that meets the minimum requirements of this document.
2372
 
2373
+ [^22]: Any library customization point must be prepared to work
2374
+ adequately with any user-defined overload that meets the minimum
2375
+ requirements of this document. Therefore an implementation may
2376
+ elect, under the as-if rule [[intro.execution]], to provide any
2377
+ customization point in the form of an instantiated function object
2378
+ [[function.objects]] even though the customization point’s
2379
+ specification is in the form of a function template. The template
2380
+ parameters of each such function object and the function parameters
2381
+ and return type of the object’s `operator()` must match those of the
2382
+ corresponding customization point’s specification.
2383
+
2384
+ [^23]: The list of such reserved names includes `errno`, declared or
2385
  defined in `<cerrno>`.
2386
 
2387
+ [^24]: The list of such reserved function signatures with external
2388
  linkage includes `setjmp(jmp_buf)`, declared or defined in
2389
  `<csetjmp>`, and `va_end(va_list)`, declared or defined in
2390
  `<cstdarg>`.
2391
 
2392
+ [^25]: The function signatures declared in `<cuchar>`, `<cwchar>`, and
2393
  `<cwctype>` are always reserved, notwithstanding the restrictions
2394
  imposed in subclause 4.5.1 of Amendment 1 to the C Standard for
2395
  these headers.
2396
 
 
 
 
 
2397
  [^26]: A valid C++ program always calls the expected library non-member
2398
  function. An implementation may also define additional non-member
2399
  functions that would otherwise not be called by a valid C++ program.
2400
 
2401
  [^27]: There is an implicit exception to this rule for types that are
2402
+ described as synonyms for basic integral types, such as `size_t`
2403
+ [[support.types]] and `streamoff` [[stream.types]].
2404
 
2405
  [^28]: That is, the C library functions can all be treated as if they
2406
  are marked `noexcept`. This allows implementations to make
2407
  performance optimizations based on the absence of exceptions at
2408
  runtime.
2409
 
2410
+ [^29]: The functions `qsort()` and `bsearch()` [[alg.c.library]] meet
2411
  this condition.
2412
 
2413
  [^30]: In particular, they can report a failure to allocate storage by
2414
  throwing an exception of type `bad_alloc`, or a class derived from
2415
+ `bad_alloc` [[bad.alloc]].