From Jason Turner

[strings]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpr2wvk_wn/{from.md → to.md} +1467 -1730
tmp/tmpr2wvk_wn/{from.md → to.md} RENAMED
@@ -1,136 +1,95 @@
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
- non-array POD ([[basic.types]]) type. Such types are called *char-like
7
- types*, and objects of char-like types are called *char-like objects* or
8
- simply *characters*.
9
-
10
- The following subclauses describe a character traits class, a string
11
- class, and null-terminated sequence utilities, as summarized in Table 
12
- [[tab:strings.lib.summary]].
13
-
14
- **Table: Strings library summary** <a id="tab:strings.lib.summary">[tab:strings.lib.summary]</a>
15
-
16
- | Subclause | | Header |
17
- | ------------------ | ---------------------------------- | --------------- |
18
- | [[char.traits]] | Character traits | `<string>` |
19
- | [[string.classes]] | String classes | `<string>` |
20
- | [[string.view]] | String view classes | `<string_view>` |
21
- | | | `<cctype>` |
22
- | | | `<cwctype>` |
23
- | [[c.strings]] | Null-terminated sequence utilities | `<cstring>` |
24
- | | | `<cwchar>` |
25
- | | | `<cstdlib>` |
26
- | | | `<cuchar>` |
27
 
 
 
 
28
 
29
  ## Character traits <a id="char.traits">[[char.traits]]</a>
30
 
31
  This subclause defines requirements on classes representing *character
32
  traits*, and defines a class template `char_traits<charT>`, along with
33
- four specializations, `char_traits<char>`, `char_traits<char16_t>`,
34
- `char_traits<char32_t>`, and `char_traits<wchar_t>`, that satisfy those
35
- requirements.
36
 
37
- Most classes specified in Clauses  [[string.classes]] and 
38
  [[input.output]] need a set of related types and functions to complete
39
  the definition of their semantics. These types and functions are
40
  provided as a set of member *typedef-name*s and functions in the
41
  template parameter `traits` used by each such template. This subclause
42
  defines the semantics of these members.
43
 
44
- To specialize those templates to generate a string or iostream class to
45
- handle a particular character container type `CharT`, that and its
46
- related character traits class `Traits` are passed as a pair of
47
- parameters to the string or iostream template as parameters `charT` and
48
- `traits`. `Traits::char_type` shall be the same as `CharT`.
49
-
50
- This subclause specifies a class template, `char_traits<charT>`, and
51
- four explicit specializations of it, `char_traits<{}char>`,
52
- `char_traits<char16_t>`, `char_traits<char32_t>`, and
53
- `char_traits<wchar_t>`, all of which appear in the header `<string>` and
54
- satisfy the requirements below.
55
 
56
  ### Character traits requirements <a id="char.traits.require">[[char.traits.require]]</a>
57
 
58
- In Table  [[tab:char.traits.require]], `X` denotes a Traits class
59
- defining types and functions for the character container type `CharT`;
60
- `c` and `d` denote values of type `CharT`; `p` and `q` denote values of
61
- type `const CharT*`; `s` denotes a value of type `CharT*`; `n`, `i` and
62
- `j` denote values of type `size_t`; `e` and `f` denote values of type
63
- `X::int_type`; `pos` denotes a value of type `X::pos_type`; `state`
64
- denotes a value of type `X::state_type`; and `r` denotes an lvalue of
65
- type `CharT`. Operations on Traits shall not throw exceptions.
66
 
67
  The class template
68
 
69
  ``` cpp
70
  template<class charT> struct char_traits;
71
  ```
72
 
73
- shall be provided in the header `<string>` as a basis for explicit
74
  specializations.
75
 
76
  ### Traits typedefs <a id="char.traits.typedefs">[[char.traits.typedefs]]</a>
77
 
78
  ``` cpp
79
- using char_type = CHAR_T;
80
  ```
81
 
82
- The type `char_type` is used to refer to the character container type in
83
- the implementation of the library classes defined in  [[string.classes]]
84
- and Clause  [[input.output]].
85
 
86
  ``` cpp
87
- using int_type = INT_T;
88
  ```
89
 
90
- *Requires:* For a certain character container type `char_type`, a
91
- related container type `INT_T` shall be a type or class which can
92
- represent all of the valid characters converted from the corresponding
93
- `char_type` values, as well as an end-of-file value, `eof()`. The type
94
- `int_type` represents a character container type which can hold
95
- end-of-file to be used as a return type of the iostream class member
96
- functions.[^1]
97
-
98
- ``` cpp
99
- using off_type = implementation-defined;
100
- using pos_type = implementation-defined;
101
- ```
102
-
103
- *Requires:* Requirements for `off_type` and `pos_type` are described
104
- in  [[iostreams.limits.pos]] and [[iostream.forward]].
105
-
106
- ``` cpp
107
- using state_type = STATE_T;
108
- ```
109
-
110
- *Requires:* `state_type` shall meet the requirements of `CopyAssignable`
111
- (Table  [[tab:copyassignable]]), `CopyConstructible`
112
- (Table  [[tab:copyconstructible]]), and `DefaultConstructible`
113
- (Table  [[tab:defaultconstructible]]) types.
114
 
115
  ### `char_traits` specializations <a id="char.traits.specializations">[[char.traits.specializations]]</a>
116
 
117
  ``` cpp
118
  namespace std {
119
  template<> struct char_traits<char>;
 
120
  template<> struct char_traits<char16_t>;
121
  template<> struct char_traits<char32_t>;
122
  template<> struct char_traits<wchar_t>;
123
  }
124
  ```
125
 
126
- The header `<string>` shall define four specializations of the class
127
- template `char_traits`: `char_traits<{}char>`, `char_traits<char16_t>`,
128
- `char_traits<char32_t>`, and `char_traits<wchar_t>`.
129
-
130
- The requirements for the members of these specializations are given in
131
- Clause  [[char.traits.require]].
132
 
133
  #### `struct char_traits<char>` <a id="char.traits.specializations.char">[[char.traits.specializations.char]]</a>
134
 
135
  ``` cpp
136
  namespace std {
@@ -138,138 +97,159 @@ namespace std {
138
  using char_type = char;
139
  using int_type = int;
140
  using off_type = streamoff;
141
  using pos_type = streampos;
142
  using state_type = mbstate_t;
 
143
 
144
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
145
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
146
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
147
 
148
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
149
  static constexpr size_t length(const char_type* s);
150
  static constexpr const char_type* find(const char_type* s, size_t n,
151
  const char_type& a);
152
- static char_type* move(char_type* s1, const char_type* s2, size_t n);
153
- static char_type* copy(char_type* s1, const char_type* s2, size_t n);
154
- static char_type* assign(char_type* s, size_t n, char_type a);
155
 
156
  static constexpr int_type not_eof(int_type c) noexcept;
157
  static constexpr char_type to_char_type(int_type c) noexcept;
158
  static constexpr int_type to_int_type(char_type c) noexcept;
159
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
160
  static constexpr int_type eof() noexcept;
161
  };
162
  }
163
  ```
164
 
165
- The defined types for `int_type`, `pos_type`, `off_type`, and
166
- `state_type` shall be `int`, `streampos`, `streamoff`, and `mbstate_t`
167
- respectively.
168
-
169
- The type `streampos` shall be an *implementation-defined* type that
170
- satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
171
- and [[iostream.forward]].
172
-
173
- The type `streamoff` shall be an *implementation-defined* type that
174
- satisfies the requirements for `off_type` in  [[iostreams.limits.pos]]
175
- and [[iostream.forward]].
176
-
177
  The type `mbstate_t` is defined in `<cwchar>` and can represent any of
178
  the conversion states that can occur in an *implementation-defined* set
179
  of supported multibyte character encoding rules.
180
 
181
- The two-argument member `assign` shall be defined identically to the
182
- built-in operator `=`. The two-argument members `eq` and `lt` shall be
183
- defined identically to the built-in operators `==` and `<` for type
184
  `unsigned char`.
185
 
186
- The member `eof()` shall return `EOF`.
187
 
188
- #### `struct char_traits<char16_t>` <a id="char.traits.specializations.char16_t">[[char.traits.specializations.char16_t]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
189
 
190
  ``` cpp
191
  namespace std {
192
  template<> struct char_traits<char16_t> {
193
  using char_type = char16_t;
194
  using int_type = uint_least16_t;
195
  using off_type = streamoff;
196
  using pos_type = u16streampos;
197
  using state_type = mbstate_t;
 
198
 
199
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
200
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
201
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
202
 
203
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
204
  static constexpr size_t length(const char_type* s);
205
  static constexpr const char_type* find(const char_type* s, size_t n,
206
  const char_type& a);
207
- static char_type* move(char_type* s1, const char_type* s2, size_t n);
208
- static char_type* copy(char_type* s1, const char_type* s2, size_t n);
209
- static char_type* assign(char_type* s, size_t n, char_type a);
210
 
211
  static constexpr int_type not_eof(int_type c) noexcept;
212
  static constexpr char_type to_char_type(int_type c) noexcept;
213
  static constexpr int_type to_int_type(char_type c) noexcept;
214
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
215
  static constexpr int_type eof() noexcept;
216
  };
217
  }
218
  ```
219
 
220
- The type `u16streampos` shall be an *implementation-defined* type that
221
- satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
222
- and [[iostream.forward]].
223
 
224
- The two-argument members `assign`, `eq`, and `lt` shall be defined
225
- identically to the built-in operators `=`, `==`, and `<` respectively.
226
 
227
- The member `eof()` shall return an *implementation-defined* constant
228
- that cannot appear as a valid UTF-16 code unit.
229
-
230
- #### `struct char_traits<char32_t>` <a id="char.traits.specializations.char32_t">[[char.traits.specializations.char32_t]]</a>
231
 
232
  ``` cpp
233
  namespace std {
234
  template<> struct char_traits<char32_t> {
235
  using char_type = char32_t;
236
  using int_type = uint_least32_t;
237
  using off_type = streamoff;
238
  using pos_type = u32streampos;
239
  using state_type = mbstate_t;
 
240
 
241
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
242
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
243
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
244
 
245
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
246
  static constexpr size_t length(const char_type* s);
247
  static constexpr const char_type* find(const char_type* s, size_t n,
248
  const char_type& a);
249
- static char_type* move(char_type* s1, const char_type* s2, size_t n);
250
- static char_type* copy(char_type* s1, const char_type* s2, size_t n);
251
- static char_type* assign(char_type* s, size_t n, char_type a);
252
 
253
  static constexpr int_type not_eof(int_type c) noexcept;
254
  static constexpr char_type to_char_type(int_type c) noexcept;
255
  static constexpr int_type to_int_type(char_type c) noexcept;
256
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
257
  static constexpr int_type eof() noexcept;
258
  };
259
  }
260
  ```
261
 
262
- The type `u32streampos` shall be an *implementation-defined* type that
263
- satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
264
- and [[iostream.forward]].
265
 
266
- The two-argument members `assign`, `eq`, and `lt` shall be defined
267
- identically to the built-in operators `=`, `==`, and `<` respectively.
268
-
269
- The member `eof()` shall return an *implementation-defined* constant
270
- that cannot appear as a Unicode code point.
271
 
272
  #### `struct char_traits<wchar_t>` <a id="char.traits.specializations.wchar.t">[[char.traits.specializations.wchar.t]]</a>
273
 
274
  ``` cpp
275
  namespace std {
@@ -277,179 +257,134 @@ namespace std {
277
  using char_type = wchar_t;
278
  using int_type = wint_t;
279
  using off_type = streamoff;
280
  using pos_type = wstreampos;
281
  using state_type = mbstate_t;
 
282
 
283
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
284
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
285
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
286
 
287
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
288
  static constexpr size_t length(const char_type* s);
289
  static constexpr const char_type* find(const char_type* s, size_t n,
290
  const char_type& a);
291
- static char_type* move(char_type* s1, const char_type* s2, size_t n);
292
- static char_type* copy(char_type* s1, const char_type* s2, size_t n);
293
- static char_type* assign(char_type* s, size_t n, char_type a);
294
 
295
  static constexpr int_type not_eof(int_type c) noexcept;
296
  static constexpr char_type to_char_type(int_type c) noexcept;
297
  static constexpr int_type to_int_type(char_type c) noexcept;
298
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
299
  static constexpr int_type eof() noexcept;
300
  };
301
  }
302
  ```
303
 
304
- The defined types for `int_type`, `pos_type`, and `state_type` shall be
305
- `wint_t`, `wstreampos`, and `mbstate_t` respectively.
306
 
307
- The type `wstreampos` shall be an *implementation-defined* type that
308
- satisfies the requirements for `pos_type` in  [[iostreams.limits.pos]]
309
- and [[iostream.forward]].
310
-
311
- The type `mbstate_t` is defined in `<cwchar>` and can represent any of
312
- the conversion states that can occur in an *implementation-defined* set
313
- of supported multibyte character encoding rules.
314
-
315
- The two-argument members `assign`, `eq`, and `lt` shall be defined
316
- identically to the built-in operators `=`, `==`, and `<` respectively.
317
-
318
- The member `eof()` shall return `WEOF`.
319
 
320
  ## String classes <a id="string.classes">[[string.classes]]</a>
321
 
322
  The header `<string>` defines the `basic_string` class template for
323
- manipulating varying-length sequences of char-like objects and four
324
- *typedef-name*s, `string`, `u16string`, `u32string`, and `wstring`, that
325
- name the specializations `basic_string<char>`, `basic_string<char16_t>`,
 
326
  `basic_string<char32_t>`, and `basic_string<{}wchar_t>`, respectively.
327
 
328
  ### Header `<string>` synopsis <a id="string.syn">[[string.syn]]</a>
329
 
330
  ``` cpp
331
- #include <initializer_list>
 
332
 
333
  namespace std {
334
  // [char.traits], character traits
335
  template<class charT> struct char_traits;
336
  template<> struct char_traits<char>;
 
337
  template<> struct char_traits<char16_t>;
338
  template<> struct char_traits<char32_t>;
339
  template<> struct char_traits<wchar_t>;
340
 
341
  // [basic.string], basic_string
342
- template<class charT, class traits = char_traits<charT>,
343
- class Allocator = allocator<charT>>
344
  class basic_string;
345
 
346
  template<class charT, class traits, class Allocator>
347
- basic_string<charT, traits, Allocator>
348
  operator+(const basic_string<charT, traits, Allocator>& lhs,
349
  const basic_string<charT, traits, Allocator>& rhs);
350
  template<class charT, class traits, class Allocator>
351
- basic_string<charT, traits, Allocator>
352
  operator+(basic_string<charT, traits, Allocator>&& lhs,
353
  const basic_string<charT, traits, Allocator>& rhs);
354
  template<class charT, class traits, class Allocator>
355
- basic_string<charT, traits, Allocator>
356
  operator+(const basic_string<charT, traits, Allocator>& lhs,
357
  basic_string<charT, traits, Allocator>&& rhs);
358
  template<class charT, class traits, class Allocator>
359
- basic_string<charT, traits, Allocator>
360
  operator+(basic_string<charT, traits, Allocator>&& lhs,
361
  basic_string<charT, traits, Allocator>&& rhs);
362
  template<class charT, class traits, class Allocator>
363
- basic_string<charT, traits, Allocator>
364
  operator+(const charT* lhs,
365
  const basic_string<charT, traits, Allocator>& rhs);
366
  template<class charT, class traits, class Allocator>
367
- basic_string<charT, traits, Allocator>
368
  operator+(const charT* lhs,
369
  basic_string<charT, traits, Allocator>&& rhs);
370
  template<class charT, class traits, class Allocator>
371
- basic_string<charT, traits, Allocator>
372
- operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);
 
373
  template<class charT, class traits, class Allocator>
374
- basic_string<charT, traits, Allocator>
375
- operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);
 
376
  template<class charT, class traits, class Allocator>
377
- basic_string<charT, traits, Allocator>
378
  operator+(const basic_string<charT, traits, Allocator>& lhs,
379
  const charT* rhs);
380
  template<class charT, class traits, class Allocator>
381
- basic_string<charT, traits, Allocator>
382
  operator+(basic_string<charT, traits, Allocator>&& lhs,
383
  const charT* rhs);
384
  template<class charT, class traits, class Allocator>
385
- basic_string<charT, traits, Allocator>
386
- operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);
 
387
  template<class charT, class traits, class Allocator>
388
- basic_string<charT, traits, Allocator>
389
- operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);
 
390
 
391
  template<class charT, class traits, class Allocator>
392
- bool operator==(const basic_string<charT, traits, Allocator>& lhs,
393
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
394
- template<class charT, class traits, class Allocator>
395
- bool operator==(const charT* lhs,
396
- const basic_string<charT, traits, Allocator>& rhs);
397
- template<class charT, class traits, class Allocator>
398
- bool operator==(const basic_string<charT, traits, Allocator>& lhs,
399
- const charT* rhs);
400
- template<class charT, class traits, class Allocator>
401
- bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
402
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
403
  template<class charT, class traits, class Allocator>
404
- bool operator!=(const charT* lhs,
405
- const basic_string<charT, traits, Allocator>& rhs);
406
- template<class charT, class traits, class Allocator>
407
- bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
408
  const charT* rhs);
409
 
410
  template<class charT, class traits, class Allocator>
411
- bool operator< (const basic_string<charT, traits, Allocator>& lhs,
412
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
413
  template<class charT, class traits, class Allocator>
414
- bool operator< (const basic_string<charT, traits, Allocator>& lhs,
415
- const charT* rhs);
416
- template<class charT, class traits, class Allocator>
417
- bool operator< (const charT* lhs,
418
- const basic_string<charT, traits, Allocator>& rhs);
419
- template<class charT, class traits, class Allocator>
420
- bool operator> (const basic_string<charT, traits, Allocator>& lhs,
421
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
422
- template<class charT, class traits, class Allocator>
423
- bool operator> (const basic_string<charT, traits, Allocator>& lhs,
424
- const charT* rhs);
425
- template<class charT, class traits, class Allocator>
426
- bool operator> (const charT* lhs,
427
- const basic_string<charT, traits, Allocator>& rhs);
428
-
429
- template<class charT, class traits, class Allocator>
430
- bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
431
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
432
- template<class charT, class traits, class Allocator>
433
- bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
434
- const charT* rhs);
435
- template<class charT, class traits, class Allocator>
436
- bool operator<=(const charT* lhs,
437
- const basic_string<charT, traits, Allocator>& rhs);
438
- template<class charT, class traits, class Allocator>
439
- bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
440
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
441
- template<class charT, class traits, class Allocator>
442
- bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
443
- const charT* rhs);
444
- template<class charT, class traits, class Allocator>
445
- bool operator>=(const charT* lhs,
446
- const basic_string<charT, traits, Allocator>& rhs);
447
 
448
  // [string.special], swap
449
  template<class charT, class traits, class Allocator>
450
- void swap(basic_string<charT, traits, Allocator>& lhs,
 
451
  basic_string<charT, traits, Allocator>& rhs)
452
  noexcept(noexcept(lhs.swap(rhs)));
453
 
454
  // [string.io], inserters and extractors
455
  template<class charT, class traits, class Allocator>
@@ -477,78 +412,94 @@ namespace std {
477
  template<class charT, class traits, class Allocator>
478
  basic_istream<charT, traits>&
479
  getline(basic_istream<charT, traits>&& is,
480
  basic_string<charT, traits, Allocator>& str);
481
 
 
 
 
 
 
 
 
 
482
  // basic_string typedef names
483
  using string = basic_string<char>;
 
484
  using u16string = basic_string<char16_t>;
485
  using u32string = basic_string<char32_t>;
486
  using wstring = basic_string<wchar_t>;
487
 
488
  // [string.conversions], numeric conversions
489
- int stoi(const string& str, size_t* idx = 0, int base = 10);
490
- long stol(const string& str, size_t* idx = 0, int base = 10);
491
- unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
492
- long long stoll(const string& str, size_t* idx = 0, int base = 10);
493
- unsigned long long stoull(const string& str, size_t* idx = 0, int base = 10);
494
- float stof(const string& str, size_t* idx = 0);
495
- double stod(const string& str, size_t* idx = 0);
496
- long double stold(const string& str, size_t* idx = 0);
497
  string to_string(int val);
498
  string to_string(unsigned val);
499
  string to_string(long val);
500
  string to_string(unsigned long val);
501
  string to_string(long long val);
502
  string to_string(unsigned long long val);
503
  string to_string(float val);
504
  string to_string(double val);
505
  string to_string(long double val);
506
 
507
- int stoi(const wstring& str, size_t* idx = 0, int base = 10);
508
- long stol(const wstring& str, size_t* idx = 0, int base = 10);
509
- unsigned long stoul(const wstring& str, size_t* idx = 0, int base = 10);
510
- long long stoll(const wstring& str, size_t* idx = 0, int base = 10);
511
- unsigned long long stoull(const wstring& str, size_t* idx = 0, int base = 10);
512
- float stof(const wstring& str, size_t* idx = 0);
513
- double stod(const wstring& str, size_t* idx = 0);
514
- long double stold(const wstring& str, size_t* idx = 0);
515
  wstring to_wstring(int val);
516
  wstring to_wstring(unsigned val);
517
  wstring to_wstring(long val);
518
  wstring to_wstring(unsigned long val);
519
  wstring to_wstring(long long val);
520
  wstring to_wstring(unsigned long long val);
521
  wstring to_wstring(float val);
522
  wstring to_wstring(double val);
523
  wstring to_wstring(long double val);
524
 
525
- // [basic.string.hash], hash support
526
- template<class T> struct hash;
527
- template<> struct hash<string>;
528
- template<> struct hash<u16string>;
529
- template<> struct hash<u32string>;
530
- template<> struct hash<wstring>;
531
-
532
  namespace pmr {
533
  template<class charT, class traits = char_traits<charT>>
534
- using basic_string =
535
- std::basic_string<charT, traits, polymorphic_allocator<charT>>;
536
 
537
  using string = basic_string<char>;
 
538
  using u16string = basic_string<char16_t>;
539
  using u32string = basic_string<char32_t>;
540
  using wstring = basic_string<wchar_t>;
541
  }
542
 
 
 
 
 
 
 
 
 
 
 
 
 
 
543
  inline namespace literals {
544
  inline namespace string_literals {
545
  // [basic.string.literals], suffix for basic_string literals
546
- string operator""s(const char* str, size_t len);
547
- u16string operator""s(const char16_t* str, size_t len);
548
- u32string operator""s(const char32_t* str, size_t len);
549
- wstring operator""s(const wchar_t* str, size_t len);
 
550
  }
551
  }
552
  }
553
  ```
554
 
@@ -560,34 +511,24 @@ with the first element of the sequence at position zero. Such a sequence
560
  is also called a “string” if the type of the char-like objects that it
561
  holds is clear from context. In the rest of this Clause, the type of the
562
  char-like objects held in a `basic_string` object is designated by
563
  `charT`.
564
 
565
- The member functions of `basic_string` use an object of the `Allocator`
566
- class passed as a template parameter to allocate and free storage for
567
- the contained char-like objects.[^2]
568
 
569
- A `basic_string` is a contiguous container (
570
- [[container.requirements.general]]).
571
-
572
- In all cases, `size() <= capacity()`.
573
-
574
- The functions described in this Clause can report two kinds of errors,
575
- each associated with an exception type:
576
-
577
- - a *length* error is associated with exceptions of type
578
- `length_error` ([[length.error]]);
579
- - an *out-of-range* error is associated with exceptions of type
580
- `out_of_range` ([[out.of.range]]).
581
 
582
  ``` cpp
583
  namespace std {
584
  template<class charT, class traits = char_traits<charT>,
585
  class Allocator = allocator<charT>>
586
  class basic_string {
587
  public:
588
- // types:
589
  using traits_type = traits;
590
  using value_type = charT;
591
  using allocator_type = Allocator;
592
  using size_type = typename allocator_traits<Allocator>::size_type;
593
  using difference_type = typename allocator_traits<Allocator>::difference_type;
@@ -601,479 +542,434 @@ namespace std {
601
  using reverse_iterator = std::reverse_iterator<iterator>;
602
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
603
  static const size_type npos = -1;
604
 
605
  // [string.cons], construct/copy/destroy
606
- basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
607
- explicit basic_string(const Allocator& a) noexcept;
608
- basic_string(const basic_string& str);
609
- basic_string(basic_string&& str) noexcept;
610
- basic_string(const basic_string& str, size_type pos,
611
  const Allocator& a = Allocator());
612
- basic_string(const basic_string& str, size_type pos, size_type n,
613
  const Allocator& a = Allocator());
614
  template<class T>
615
- basic_string(const T& t, size_type pos, size_type n,
616
  const Allocator& a = Allocator());
617
- explicit basic_string(basic_string_view<charT, traits> sv,
618
- const Allocator& a = Allocator());
619
- basic_string(const charT* s,
620
- size_type n, const Allocator& a = Allocator());
621
- basic_string(const charT* s, const Allocator& a = Allocator());
622
- basic_string(size_type n, charT c, const Allocator& a = Allocator());
623
  template<class InputIterator>
624
- basic_string(InputIterator begin, InputIterator end,
625
  const Allocator& a = Allocator());
626
- basic_string(initializer_list<charT>, const Allocator& = Allocator());
627
- basic_string(const basic_string&, const Allocator&);
628
- basic_string(basic_string&&, const Allocator&);
 
629
 
630
- ~basic_string();
631
- basic_string& operator=(const basic_string& str);
632
- basic_string& operator=(basic_string&& str)
633
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
634
  allocator_traits<Allocator>::is_always_equal::value);
635
- basic_string& operator=(basic_string_view<charT, traits> sv);
636
- basic_string& operator=(const charT* s);
637
- basic_string& operator=(charT c);
638
- basic_string& operator=(initializer_list<charT>);
 
639
 
640
  // [string.iterators], iterators
641
- iterator begin() noexcept;
642
- const_iterator begin() const noexcept;
643
- iterator end() noexcept;
644
- const_iterator end() const noexcept;
645
 
646
- reverse_iterator rbegin() noexcept;
647
- const_reverse_iterator rbegin() const noexcept;
648
- reverse_iterator rend() noexcept;
649
- const_reverse_iterator rend() const noexcept;
650
 
651
- const_iterator cbegin() const noexcept;
652
- const_iterator cend() const noexcept;
653
- const_reverse_iterator crbegin() const noexcept;
654
- const_reverse_iterator crend() const noexcept;
655
 
656
  // [string.capacity], capacity
657
- size_type size() const noexcept;
658
- size_type length() const noexcept;
659
- size_type max_size() const noexcept;
660
- void resize(size_type n, charT c);
661
- void resize(size_type n);
662
- size_type capacity() const noexcept;
663
- void reserve(size_type res_arg = 0);
664
- void shrink_to_fit();
665
- void clear() noexcept;
666
- bool empty() const noexcept;
667
 
668
  // [string.access], element access
669
- const_reference operator[](size_type pos) const;
670
- reference operator[](size_type pos);
671
- const_reference at(size_type n) const;
672
- reference at(size_type n);
673
 
674
- const charT& front() const;
675
- charT& front();
676
- const charT& back() const;
677
- charT& back();
678
 
679
  // [string.modifiers], modifiers
680
- basic_string& operator+=(const basic_string& str);
681
- basic_string& operator+=(basic_string_view<charT, traits> sv);
682
- basic_string& operator+=(const charT* s);
683
- basic_string& operator+=(charT c);
684
- basic_string& operator+=(initializer_list<charT>);
685
- basic_string& append(const basic_string& str);
686
- basic_string& append(const basic_string& str, size_type pos,
687
- size_type n = npos);
688
- basic_string& append(basic_string_view<charT, traits> sv);
689
  template<class T>
690
- basic_string& append(const T& t, size_type pos, size_type n = npos);
691
- basic_string& append(const charT* s, size_type n);
692
- basic_string& append(const charT* s);
693
- basic_string& append(size_type n, charT c);
 
 
 
 
 
 
 
 
 
694
  template<class InputIterator>
695
- basic_string& append(InputIterator first, InputIterator last);
696
- basic_string& append(initializer_list<charT>);
697
- void push_back(charT c);
698
 
699
- basic_string& assign(const basic_string& str);
700
- basic_string& assign(basic_string&& str)
 
 
701
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
702
  allocator_traits<Allocator>::is_always_equal::value);
703
- basic_string& assign(const basic_string& str, size_type pos,
704
- size_type n = npos);
705
- basic_string& assign(basic_string_view<charT, traits> sv);
706
  template<class T>
707
- basic_string& assign(const T& t, size_type pos, size_type n = npos);
708
- basic_string& assign(const charT* s, size_type n);
709
- basic_string& assign(const charT* s);
710
- basic_string& assign(size_type n, charT c);
 
 
711
  template<class InputIterator>
712
- basic_string& assign(InputIterator first, InputIterator last);
713
- basic_string& assign(initializer_list<charT>);
714
 
715
- basic_string& insert(size_type pos, const basic_string& str);
716
- basic_string& insert(size_type pos1, const basic_string& str,
717
  size_type pos2, size_type n = npos);
718
- basic_string& insert(size_type pos, basic_string_view<charT, traits> sv);
719
  template<class T>
720
- basic_string& insert(size_type pos1, const T& t,
 
 
721
  size_type pos2, size_type n = npos);
722
- basic_string& insert(size_type pos, const charT* s, size_type n);
723
- basic_string& insert(size_type pos, const charT* s);
724
- basic_string& insert(size_type pos, size_type n, charT c);
725
- iterator insert(const_iterator p, charT c);
726
- iterator insert(const_iterator p, size_type n, charT c);
727
  template<class InputIterator>
728
- iterator insert(const_iterator p, InputIterator first, InputIterator last);
729
- iterator insert(const_iterator p, initializer_list<charT>);
730
 
731
- basic_string& erase(size_type pos = 0, size_type n = npos);
732
- iterator erase(const_iterator p);
733
- iterator erase(const_iterator first, const_iterator last);
734
 
735
- void pop_back();
736
 
737
- basic_string& replace(size_type pos1, size_type n1,
738
- const basic_string& str);
739
- basic_string& replace(size_type pos1, size_type n1,
740
- const basic_string& str,
741
  size_type pos2, size_type n2 = npos);
742
- basic_string& replace(size_type pos1, size_type n1,
743
- basic_string_view<charT, traits> sv);
744
  template<class T>
745
- basic_string& replace(size_type pos1, size_type n1, const T& t,
 
 
746
  size_type pos2, size_type n2 = npos);
747
- basic_string& replace(size_type pos, size_type n1, const charT* s,
748
- size_type n2);
749
- basic_string& replace(size_type pos, size_type n1, const charT* s);
750
- basic_string& replace(size_type pos, size_type n1, size_type n2,
751
- charT c);
752
-
753
- basic_string& replace(const_iterator i1, const_iterator i2,
754
  const basic_string& str);
755
- basic_string& replace(const_iterator i1, const_iterator i2,
756
- basic_string_view<charT, traits> sv);
757
- basic_string& replace(const_iterator i1, const_iterator i2, const charT* s,
758
  size_type n);
759
- basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
760
- basic_string& replace(const_iterator i1, const_iterator i2,
761
- size_type n, charT c);
762
  template<class InputIterator>
763
- basic_string& replace(const_iterator i1, const_iterator i2,
764
  InputIterator j1, InputIterator j2);
765
- basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
766
 
767
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
768
- void swap(basic_string& str)
 
769
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
770
  allocator_traits<Allocator>::is_always_equal::value);
771
 
772
  // [string.ops], string operations
773
- const charT* c_str() const noexcept;
774
- const charT* data() const noexcept;
775
- charT* data() noexcept;
776
- operator basic_string_view<charT, traits>() const noexcept;
777
- allocator_type get_allocator() const noexcept;
778
 
779
- size_type find (basic_string_view<charT, traits> sv,
780
- size_type pos = 0) const noexcept;
781
- size_type find (const basic_string& str, size_type pos = 0) const noexcept;
782
- size_type find (const charT* s, size_type pos, size_type n) const;
783
- size_type find (const charT* s, size_type pos = 0) const;
784
- size_type find (charT c, size_type pos = 0) const;
785
- size_type rfind(basic_string_view<charT, traits> sv,
786
- size_type pos = npos) const noexcept;
787
- size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
788
- size_type rfind(const charT* s, size_type pos, size_type n) const;
789
- size_type rfind(const charT* s, size_type pos = npos) const;
790
- size_type rfind(charT c, size_type pos = npos) const;
791
 
792
- size_type find_first_of(basic_string_view<charT, traits> sv,
793
- size_type pos = 0) const noexcept;
794
- size_type find_first_of(const basic_string& str,
795
- size_type pos = 0) const noexcept;
796
- size_type find_first_of(const charT* s,
797
- size_type pos, size_type n) const;
798
- size_type find_first_of(const charT* s, size_type pos = 0) const;
799
- size_type find_first_of(charT c, size_type pos = 0) const;
800
- size_type find_last_of (basic_string_view<charT, traits> sv,
801
- size_type pos = npos) const noexcept;
802
- size_type find_last_of (const basic_string& str,
803
  size_type pos = npos) const noexcept;
804
- size_type find_last_of (const charT* s,
805
- size_type pos, size_type n) const;
806
- size_type find_last_of (const charT* s, size_type pos = npos) const;
807
- size_type find_last_of (charT c, size_type pos = npos) const;
808
 
809
- size_type find_first_not_of(basic_string_view<charT, traits> sv,
810
- size_type pos = 0) const noexcept;
811
- size_type find_first_not_of(const basic_string& str,
 
812
  size_type pos = 0) const noexcept;
813
- size_type find_first_not_of(const charT* s, size_type pos,
814
- size_type n) const;
815
- size_type find_first_not_of(const charT* s, size_type pos = 0) const;
816
- size_type find_first_not_of(charT c, size_type pos = 0) const;
817
- size_type find_last_not_of (basic_string_view<charT, traits> sv,
818
- size_type pos = npos) const noexcept;
819
- size_type find_last_not_of (const basic_string& str,
820
  size_type pos = npos) const noexcept;
821
- size_type find_last_not_of (const charT* s, size_type pos,
822
- size_type n) const;
823
- size_type find_last_not_of (const charT* s,
824
- size_type pos = npos) const;
825
- size_type find_last_not_of (charT c, size_type pos = npos) const;
826
 
827
- basic_string substr(size_type pos = 0, size_type n = npos) const;
828
- int compare(basic_string_view<charT, traits> sv) const noexcept;
829
- int compare(size_type pos1, size_type n1,
830
- basic_string_view<charT, traits> sv) const;
831
  template<class T>
832
- int compare(size_type pos1, size_type n1, const T& t,
 
 
833
  size_type pos2, size_type n2 = npos) const;
834
- int compare(const basic_string& str) const noexcept;
835
- int compare(size_type pos1, size_type n1,
836
- const basic_string& str) const;
837
- int compare(size_type pos1, size_type n1,
838
- const basic_string& str,
839
  size_type pos2, size_type n2 = npos) const;
840
- int compare(const charT* s) const;
841
- int compare(size_type pos1, size_type n1,
842
- const charT* s) const;
843
- int compare(size_type pos1, size_type n1,
844
- const charT* s, size_type n2) const;
 
 
 
 
 
845
  };
846
 
847
  template<class InputIterator,
848
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
849
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
850
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
851
  char_traits<typename iterator_traits<InputIterator>::value_type>,
852
  Allocator>;
 
 
 
 
 
 
 
 
 
 
 
 
 
 
853
  }
854
  ```
855
 
856
- #### `basic_string` general requirements <a id="string.require">[[string.require]]</a>
 
 
 
 
857
 
858
  If any operation would cause `size()` to exceed `max_size()`, that
859
- operation shall throw an exception object of type `length_error`.
860
 
861
  If any member function or operator of `basic_string` throws an
862
- exception, that function or operator shall have no other effect.
 
863
 
864
  In every specialization `basic_string<charT, traits, Allocator>`, the
865
  type `allocator_traits<Allocator>::value_type` shall name the same type
866
  as `charT`. Every object of type
867
- `basic_string<charT, traits, Allocator>` shall use an object of type
868
  `Allocator` to allocate and free storage for the contained `charT`
869
- objects as needed. The `Allocator` object used shall be obtained as
870
- described in [[container.requirements.general]]. In every specialization
871
- `basic_string<charT, traits, Allocator>`, the type `traits` shall
872
- satisfy the character traits requirements ([[char.traits]]), and the
873
- type `traits::char_type` shall name the same type as `charT`.
 
 
874
 
875
  References, pointers, and iterators referring to the elements of a
876
  `basic_string` sequence may be invalidated by the following uses of that
877
  `basic_string` object:
878
 
879
- - as an argument to any standard library function taking a reference to
880
- non-const `basic_string` as an argument.[^3]
881
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
882
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
883
 
884
- #### `basic_string` constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
885
 
886
  ``` cpp
887
- explicit basic_string(const Allocator& a) noexcept;
888
  ```
889
 
890
- *Effects:* Constructs an object of class `basic_string`. The
891
- postconditions of this function are indicated in
892
- Table  [[tab:strings.ctr.1]].
893
-
894
- **Table: `basic_string(const Allocator&)` effects** <a id="tab:strings.ctr.1">[tab:strings.ctr.1]</a>
895
-
896
- | Element | Value |
897
- | ------------ | -------------------------------------------------------------- |
898
- | `data()` | a non-null pointer that is copyable and can have 0 added to it |
899
- | `size()` | 0 |
900
- | `capacity()` | an unspecified value |
901
 
902
  ``` cpp
903
- basic_string(const basic_string& str);
904
- basic_string(basic_string&& str) noexcept;
905
  ```
906
 
907
- *Effects:* Constructs an object of class `basic_string` as indicated in
908
- Table  [[tab:strings.ctr.cpy]]. In the second form, `str` is left in a
909
- valid state with an unspecified value.
910
-
911
- **Table: `basic_string(const basic_string&)` effects** <a id="tab:strings.ctr.cpy">[tab:strings.ctr.cpy]</a>
912
 
913
- | Element | Value |
914
- | ------------ | --------------------------------------------------------------------------------------------------------------- |
915
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
916
- | `size()` | `str.size()` |
917
- | `capacity()` | a value at least as large as `size()` |
918
 
919
  ``` cpp
920
- basic_string(const basic_string& str, size_type pos,
 
 
921
  const Allocator& a = Allocator());
922
  ```
923
 
924
- *Throws:* `out_of_range` if `pos > str.size()`.
925
-
926
- *Effects:* Constructs an object of class `basic_string` and determines
927
- the effective length `rlen` of the initial string value as
928
- `str.size() - pos`, as indicated in Table  [[tab:strings.ctr.2]].
929
 
930
  ``` cpp
931
- basic_string(const basic_string& str, size_type pos, size_type n,
932
- const Allocator& a = Allocator());
933
  ```
934
 
935
- *Throws:* `out_of_range` if `pos > str.size()`.
936
-
937
- *Effects:* Constructs an object of class `basic_string` and determines
938
- the effective length `rlen` of the initial string value as the smaller
939
- of `n` and `str.size() - pos`, as indicated in
940
- Table  [[tab:strings.ctr.2]].
941
-
942
- **Table: `basic_string(const basic_string&, size_type, const Allocator&)`\protect\mbox{ }and\protect
943
- `basic_string(const basic_string&, size_type, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.2">[tab:strings.ctr.2]</a>
944
-
945
- | Element | Value |
946
- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
947
- | `data()` | points at the first element of an allocated copy of `rlen` consecutive elements of the string controlled by `str` beginning at position `pos` |
948
- | `size()` | `rlen` |
949
- | `capacity()` | a value at least as large as `size()` |
950
-
951
  ``` cpp
952
  template<class T>
953
- basic_string(const T& t, size_type pos, size_type n,
954
- const Allocator& a = Allocator());
955
  ```
956
 
 
 
 
 
957
  *Effects:* Creates a variable, `sv`, as if by
958
  `basic_string_view<charT, traits> sv = t;` and then behaves the same as:
959
 
960
  ``` cpp
961
  basic_string(sv.substr(pos, n), a);
962
  ```
963
 
964
- *Remarks:* This constructor shall not participate in overload resolution
965
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
966
- `true`.
967
-
968
  ``` cpp
969
- explicit basic_string(basic_string_view<charT, traits> sv,
970
- const Allocator& a = Allocator());
971
  ```
972
 
973
- *Effects:* Same as `basic_string(sv.data(), sv.size(), a)`.
 
 
 
 
 
 
 
 
974
 
975
  ``` cpp
976
- basic_string(const charT* s, size_type n,
977
- const Allocator& a = Allocator());
978
  ```
979
 
980
- *Requires:* `s` points to an array of at least `n` elements of `charT`.
981
 
982
- *Effects:* Constructs an object of class `basic_string` and determines
983
- its initial string value from the array of `charT` of length `n` whose
984
- first element is designated by `s`, as indicated in
985
- Table  [[tab:strings.ctr.3]].
986
 
987
- **Table: `basic_string(const charT*, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.3">[tab:strings.ctr.3]</a>
988
-
989
- | Element | Value |
990
- | ------------ | ------------------------------------------------------------------------------------------------------ |
991
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
992
- | `size()` | `n` |
993
- | `capacity()` | a value at least as large as `size()` |
994
 
995
  ``` cpp
996
- basic_string(const charT* s, const Allocator& a = Allocator());
997
  ```
998
 
999
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1000
- elements of `charT`.
1001
-
1002
- *Effects:* Constructs an object of class `basic_string` and determines
1003
- its initial string value from the array of `charT` of length
1004
- `traits::length(s)` whose first element is designated by `s`, as
1005
- indicated in Table  [[tab:strings.ctr.4]].
1006
 
1007
- **Table: `basic_string(const charT*, const Allocator&)` effects** <a id="tab:strings.ctr.4">[tab:strings.ctr.4]</a>
 
1008
 
1009
- | Element | Value |
1010
- | ------------ | ------------------------------------------------------------------------------------------------------ |
1011
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
1012
- | `size()` | `traits::length(s)` |
1013
- | `capacity()` | a value at least as large as `size()` |
1014
 
1015
  ``` cpp
1016
- basic_string(size_type n, charT c, const Allocator& a = Allocator());
1017
  ```
1018
 
1019
- *Requires:* `n < npos`.
1020
-
1021
- *Effects:* Constructs an object of class `basic_string` and determines
1022
- its initial string value by repeating the char-like object `c` for all
1023
- `n` elements, as indicated in Table  [[tab:strings.ctr.5]].
1024
 
1025
- **Table: `basic_string(size_t, charT, const Allocator&)` effects** <a id="tab:strings.ctr.5">[tab:strings.ctr.5]</a>
 
1026
 
1027
- | Element | Value |
1028
- | ------------ | ----------------------------------------------------------------------------------------------------- |
1029
- | `data()` | points at the first element of an allocated array of `n` elements, each storing the initial value `c` |
1030
- | `size()` | `n` |
1031
- | `capacity()` | a value at least as large as `size()` |
1032
 
1033
  ``` cpp
1034
  template<class InputIterator>
1035
- basic_string(InputIterator begin, InputIterator end,
1036
- const Allocator& a = Allocator());
1037
  ```
1038
 
1039
- *Effects:* If `InputIterator` is an integral type, equivalent to:
 
1040
 
1041
- ``` cpp
1042
- basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a);
1043
- ```
1044
-
1045
- Otherwise constructs a string from the values in the range \[`begin`,
1046
- `end`), as indicated in the Sequence Requirements table
1047
- (see  [[sequence.reqmts]]).
1048
 
1049
  ``` cpp
1050
- basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
1051
  ```
1052
 
1053
- *Effects:* Same as `basic_string(il.begin(), il.end(), a)`.
1054
 
1055
  ``` cpp
1056
- basic_string(const basic_string& str, const Allocator& alloc);
1057
- basic_string(basic_string&& str, const Allocator& alloc);
1058
  ```
1059
 
1060
- *Effects:* Constructs an object of class `basic_string` as indicated in
1061
- Table  [[tab:strings.ctr.6]]. The stored allocator is constructed from
1062
- `alloc`. In the second form, `str` is left in a valid state with an
1063
- unspecified value.
1064
-
1065
- **Table: `basic_string(const basic_string&, const Allocator&)`\protect and
1066
- `basic_string(basic_string&&, const Allocator&)` effects** <a id="tab:strings.ctr.6">[tab:strings.ctr.6]</a>
1067
-
1068
- | Element | Value |
1069
- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
1070
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by the original value of `str.data()`. |
1071
- | `size()` | the original value of `str.size()` |
1072
- | `capacity()` | a value at least as large as `size()` |
1073
- | `get_allocator()` | `alloc` |
1074
-
1075
 
1076
  *Throws:* The second form throws nothing if
1077
  `alloc == str.get_allocator()`.
1078
 
1079
  ``` cpp
@@ -1083,226 +979,236 @@ template<class InputIterator,
1083
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
1084
  char_traits<typename iterator_traits<InputIterator>::value_type>,
1085
  Allocator>;
1086
  ```
1087
 
1088
- *Remarks:* Shall not participate in overload resolution if
1089
- `InputIterator` is a type that does not qualify as an input iterator, or
1090
- if `Allocator` is a type that does not qualify as an
1091
- allocator ([[container.requirements.general]]).
1092
 
1093
  ``` cpp
1094
- basic_string& operator=(const basic_string& str);
 
 
 
 
 
 
 
 
 
 
 
 
1095
  ```
1096
 
1097
- *Effects:* If `*this` and `str` are not the same object, modifies
1098
- `*this` as shown in Table  [[tab:strings.op=]].
 
 
 
 
1099
 
1100
- If `*this` and `str` are the same object, the member has no effect.
 
1101
 
1102
  *Returns:* `*this`.
1103
 
1104
- **Table: `operator=(const basic_string&)` effects** <a id="tab:strings.op=">[tab:strings.op=]</a>
1105
-
1106
- | Element | Value |
1107
- | ------------ | --------------------------------------------------------------------------------------------------------------- |
1108
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
1109
- | `size()` | `str.size()` |
1110
- | `capacity()` | a value at least as large as `size()` |
1111
-
1112
  ``` cpp
1113
- basic_string& operator=(basic_string&& str)
1114
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1115
  allocator_traits<Allocator>::is_always_equal::value);
1116
  ```
1117
 
1118
  *Effects:* Move assigns as a sequence
1119
- container ([[container.requirements]]), except that iterators, pointers
1120
  and references may be invalidated.
1121
 
1122
  *Returns:* `*this`.
1123
 
1124
  ``` cpp
1125
- basic_string& operator=(basic_string_view<charT, traits> sv);
 
1126
  ```
1127
 
1128
- *Effects:* Equivalent to: `return assign(sv);`
 
 
 
 
 
 
1129
 
1130
  ``` cpp
1131
- basic_string& operator=(const charT* s);
 
1132
  ```
1133
 
1134
- *Returns:* `*this = basic_string(s)`.
 
 
1135
 
1136
- *Remarks:* Uses `traits::length()`.
 
1137
 
1138
  ``` cpp
1139
- basic_string& operator=(charT c);
1140
  ```
1141
 
1142
- *Returns:* `*this = basic_string(1, c)`.
1143
 
1144
  ``` cpp
1145
- basic_string& operator=(initializer_list<charT> il);
1146
  ```
1147
 
1148
- *Effects:* As if by: `*this = basic_string(il);`
 
 
 
 
1149
 
1150
- *Returns:* `*this`.
 
 
1151
 
1152
- #### `basic_string` iterator support <a id="string.iterators">[[string.iterators]]</a>
1153
 
1154
  ``` cpp
1155
- iterator begin() noexcept;
1156
- const_iterator begin() const noexcept;
1157
- const_iterator cbegin() const noexcept;
1158
  ```
1159
 
1160
  *Returns:* An iterator referring to the first character in the string.
1161
 
1162
  ``` cpp
1163
- iterator end() noexcept;
1164
- const_iterator end() const noexcept;
1165
- const_iterator cend() const noexcept;
1166
  ```
1167
 
1168
  *Returns:* An iterator which is the past-the-end value.
1169
 
1170
  ``` cpp
1171
- reverse_iterator rbegin() noexcept;
1172
- const_reverse_iterator rbegin() const noexcept;
1173
- const_reverse_iterator crbegin() const noexcept;
1174
  ```
1175
 
1176
  *Returns:* An iterator which is semantically equivalent to
1177
  `reverse_iterator(end())`.
1178
 
1179
  ``` cpp
1180
- reverse_iterator rend() noexcept;
1181
- const_reverse_iterator rend() const noexcept;
1182
- const_reverse_iterator crend() const noexcept;
1183
  ```
1184
 
1185
  *Returns:* An iterator which is semantically equivalent to
1186
  `reverse_iterator(begin())`.
1187
 
1188
- #### `basic_string` capacity <a id="string.capacity">[[string.capacity]]</a>
1189
 
1190
  ``` cpp
1191
- size_type size() const noexcept;
 
1192
  ```
1193
 
1194
  *Returns:* A count of the number of char-like objects currently in the
1195
  string.
1196
 
1197
  *Complexity:* Constant time.
1198
 
1199
  ``` cpp
1200
- size_type length() const noexcept;
1201
- ```
1202
-
1203
- *Returns:* `size()`.
1204
-
1205
- ``` cpp
1206
- size_type max_size() const noexcept;
1207
  ```
1208
 
1209
  *Returns:* The largest possible number of char-like objects that can be
1210
  stored in a `basic_string`.
1211
 
1212
  *Complexity:* Constant time.
1213
 
1214
  ``` cpp
1215
- void resize(size_type n, charT c);
1216
  ```
1217
 
1218
- *Throws:* `length_error` if `n > max_size()`.
1219
 
1220
- *Effects:* Alters the length of the string designated by `*this` as
1221
- follows:
1222
-
1223
- - If `n <= size()`, the function replaces the string designated by
1224
- `*this` with a string of length `n` whose elements are a copy of the
1225
- initial elements of the original string designated by `*this`.
1226
- - If `n > size()`, the function replaces the string designated by
1227
- `*this` with a string of length `n` whose first `size()` elements are
1228
- a copy of the original string designated by `*this`, and whose
1229
- remaining elements are all initialized to `c`.
1230
 
1231
  ``` cpp
1232
- void resize(size_type n);
1233
  ```
1234
 
1235
- *Effects:* As if by `resize(n, charT())`.
1236
 
1237
  ``` cpp
1238
- size_type capacity() const noexcept;
1239
  ```
1240
 
1241
  *Returns:* The size of the allocated storage in the string.
1242
 
 
 
1243
  ``` cpp
1244
- void reserve(size_type res_arg=0);
1245
  ```
1246
 
1247
- The member function `reserve()` is a directive that informs a
1248
- `basic_string` object of a planned change in size, so that it can manage
1249
- the storage allocation accordingly.
 
 
 
1250
 
1251
- *Effects:* After `reserve()`, `capacity()` is greater or equal to the
1252
- argument of `reserve`.
1253
-
1254
- [*Note 1*: Calling `reserve()` with a `res_arg` argument less than
1255
- `capacity()` is in effect a non-binding shrink request. A call with
1256
- `res_arg <= size()` is in effect a non-binding shrink-to-fit
1257
- request. — *end note*]
1258
-
1259
- *Throws:* `length_error` if `res_arg > max_size()`.[^4]
1260
 
1261
  ``` cpp
1262
- void shrink_to_fit();
1263
  ```
1264
 
1265
  *Effects:* `shrink_to_fit` is a non-binding request to reduce
1266
  `capacity()` to `size()`.
1267
 
1268
- [*Note 2*: The request is non-binding to allow latitude for
1269
  implementation-specific optimizations. — *end note*]
1270
 
1271
  It does not increase `capacity()`, but may reduce `capacity()` by
1272
  causing reallocation.
1273
 
1274
- *Complexity:* Linear in the size of the sequence.
 
1275
 
1276
  *Remarks:* Reallocation invalidates all the references, pointers, and
1277
- iterators referring to the elements in the sequence as well as the
1278
- past-the-end iterator. If no reallocation happens, they remain valid.
1279
 
1280
- ``` cpp
1281
- void clear() noexcept;
1282
- ```
1283
-
1284
- *Effects:* Behaves as if the function calls:
1285
 
1286
  ``` cpp
1287
- erase(begin(), end());
1288
  ```
1289
 
 
 
1290
  ``` cpp
1291
- bool empty() const noexcept;
1292
  ```
1293
 
1294
- *Returns:* `size() == 0`.
1295
 
1296
- #### `basic_string` element access <a id="string.access">[[string.access]]</a>
1297
 
1298
  ``` cpp
1299
- const_reference operator[](size_type pos) const;
1300
- reference operator[](size_type pos);
1301
  ```
1302
 
1303
- *Requires:* `pos <= size()`.
1304
 
1305
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
1306
  reference to an object of type `charT` with value `charT()`, where
1307
  modifying the object to any value other than `charT()` leads to
1308
  undefined behavior.
@@ -1310,1026 +1216,800 @@ undefined behavior.
1310
  *Throws:* Nothing.
1311
 
1312
  *Complexity:* Constant time.
1313
 
1314
  ``` cpp
1315
- const_reference at(size_type pos) const;
1316
- reference at(size_type pos);
1317
  ```
1318
 
1319
  *Throws:* `out_of_range` if `pos >= size()`.
1320
 
1321
  *Returns:* `operator[](pos)`.
1322
 
1323
  ``` cpp
1324
- const charT& front() const;
1325
- charT& front();
1326
  ```
1327
 
1328
- *Requires:* `!empty()`.
1329
 
1330
  *Effects:* Equivalent to: `return operator[](0);`
1331
 
1332
  ``` cpp
1333
- const charT& back() const;
1334
- charT& back();
1335
  ```
1336
 
1337
- *Requires:* `!empty()`.
1338
 
1339
  *Effects:* Equivalent to: `return operator[](size() - 1);`
1340
 
1341
- #### `basic_string` modifiers <a id="string.modifiers">[[string.modifiers]]</a>
1342
 
1343
- ##### `basic_string::operator+=` <a id="string.op+=">[[string.op+=]]</a>
1344
 
1345
  ``` cpp
1346
- basic_string&
1347
- operator+=(const basic_string& str);
1348
  ```
1349
 
1350
- *Effects:* Calls `append(str)`.
1351
-
1352
- *Returns:* `*this`.
1353
 
1354
  ``` cpp
1355
- basic_string& operator+=(basic_string_view<charT, traits> sv);
 
1356
  ```
1357
 
1358
- *Effects:* Calls `append(sv)`.
 
 
 
 
1359
 
1360
- *Returns:* `*this`.
1361
 
1362
  ``` cpp
1363
- basic_string& operator+=(const charT* s);
 
1364
  ```
1365
 
1366
- *Effects:* Calls `append(s)`.
 
 
1367
 
1368
- *Returns:* `*this`.
1369
 
1370
  ``` cpp
1371
- basic_string& operator+=(charT c);
1372
  ```
1373
 
1374
- *Effects:* Calls `push_back(c)`;
1375
-
1376
- *Returns:* `*this`.
1377
 
1378
  ``` cpp
1379
- basic_string& operator+=(initializer_list<charT> il);
1380
  ```
1381
 
1382
- *Effects:* Calls `append(il)`.
1383
-
1384
- *Returns:* `*this`.
1385
 
1386
  ##### `basic_string::append` <a id="string.append">[[string.append]]</a>
1387
 
1388
  ``` cpp
1389
- basic_string&
1390
- append(const basic_string& str);
1391
  ```
1392
 
1393
- *Effects:* Calls `append(str.data(), str.size())`.
1394
-
1395
- *Returns:* `*this`.
1396
 
1397
  ``` cpp
1398
- basic_string&
1399
- append(const basic_string& str, size_type pos, size_type n = npos);
1400
  ```
1401
 
1402
- *Throws:* `out_of_range` if `pos > str.size()`.
1403
-
1404
- *Effects:* Determines the effective length `rlen` of the string to
1405
- append as the smaller of `n` and `str``.size() - ``pos` and calls
1406
- `append(str.data() + pos, rlen)`.
1407
-
1408
- *Returns:* `*this`.
1409
 
1410
  ``` cpp
1411
- basic_string& append(basic_string_view<charT, traits> sv);
1412
  ```
1413
 
1414
- *Effects:* Equivalent to: `return append(sv.data(), sv.size());`
1415
-
1416
  ``` cpp
1417
  template<class T>
1418
- basic_string& append(const T& t, size_type pos, size_type n = npos);
1419
  ```
1420
 
1421
- *Throws:* `out_of_range` if `pos > sv.size()`.
1422
 
1423
- *Effects:* Creates a variable, `sv`, as if by
1424
- `basic_string_view<charT, traits> sv = t`. Determines the effective
1425
- length `rlen` of the string to append as the smaller of `n` and
1426
- `sv.size() - pos` and calls `append(sv.data() + pos, rlen)`.
1427
 
1428
- *Remarks:* This function shall not participate in overload resolution
1429
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1430
- `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1431
 
1432
- *Returns:* `*this`.
 
 
 
1433
 
1434
  ``` cpp
1435
- basic_string&
1436
- append(const charT* s, size_type n);
1437
  ```
1438
 
1439
- *Requires:* `s` points to an array of at least `n` elements of `charT`.
1440
 
1441
- *Throws:* `length_error` if `size() + n > max_size()`.
 
 
1442
 
1443
- *Effects:* The function replaces the string controlled by `*this` with a
1444
- string of length `size() + n` whose first `size()` elements are a copy
1445
- of the original string controlled by `*this` and whose remaining
1446
- elements are a copy of the initial `n` elements of `s`.
1447
 
1448
- *Returns:* `*this`.
 
 
 
1449
 
1450
  ``` cpp
1451
- basic_string& append(const charT* s);
1452
  ```
1453
 
1454
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1455
- elements of `charT`.
1456
 
1457
- *Effects:* Calls `append(s, traits::length(s))`.
1458
 
1459
  *Returns:* `*this`.
1460
 
1461
  ``` cpp
1462
- basic_string& append(size_type n, charT c);
 
 
 
 
 
 
1463
  ```
1464
 
1465
- *Effects:* Equivalent to `append(basic_string(n, c))`.
1466
 
1467
  *Returns:* `*this`.
1468
 
1469
  ``` cpp
1470
  template<class InputIterator>
1471
- basic_string& append(InputIterator first, InputIterator last);
1472
  ```
1473
 
1474
- *Requires:* \[`first`, `last`) is a valid range.
 
1475
 
1476
- *Effects:* Equivalent to
1477
- `append(basic_string(first, last, get_allocator()))`.
1478
-
1479
- *Returns:* `*this`.
1480
 
1481
  ``` cpp
1482
- basic_string& append(initializer_list<charT> il);
1483
  ```
1484
 
1485
- *Effects:* Calls `append(il.begin(), il.size())`.
1486
-
1487
- *Returns:* `*this`.
1488
 
1489
  ``` cpp
1490
- void push_back(charT c);
1491
  ```
1492
 
1493
- *Effects:* Equivalent to `append(static_cast<size_type>(1), c)`.
1494
 
1495
  ##### `basic_string::assign` <a id="string.assign">[[string.assign]]</a>
1496
 
1497
  ``` cpp
1498
- basic_string& assign(const basic_string& str);
1499
  ```
1500
 
1501
- *Effects:* Equivalent to `*this = str`.
1502
-
1503
- *Returns:* `*this`.
1504
 
1505
  ``` cpp
1506
- basic_string& assign(basic_string&& str)
1507
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1508
  allocator_traits<Allocator>::is_always_equal::value);
1509
  ```
1510
 
1511
- *Effects:* Equivalent to `*this = std::move(str)`.
1512
-
1513
- *Returns:* `*this`.
1514
 
1515
  ``` cpp
1516
- basic_string&
1517
- assign(const basic_string& str, size_type pos,
1518
- size_type n = npos);
1519
  ```
1520
 
1521
- *Throws:* `out_of_range` if `pos > str.size()`.
1522
-
1523
- *Effects:* Determines the effective length `rlen` of the string to
1524
- assign as the smaller of `n` and `str``.size() - ``pos` and calls
1525
- `assign(str.data() + pos, rlen)`.
1526
-
1527
- *Returns:* `*this`.
1528
 
1529
  ``` cpp
1530
- basic_string& assign(basic_string_view<charT, traits> sv);
1531
  ```
1532
 
1533
- *Effects:* Equivalent to: `return assign(sv.data(), sv.size());`
1534
-
1535
  ``` cpp
1536
  template<class T>
1537
- basic_string& assign(const T& t, size_type pos, size_type n = npos);
1538
  ```
1539
 
1540
- *Throws:* `out_of_range` if `pos > sv.size()`.
1541
 
1542
- *Effects:* Creates a variable, `sv`, as if by
1543
- `basic_string_view<charT, traits> sv = t`. Determines the effective
1544
- length `rlen` of the string to assign as the smaller of `n` and
1545
- `sv.size() - pos` and calls `assign(sv.data() + pos, rlen)`.
1546
 
1547
- *Remarks:* This function shall not participate in overload resolution
1548
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1549
- `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1550
 
1551
- *Returns:* `*this`.
 
 
 
1552
 
1553
  ``` cpp
1554
- basic_string& assign(const charT* s, size_type n);
 
1555
  ```
1556
 
1557
- *Requires:* `s` points to an array of at least `n` elements of `charT`.
1558
 
1559
- *Throws:* `length_error` if `n > max_size()`.
 
 
1560
 
1561
- *Effects:* Replaces the string controlled by `*this` with a string of
1562
- length `n` whose elements are a copy of those pointed to by `s`.
1563
 
1564
- *Returns:* `*this`.
 
 
 
1565
 
1566
  ``` cpp
1567
- basic_string& assign(const charT* s);
1568
  ```
1569
 
1570
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1571
- elements of `charT`.
1572
 
1573
- *Effects:* Calls `assign(s, traits::length(s))`.
 
1574
 
1575
  *Returns:* `*this`.
1576
 
1577
  ``` cpp
1578
- basic_string& assign(initializer_list<charT> il);
1579
  ```
1580
 
1581
- *Effects:* Calls `assign(il.begin(), il.size())`.
1582
 
1583
- `*this`.
 
 
 
 
1584
 
1585
  ``` cpp
1586
- basic_string& assign(size_type n, charT c);
1587
  ```
1588
 
1589
- *Effects:* Equivalent to `assign(basic_string(n, c))`.
1590
 
1591
- *Returns:* `*this`.
 
 
 
 
1592
 
1593
  ``` cpp
1594
  template<class InputIterator>
1595
- basic_string& assign(InputIterator first, InputIterator last);
1596
  ```
1597
 
1598
- *Effects:* Equivalent to
1599
- `assign(basic_string(first, last, get_allocator()))`.
1600
 
1601
- *Returns:* `*this`.
 
1602
 
1603
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1604
 
1605
  ``` cpp
1606
- basic_string&
1607
- insert(size_type pos,
1608
- const basic_string& str);
1609
  ```
1610
 
1611
  *Effects:* Equivalent to: `return insert(pos, str.data(), str.size());`
1612
 
1613
  ``` cpp
1614
- basic_string&
1615
- insert(size_type pos1,
1616
- const basic_string& str,
1617
  size_type pos2, size_type n = npos);
1618
  ```
1619
 
1620
- *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1621
 
1622
- *Effects:* Determines the effective length `rlen` of the string to
1623
- insert as the smaller of `n` and `str.size() - pos2` and calls
1624
- `insert(pos1, str.data() + pos2, rlen)`.
1625
-
1626
- *Returns:* `*this`.
1627
 
1628
  ``` cpp
1629
- basic_string& insert(size_type pos, basic_string_view<charT, traits> sv);
 
1630
  ```
1631
 
1632
- *Effects:* Equivalent to: `return insert(pos, sv.data(), sv.size());`
 
 
 
 
 
 
 
 
 
 
 
1633
 
1634
  ``` cpp
1635
  template<class T>
1636
- basic_string& insert(size_type pos1, const T& t,
1637
  size_type pos2, size_type n = npos);
1638
  ```
1639
 
1640
- *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > sv.size()`.
1641
 
1642
- *Effects:* Creates a variable, `sv`, as if by
1643
- `basic_string_view<charT, traits> sv = t`. Determines the effective
1644
- length `rlen` of the string to assign as the smaller of `n` and
1645
- `sv.size() - pos2` and calls `insert(pos1, sv.data() + pos2, rlen)`.
1646
 
1647
- *Remarks:* This function shall not participate in overload resolution
1648
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1649
- `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1650
 
1651
- *Returns:* `*this`.
 
 
 
1652
 
1653
  ``` cpp
1654
- basic_string&
1655
- insert(size_type pos, const charT* s, size_type n);
1656
  ```
1657
 
1658
- *Requires:* `s` points to an array of at least `n` elements of `charT`.
 
 
1659
 
1660
- *Throws:* `out_of_range` if `pos > size()` or `length_error` if
1661
- `size() + n > max_size()`.
 
1662
 
1663
- *Effects:* Replaces the string controlled by `*this` with a string of
1664
- length `size() + n` whose first `pos` elements are a copy of the initial
1665
- elements of the original string controlled by `*this` and whose next `n`
1666
- elements are a copy of the elements in `s` and whose remaining elements
1667
- are a copy of the remaining elements of the original string controlled
1668
- by `*this`.
1669
 
1670
  *Returns:* `*this`.
1671
 
1672
  ``` cpp
1673
- basic_string&
1674
- insert(size_type pos, const charT* s);
1675
  ```
1676
 
1677
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1678
- elements of `charT`.
1679
-
1680
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
1681
 
1682
  ``` cpp
1683
- basic_string&
1684
- insert(size_type pos, size_type n, charT c);
1685
  ```
1686
 
1687
- *Effects:* Equivalent to `insert(pos, basic_string(n, c))`.
 
1688
 
1689
- *Returns:* `*this`.
 
 
 
 
 
 
1690
 
1691
  ``` cpp
1692
- iterator insert(const_iterator p, charT c);
1693
  ```
1694
 
1695
- *Requires:* `p` is a valid iterator on `*this`.
1696
 
1697
- *Effects:* Inserts a copy of `c` before the character referred to by
1698
- `p`.
1699
 
1700
- *Returns:* An iterator which refers to the copy of the inserted
1701
- character.
1702
 
1703
  ``` cpp
1704
- iterator insert(const_iterator p, size_type n, charT c);
1705
  ```
1706
 
1707
- *Requires:* `p` is a valid iterator on `*this`.
1708
 
1709
- *Effects:* Inserts `n` copies of `c` before the character referred to by
1710
- `p`.
1711
 
1712
- *Returns:* An iterator which refers to the copy of the first inserted
1713
- character, or `p` if `n == 0`.
1714
 
1715
  ``` cpp
1716
  template<class InputIterator>
1717
- iterator insert(const_iterator p, InputIterator first, InputIterator last);
1718
  ```
1719
 
1720
- *Requires:* `p` is a valid iterator on `*this`. `[first, last)` is a
1721
- valid range.
 
 
1722
 
1723
  *Effects:* Equivalent to
1724
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1725
 
1726
- *Returns:* An iterator which refers to the copy of the first inserted
1727
- character, or `p` if `first == last`.
1728
 
1729
  ``` cpp
1730
- iterator insert(const_iterator p, initializer_list<charT> il);
1731
  ```
1732
 
1733
- *Effects:* As if by `insert(p, il.begin(), il.end())`.
1734
-
1735
- *Returns:* An iterator which refers to the copy of the first inserted
1736
- character, or `p` if `i1` is empty.
1737
 
1738
  ##### `basic_string::erase` <a id="string.erase">[[string.erase]]</a>
1739
 
1740
  ``` cpp
1741
- basic_string& erase(size_type pos = 0, size_type n = npos);
1742
  ```
1743
 
1744
  *Throws:* `out_of_range` if `pos` `> size()`.
1745
 
1746
  *Effects:* Determines the effective length `xlen` of the string to be
1747
- removed as the smaller of `n` and `size() - pos`.
1748
-
1749
- The function then replaces the string controlled by `*this` with a
1750
- string of length `size() - xlen` whose first `pos` elements are a copy
1751
- of the initial elements of the original string controlled by `*this`,
1752
- and whose remaining elements are a copy of the elements of the original
1753
- string controlled by `*this` beginning at position `pos + xlen`.
1754
 
1755
  *Returns:* `*this`.
1756
 
1757
  ``` cpp
1758
- iterator erase(const_iterator p);
1759
  ```
1760
 
 
 
1761
  *Throws:* Nothing.
1762
 
1763
  *Effects:* Removes the character referred to by `p`.
1764
 
1765
  *Returns:* An iterator which points to the element immediately following
1766
  `p` prior to the element being erased. If no such element exists,
1767
  `end()` is returned.
1768
 
1769
  ``` cpp
1770
- iterator erase(const_iterator first, const_iterator last);
1771
  ```
1772
 
1773
- *Requires:* `first` and `last` are valid iterators on `*this`, defining
1774
- a range `[first, last)`.
1775
 
1776
  *Throws:* Nothing.
1777
 
1778
  *Effects:* Removes the characters in the range `[first, last)`.
1779
 
1780
  *Returns:* An iterator which points to the element pointed to by `last`
1781
  prior to the other elements being erased. If no such element exists,
1782
  `end()` is returned.
1783
 
1784
  ``` cpp
1785
- void pop_back();
1786
  ```
1787
 
1788
- *Requires:* `!empty()`.
1789
 
1790
  *Throws:* Nothing.
1791
 
1792
- *Effects:* Equivalent to `erase(size() - 1, 1)`.
1793
 
1794
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1795
 
1796
  ``` cpp
1797
- basic_string&
1798
- replace(size_type pos1, size_type n1,
1799
- const basic_string& str);
1800
  ```
1801
 
1802
  *Effects:* Equivalent to:
1803
  `return replace(pos1, n1, str.data(), str.size());`
1804
 
1805
  ``` cpp
1806
- basic_string&
1807
- replace(size_type pos1, size_type n1,
1808
- const basic_string& str,
1809
  size_type pos2, size_type n2 = npos);
1810
  ```
1811
 
1812
- *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > str.size()`.
1813
-
1814
- *Effects:* Determines the effective length `rlen` of the string to be
1815
- inserted as the smaller of `n2` and `str.size() - pos2` and calls
1816
- `replace(pos1, n1, str.data() + pos2, rlen)`.
1817
 
1818
- *Returns:* `*this`.
 
 
1819
 
1820
  ``` cpp
1821
- basic_string& replace(size_type pos1, size_type n1,
1822
- basic_string_view<charT, traits> sv);
1823
  ```
1824
 
 
 
 
 
 
 
1825
  *Effects:* Equivalent to:
1826
- `return replace(pos1, n1, sv.data(), sv.size());`
 
 
 
 
1827
 
1828
  ``` cpp
1829
  template<class T>
1830
- basic_string& replace(size_type pos1, size_type n1, const T& t,
1831
  size_type pos2, size_type n2 = npos);
1832
  ```
1833
 
1834
- *Throws:* `out_of_range` if `pos1 > size()` or `pos2 > sv.size()`.
1835
 
1836
- *Effects:* Creates a variable, `sv`, as if by
1837
- `basic_string_view<charT, traits> sv = t`. Determines the effective
1838
- length `rlen` of the string to be inserted as the smaller of `n2` and
1839
- `sv.size() - pos2` and calls
1840
- `replace(pos1, n1, sv.data() + pos2, rlen)`.
1841
 
1842
- *Remarks:* This function shall not participate in overload resolution
1843
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1844
- `true` and `is_convertible_v<const T&, const charT*>` is `false`.
1845
 
1846
- *Returns:* `*this`.
 
 
 
1847
 
1848
  ``` cpp
1849
- basic_string&
1850
- replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1851
  ```
1852
 
1853
- *Requires:* `s` points to an array of at least `n2` elements of `charT`.
 
 
1854
 
1855
- *Throws:* `out_of_range` if `pos1 > size()` or `length_error` if the
1856
- length of the resulting string would exceed `max_size()` (see below).
 
 
1857
 
1858
  *Effects:* Determines the effective length `xlen` of the string to be
1859
  removed as the smaller of `n1` and `size() - pos1`. If
1860
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1861
- function replaces the string controlled by \*`this` with a string of
1862
- length `size() - xlen + n2` whose first `pos1` elements are a copy of
1863
- the initial elements of the original string controlled by `*this`, whose
1864
- next `n2` elements are a copy of the initial `n2` elements of `s`, and
1865
- whose remaining elements are a copy of the elements of the original
1866
- string controlled by `*this` beginning at position `pos + xlen`.
1867
 
1868
  *Returns:* `*this`.
1869
 
1870
  ``` cpp
1871
- basic_string&
1872
- replace(size_type pos, size_type n, const charT* s);
1873
  ```
1874
 
1875
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
1876
- elements of `charT`.
1877
-
1878
  *Effects:* Equivalent to:
1879
  `return replace(pos, n, s, traits::length(s));`
1880
 
1881
  ``` cpp
1882
- basic_string&
1883
- replace(size_type pos1, size_type n1,
1884
- size_type n2, charT c);
1885
  ```
1886
 
1887
- *Effects:* Equivalent to `replace(pos1, n1, basic_string(n2, c))`.
 
 
 
 
 
 
 
 
 
 
 
1888
 
1889
  *Returns:* `*this`.
1890
 
1891
  ``` cpp
1892
- basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1893
  ```
1894
 
1895
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1896
-
1897
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, str)`.
1898
-
1899
- *Returns:* `*this`.
1900
 
1901
  ``` cpp
1902
- basic_string& replace(const_iterator i1, const_iterator i2,
1903
- basic_string_view<charT, traits> sv);
1904
  ```
1905
 
1906
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1907
 
1908
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, sv)`.
 
 
1909
 
1910
- *Returns:* `*this`.
 
 
1911
 
1912
  ``` cpp
1913
- basic_string&
1914
- replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
1915
  ```
1916
 
1917
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges and
1918
- `s` points to an array of at least `n` elements of `charT`.
1919
-
1920
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, s, n)`.
1921
-
1922
- *Returns:* `*this`.
1923
-
1924
  ``` cpp
1925
- basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
1926
  ```
1927
 
1928
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges and
1929
- `s` points to an array of at least `traits::length(s) + 1` elements of
1930
- `charT`.
1931
 
1932
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, s, traits::length(s))`.
 
 
1933
 
1934
- *Returns:* `*this`.
 
1935
 
1936
  ``` cpp
1937
- basic_string& replace(const_iterator i1, const_iterator i2, size_type n,
1938
- charT c);
1939
  ```
1940
 
1941
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1942
 
1943
- *Effects:* Calls `replace(i1 - begin(), i2 - i1, basic_string(n, c))`.
1944
-
1945
- *Returns:* `*this`.
1946
 
1947
  ``` cpp
1948
  template<class InputIterator>
1949
- basic_string& replace(const_iterator i1, const_iterator i2,
1950
  InputIterator j1, InputIterator j2);
1951
  ```
1952
 
1953
- *Requires:* \[`begin()`, `i1`), \[`i1`, `i2`) and \[`j1`, `j2`) are
1954
- valid ranges.
1955
 
1956
- *Effects:* Calls
1957
- `replace(i1 - begin(), i2 - i1, basic_string(j1, j2, get_allocator()))`.
1958
-
1959
- *Returns:* `*this`.
1960
 
1961
  ``` cpp
1962
- basic_string& replace(const_iterator i1, const_iterator i2,
1963
- initializer_list<charT> il);
1964
  ```
1965
 
1966
- *Requires:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1967
-
1968
- *Effects:* Calls
1969
- `replace(i1 - begin(), i2 - i1, il.begin(), il.size())`.
1970
-
1971
- *Returns:* `*this`.
1972
 
1973
  ##### `basic_string::copy` <a id="string.copy">[[string.copy]]</a>
1974
 
1975
  ``` cpp
1976
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
1977
  ```
1978
 
1979
- Let `rlen` be the smaller of `n` and `size() - pos`.
1980
-
1981
- *Throws:* `out_of_range` if `pos > size()`.
1982
-
1983
- *Requires:* \[`s`, `s + rlen`) is a valid range.
1984
-
1985
- *Effects:* Equivalent to: `traits::copy(s, data() + pos, rlen)`.
1986
 
1987
  [*Note 1*: This does not terminate `s` with a null
1988
  object. — *end note*]
1989
 
1990
- *Returns:* `rlen`.
1991
-
1992
  ##### `basic_string::swap` <a id="string.swap">[[string.swap]]</a>
1993
 
1994
  ``` cpp
1995
- void swap(basic_string& s)
1996
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
1997
  allocator_traits<Allocator>::is_always_equal::value);
1998
  ```
1999
 
2000
- *Postconditions:* `*this` contains the same sequence of characters that
2001
- was in `s`, `s` contains the same sequence of characters that was in
2002
- `*this`.
 
 
 
2003
 
2004
  *Throws:* Nothing.
2005
 
2006
  *Complexity:* Constant time.
2007
 
2008
- #### `basic_string` string operations <a id="string.ops">[[string.ops]]</a>
2009
 
2010
- ##### `basic_string` accessors <a id="string.accessors">[[string.accessors]]</a>
2011
 
2012
  ``` cpp
2013
- const charT* c_str() const noexcept;
2014
- const charT* data() const noexcept;
2015
  ```
2016
 
2017
- *Returns:* A pointer `p` such that `p + i == &operator[](i)` for each
2018
- `i` in \[`0`, `size()`\].
2019
 
2020
  *Complexity:* Constant time.
2021
 
2022
- *Requires:* The program shall not alter any of the values stored in the
2023
- character array.
2024
 
2025
  ``` cpp
2026
- charT* data() noexcept;
2027
  ```
2028
 
2029
- *Returns:* A pointer `p` such that `p + i == &operator[](i)` for each
2030
- `i` in \[`0`, `size()`\].
2031
 
2032
  *Complexity:* Constant time.
2033
 
2034
- *Requires:* The program shall not alter the value stored at
2035
- `p + size()`.
2036
 
2037
  ``` cpp
2038
- operator basic_string_view<charT, traits>() const noexcept;
2039
  ```
2040
 
2041
  *Effects:* Equivalent to:
2042
  `return basic_string_view<charT, traits>(data(), size());`
2043
 
2044
  ``` cpp
2045
- allocator_type get_allocator() const noexcept;
2046
  ```
2047
 
2048
  *Returns:* A copy of the `Allocator` object used to construct the string
2049
  or, if that allocator has been replaced, a copy of the most recent
2050
  replacement.
2051
 
2052
- ##### `basic_string::find` <a id="string.find">[[string.find]]</a>
2053
 
2054
- ``` cpp
2055
- size_type find(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
2056
- ```
2057
-
2058
- *Effects:* Determines the lowest position `xpos`, if possible, such that
2059
- both of the following conditions hold:
2060
-
2061
- - `pos <= xpos` and `xpos + sv.size() <= size()`;
2062
- - `traits::eq(at(xpos + I), sv.at(I))` for all elements `I` of the data
2063
- referenced by `sv`.
2064
-
2065
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2066
- Otherwise, returns `npos`.
2067
-
2068
- ``` cpp
2069
- size_type find(const basic_string& str, size_type pos = 0) const noexcept;
2070
- ```
2071
-
2072
- *Effects:* Equivalent to:
2073
- `return find(basic_string_view<charT, traits>(str), pos);`
2074
-
2075
- ``` cpp
2076
- size_type find(const charT* s, size_type pos, size_type n) const;
2077
- ```
2078
-
2079
- *Returns:* `find(basic_string_view<charT, traits>(s, n), pos)`.
2080
-
2081
- ``` cpp
2082
- size_type find(const charT* s, size_type pos = 0) const;
2083
- ```
2084
-
2085
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2086
- elements of `charT`.
2087
-
2088
- *Returns:* `find(basic_string_view<charT, traits>(s), pos)`.
2089
-
2090
- ``` cpp
2091
- size_type find(charT c, size_type pos = 0) const;
2092
- ```
2093
-
2094
- *Returns:* `find(basic_string(1, c), pos)`.
2095
-
2096
- ##### `basic_string::rfind` <a id="string.rfind">[[string.rfind]]</a>
2097
-
2098
- ``` cpp
2099
- size_type rfind(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
2100
- ```
2101
-
2102
- *Effects:* Determines the highest position `xpos`, if possible, such
2103
- that both of the following conditions hold:
2104
-
2105
- - `xpos <= pos` and `xpos + sv.size() <= size()`;
2106
- - `traits::eq(at(xpos + I), sv.at(I))` for all elements `I` of the data
2107
- referenced by `sv`.
2108
-
2109
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2110
- Otherwise, returns `npos`.
2111
-
2112
- ``` cpp
2113
- size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
2114
- ```
2115
-
2116
- *Effects:* Equivalent to:
2117
- `return rfind(basic_string_view<charT, traits>(str), pos);`
2118
-
2119
- ``` cpp
2120
- size_type rfind(const charT* s, size_type pos, size_type n) const;
2121
- ```
2122
-
2123
- *Returns:* `rfind(basic_string_view<charT, traits>(s, n), pos)`.
2124
 
 
2125
  ``` cpp
2126
- size_type rfind(const charT* s, size_type pos = npos) const;
2127
  ```
2128
 
2129
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2130
- elements of `charT`.
2131
-
2132
- *Returns:* `rfind(basic_string_view<charT, traits>(s), pos)`.
2133
-
2134
  ``` cpp
2135
- size_type rfind(charT c, size_type pos = npos) const;
2136
  ```
2137
 
2138
- *Returns:* `rfind(basic_string(1, c), pos)`.
2139
-
2140
- ##### `basic_string::find_first_of` <a id="string.find.first.of">[[string.find.first.of]]</a>
2141
-
2142
  ``` cpp
2143
- size_type find_first_of(basic_string_view<charT, traits> sv, size_type pos = 0) const noexcept;
2144
  ```
2145
 
2146
- *Effects:* Determines the lowest position `xpos`, if possible, such that
2147
- both of the following conditions hold:
2148
-
2149
- - `pos <= xpos` and `xpos < size()`;
2150
- - `traits::eq(at(xpos), sv.at(I))` for some element `I` of the data
2151
- referenced by `sv`.
2152
-
2153
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2154
- Otherwise, returns `npos`.
2155
-
2156
  ``` cpp
2157
- size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
2158
  ```
2159
 
2160
- *Effects:* Equivalent to:
2161
- `return find_first_of(basic_string_view<charT, traits>(str), pos);`
2162
-
2163
  ``` cpp
2164
- size_type find_first_of(const charT* s, size_type pos, size_type n) const;
2165
  ```
2166
 
2167
- *Returns:* `find_first_of(basic_string_view<charT, traits>(s, n), pos)`.
2168
-
2169
- ``` cpp
2170
- size_type find_first_of(const charT* s, size_type pos = 0) const;
2171
- ```
2172
-
2173
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2174
- elements of `charT`.
2175
-
2176
- *Returns:* `find_first_of(basic_string_view<charT, traits>(s), pos)`.
2177
-
2178
- ``` cpp
2179
- size_type find_first_of(charT c, size_type pos = 0) const;
2180
- ```
2181
-
2182
- *Returns:* `find_first_of(basic_string(1, c), pos)`.
2183
-
2184
- ##### `basic_string::find_last_of` <a id="string.find.last.of">[[string.find.last.of]]</a>
2185
-
2186
- ``` cpp
2187
- size_type find_last_of(basic_string_view<charT, traits> sv, size_type pos = npos) const noexcept;
2188
- ```
2189
-
2190
- *Effects:* Determines the highest position `xpos`, if possible, such
2191
- that both of the following conditions hold:
2192
-
2193
- - `xpos <= pos` and `xpos < size()`;
2194
- - `traits::eq(at(xpos), sv.at(I))` for some element `I` of the data
2195
- referenced by `sv`.
2196
-
2197
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2198
- Otherwise, returns `npos`.
2199
-
2200
  ``` cpp
2201
- size_type find_last_of(const basic_string& str, size_type pos = npos) const noexcept;
 
 
 
 
 
 
 
 
 
 
 
2202
  ```
2203
 
2204
- *Effects:* Equivalent to:
2205
- `return find_last_of(basic_string_view<charT, traits>(str), pos);`
2206
-
2207
- ``` cpp
2208
- size_type find_last_of(const charT* s, size_type pos, size_type n) const;
2209
- ```
2210
-
2211
- *Returns:* `find_last_of(basic_string_view<charT, traits>(s, n), pos)`.
2212
-
2213
- ``` cpp
2214
- size_type find_last_of(const charT* s, size_type pos = npos) const;
2215
- ```
2216
-
2217
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2218
- elements of `charT`.
2219
-
2220
- *Returns:* `find_last_of(basic_string_view<charT, traits>(s), pos)`.
2221
-
2222
- ``` cpp
2223
- size_type find_last_of(charT c, size_type pos = npos) const;
2224
- ```
2225
-
2226
- *Returns:* `find_last_of(basic_string(1, c), pos)`.
2227
-
2228
- ##### `basic_string::find_first_not_of` <a id="string.find.first.not.of">[[string.find.first.not.of]]</a>
2229
-
2230
- ``` cpp
2231
- size_type find_first_not_of(basic_string_view<charT, traits> sv,
2232
- size_type pos = 0) const noexcept;
2233
- ```
2234
-
2235
- *Effects:* Determines the lowest position `xpos`, if possible, such that
2236
- both of the following conditions hold:
2237
-
2238
- - `pos <= xpos` and `xpos < size()`;
2239
- - `traits::eq(at(xpos), sv.at(I))` for no element `I` of the data
2240
- referenced by `sv`.
2241
-
2242
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2243
- Otherwise, returns `npos`.
2244
-
2245
- ``` cpp
2246
- size_type find_first_not_of(const basic_string& str, size_type pos = 0) const noexcept;
2247
- ```
2248
-
2249
- *Effects:* Equivalent to:
2250
-
2251
- ``` cpp
2252
- return find_first_not_of(basic_string_view<charT, traits>(str), pos);
2253
- ```
2254
-
2255
- ``` cpp
2256
- size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
2257
- ```
2258
-
2259
- *Returns:*
2260
- `find_first_not_of(basic_string_view<charT, traits>(s, n), pos)`.
2261
-
2262
- ``` cpp
2263
- size_type find_first_not_of(const charT* s, size_type pos = 0) const;
2264
- ```
2265
-
2266
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2267
- elements of `charT`.
2268
-
2269
- *Returns:*
2270
- `find_first_not_of(basic_string_view<charT, traits>(s), pos)`.
2271
-
2272
- ``` cpp
2273
- size_type find_first_not_of(charT c, size_type pos = 0) const;
2274
- ```
2275
-
2276
- *Returns:* `find_first_not_of(basic_string(1, c), pos)`.
2277
-
2278
- ##### `basic_string::find_last_not_of` <a id="string.find.last.not.of">[[string.find.last.not.of]]</a>
2279
-
2280
- ``` cpp
2281
- size_type find_last_not_of(basic_string_view<charT, traits> sv,
2282
- size_type pos = npos) const noexcept;
2283
- ```
2284
-
2285
- *Effects:* Determines the highest position `xpos`, if possible, such
2286
- that both of the following conditions hold:
2287
-
2288
- - `xpos <= pos` and `xpos < size()`;
2289
- - `traits::eq(at(xpos), sv.at(I))` for no element `I` of the data
2290
- referenced by `sv`.
2291
-
2292
- *Returns:* `xpos` if the function can determine such a value for `xpos`.
2293
- Otherwise, returns `npos`.
2294
-
2295
- ``` cpp
2296
- size_type find_last_not_of(const basic_string& str, size_type pos = npos) const noexcept;
2297
- ```
2298
-
2299
- *Effects:* Equivalent to:
2300
-
2301
- ``` cpp
2302
- return find_last_not_of(basic_string_view<charT, traits>(str), pos);
2303
- ```
2304
-
2305
- ``` cpp
2306
- size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
2307
- ```
2308
-
2309
- *Returns:*
2310
- `find_last_not_of(basic_string_view<charT, traits>(s, n), pos)`.
2311
-
2312
- ``` cpp
2313
- size_type find_last_not_of(const charT* s, size_type pos = npos) const;
2314
- ```
2315
 
2316
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
2317
- elements of `charT`.
 
2318
 
2319
- *Returns:* `find_last_not_of(basic_string_view<charT, traits>(s), pos)`.
2320
 
2321
  ``` cpp
2322
- size_type find_last_not_of(charT c, size_type pos = npos) const;
 
2323
  ```
2324
 
2325
- *Returns:* `find_last_not_of(basic_string(1, c), pos)`.
 
2326
 
2327
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
2328
 
2329
  ``` cpp
2330
- basic_string substr(size_type pos = 0, size_type n = npos) const;
2331
  ```
2332
 
2333
  *Throws:* `out_of_range` if `pos > size()`.
2334
 
2335
  *Effects:* Determines the effective length `rlen` of the string to copy
@@ -2338,409 +2018,327 @@ as the smaller of `n` and `size() - pos`.
2338
  *Returns:* `basic_string(data()+pos, rlen)`.
2339
 
2340
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
2341
 
2342
  ``` cpp
2343
- int compare(basic_string_view<charT, traits> sv) const noexcept;
 
2344
  ```
2345
 
2346
- *Effects:* Determines the effective length `rlen` of the strings to
2347
- compare as the smaller of `size()` and `sv.size()`. The function then
2348
- compares the two strings by calling
2349
- `traits::compare(data(), sv.data(), rlen)`.
2350
 
2351
- *Returns:* The nonzero result if the result of the comparison is
2352
- nonzero. Otherwise, returns a value as indicated in
2353
- Table  [[tab:strings.compare]].
2354
 
2355
- **Table: `compare()` results** <a id="tab:strings.compare">[tab:strings.compare]</a>
 
2356
 
2357
- | Condition | Return Value |
2358
- | --------------------- | ------------ |
2359
- | `size() < sv.size()` | `< 0` |
2360
- | `size() == sv.size()` | ` 0` |
2361
- | `size() > sv.size()` | `> 0` |
2362
 
2363
  ``` cpp
2364
- int compare(size_type pos1, size_type n1, basic_string_view<charT, traits> sv) const;
 
2365
  ```
2366
 
 
 
 
 
 
 
2367
  *Effects:* Equivalent to:
2368
 
2369
  ``` cpp
2370
- return basic_string_view<charT, traits>(data(), size()).substr(pos1, n1).compare(sv);
2371
  ```
2372
 
2373
  ``` cpp
2374
  template<class T>
2375
- int compare(size_type pos1, size_type n1, const T& t,
2376
  size_type pos2, size_type n2 = npos) const;
2377
  ```
2378
 
 
 
 
 
 
 
2379
  *Effects:* Equivalent to:
2380
 
2381
  ``` cpp
2382
- basic_string_view<charT, traits> sv = t;
2383
- return basic_string_view<charT, traits>(
2384
- data(), size()).substr(pos1, n1).compare(sv.substr(pos2, n2));
2385
  ```
2386
 
2387
- *Remarks:* This function shall not participate in overload resolution
2388
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
2389
- `true` and `is_convertible_v<const T&, const charT*>` is `false`.
2390
-
2391
  ``` cpp
2392
- int compare(const basic_string& str) const noexcept;
2393
  ```
2394
 
2395
  *Effects:* Equivalent to:
2396
  `return compare(basic_string_view<charT, traits>(str));`
2397
 
2398
  ``` cpp
2399
- int compare(size_type pos1, size_type n1, const basic_string& str) const;
2400
  ```
2401
 
2402
  *Effects:* Equivalent to:
2403
  `return compare(pos1, n1, basic_string_view<charT, traits>(str));`
2404
 
2405
  ``` cpp
2406
- int compare(size_type pos1, size_type n1,
2407
- const basic_string& str,
2408
  size_type pos2, size_type n2 = npos) const;
2409
  ```
2410
 
2411
  *Effects:* Equivalent to:
2412
 
2413
  ``` cpp
2414
  return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
2415
  ```
2416
 
2417
  ``` cpp
2418
- int compare(const charT* s) const;
2419
  ```
2420
 
2421
- *Returns:* `compare(basic_string(s))`.
 
2422
 
2423
  ``` cpp
2424
- int compare(size_type pos, size_type n1, const charT* s) const;
2425
  ```
2426
 
2427
- *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s))`.
 
2428
 
2429
  ``` cpp
2430
- int compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
2431
  ```
2432
 
2433
- *Returns:* `basic_string(*this, pos, n1).compare(basic_string(s, n2))`.
 
2434
 
2435
- ### `basic_string` non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
2436
-
2437
- #### `operator+` <a id="string.op+">[[string.op+]]</a>
2438
 
2439
  ``` cpp
2440
- template<class charT, class traits, class Allocator>
2441
- basic_string<charT, traits, Allocator>
2442
- operator+(const basic_string<charT, traits, Allocator>& lhs,
2443
- const basic_string<charT, traits, Allocator>& rhs);
2444
  ```
2445
 
2446
- *Returns:* `basic_string<charT, traits, Allocator>(lhs).append(rhs)`.
2447
 
2448
  ``` cpp
2449
- template<class charT, class traits, class Allocator>
2450
- basic_string<charT, traits, Allocator>
2451
- operator+(basic_string<charT, traits, Allocator>&& lhs,
2452
- const basic_string<charT, traits, Allocator>& rhs);
2453
  ```
2454
 
2455
- *Returns:* `std::move(lhs.append(rhs))`.
2456
 
2457
  ``` cpp
2458
- template<class charT, class traits, class Allocator>
2459
- basic_string<charT, traits, Allocator>
2460
- operator+(const basic_string<charT, traits, Allocator>& lhs,
2461
- basic_string<charT, traits, Allocator>&& rhs);
2462
  ```
2463
 
2464
- *Returns:* `std::move(rhs.insert(0, lhs))`.
2465
 
2466
  ``` cpp
2467
- template<class charT, class traits, class Allocator>
2468
- basic_string<charT, traits, Allocator>
2469
- operator+(basic_string<charT, traits, Allocator>&& lhs,
2470
- basic_string<charT, traits, Allocator>&& rhs);
2471
  ```
2472
 
2473
- *Returns:* `std::move(lhs.append(rhs))`.
2474
 
2475
- [*Note 1*: Or equivalently,
2476
- `std::move(rhs.insert(0, lhs))`. — *end note*]
2477
 
2478
  ``` cpp
2479
  template<class charT, class traits, class Allocator>
2480
- basic_string<charT, traits, Allocator>
2481
- operator+(const charT* lhs,
2482
  const basic_string<charT, traits, Allocator>& rhs);
 
 
 
2483
  ```
2484
 
2485
- *Returns:* `basic_string<charT, traits, Allocator>(lhs) + rhs`.
2486
-
2487
- *Remarks:* Uses `traits::length()`.
2488
 
2489
  ``` cpp
2490
- template<class charT, class traits, class Allocator>
2491
- basic_string<charT, traits, Allocator>
2492
- operator+(const charT* lhs,
2493
- basic_string<charT, traits, Allocator>&& rhs);
2494
  ```
2495
 
2496
- *Returns:* `std::move(rhs.insert(0, lhs))`.
2497
-
2498
- *Remarks:* Uses `traits::length()`.
2499
-
2500
  ``` cpp
2501
  template<class charT, class traits, class Allocator>
2502
- basic_string<charT, traits, Allocator>
2503
- operator+(charT lhs,
2504
  const basic_string<charT, traits, Allocator>& rhs);
2505
- ```
2506
-
2507
- *Returns:* `basic_string<charT, traits, Allocator>(1, lhs) + rhs`.
2508
-
2509
- ``` cpp
2510
  template<class charT, class traits, class Allocator>
2511
- basic_string<charT, traits, Allocator>
2512
- operator+(charT lhs,
2513
- basic_string<charT, traits, Allocator>&& rhs);
2514
  ```
2515
 
2516
- *Returns:* `std::move(rhs.insert(0, 1, lhs))`.
2517
 
2518
  ``` cpp
2519
- template<class charT, class traits, class Allocator>
2520
- basic_string<charT, traits, Allocator>
2521
- operator+(const basic_string<charT, traits, Allocator>& lhs,
2522
- const charT* rhs);
2523
  ```
2524
 
2525
- *Returns:* `lhs + basic_string<charT, traits, Allocator>(rhs)`.
2526
-
2527
- *Remarks:* Uses `traits::length()`.
2528
-
2529
  ``` cpp
2530
  template<class charT, class traits, class Allocator>
2531
- basic_string<charT, traits, Allocator>
2532
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2533
- const charT* rhs);
2534
- ```
2535
-
2536
- *Returns:* `std::move(lhs.append(rhs))`.
2537
-
2538
- *Remarks:* Uses `traits::length()`.
2539
-
2540
- ``` cpp
2541
- template<class charT, class traits, class Allocator>
2542
- basic_string<charT, traits, Allocator>
2543
- operator+(const basic_string<charT, traits, Allocator>& lhs,
2544
- charT rhs);
2545
  ```
2546
 
2547
- *Returns:* `lhs + basic_string<charT, traits, Allocator>(1, rhs)`.
2548
 
2549
  ``` cpp
2550
- template<class charT, class traits, class Allocator>
2551
- basic_string<charT, traits, Allocator>
2552
- operator+(basic_string<charT, traits, Allocator>&& lhs,
2553
- charT rhs);
2554
  ```
2555
 
2556
- *Returns:* `std::move(lhs.append(1, rhs))`.
 
2557
 
2558
- #### `operator==` <a id="string.operator==">[[string.operator==]]</a>
 
2559
 
2560
  ``` cpp
2561
  template<class charT, class traits, class Allocator>
2562
- bool operator==(const basic_string<charT, traits, Allocator>& lhs,
2563
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2564
- ```
2565
-
2566
- *Returns:* `lhs.compare(rhs) == 0`.
2567
-
2568
- ``` cpp
2569
  template<class charT, class traits, class Allocator>
2570
- bool operator==(const charT* lhs,
2571
- const basic_string<charT, traits, Allocator>& rhs);
2572
  ```
2573
 
2574
- *Returns:* `rhs == lhs`.
2575
 
2576
  ``` cpp
2577
- template<class charT, class traits, class Allocator>
2578
- bool operator==(const basic_string<charT, traits, Allocator>& lhs,
2579
- const charT* rhs);
2580
  ```
2581
 
2582
- *Requires:* `rhs` points to an array of at least
2583
- `traits::length(rhs) + 1` elements of `charT`.
2584
-
2585
- *Returns:* `lhs.compare(rhs) == 0`.
2586
-
2587
- #### `operator!=` <a id="string.op!=">[[string.op!=]]</a>
2588
-
2589
  ``` cpp
2590
  template<class charT, class traits, class Allocator>
2591
- bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
2592
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2593
  ```
2594
 
2595
- *Returns:* `!(lhs == rhs)`.
2596
 
2597
  ``` cpp
2598
- template<class charT, class traits, class Allocator>
2599
- bool operator!=(const charT* lhs,
2600
- const basic_string<charT, traits, Allocator>& rhs);
2601
  ```
2602
 
2603
- *Returns:* `rhs != lhs`.
2604
-
2605
  ``` cpp
2606
  template<class charT, class traits, class Allocator>
2607
- bool operator!=(const basic_string<charT, traits, Allocator>& lhs,
2608
- const charT* rhs);
2609
  ```
2610
 
2611
- *Requires:* `rhs` points to an array of at least
2612
- `traits::length(rhs) + 1` elements of `charT`.
2613
-
2614
- *Returns:* `lhs.compare(rhs) != 0`.
2615
-
2616
- #### `operator<` <a id="string.op<">[[string.op<]]</a>
2617
 
2618
  ``` cpp
2619
- template<class charT, class traits, class Allocator>
2620
- bool operator< (const basic_string<charT, traits, Allocator>& lhs,
2621
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2622
  ```
2623
 
2624
- *Returns:* `lhs.compare(rhs) < 0`.
2625
-
2626
  ``` cpp
2627
  template<class charT, class traits, class Allocator>
2628
- bool operator< (const charT* lhs,
2629
- const basic_string<charT, traits, Allocator>& rhs);
2630
  ```
2631
 
2632
- *Returns:* `rhs.compare(lhs) > 0`.
2633
 
2634
  ``` cpp
2635
- template<class charT, class traits, class Allocator>
2636
- bool operator< (const basic_string<charT, traits, Allocator>& lhs,
2637
- const charT* rhs);
2638
  ```
2639
 
2640
- *Returns:* `lhs.compare(rhs) < 0`.
2641
-
2642
- #### `operator>` <a id="string.op>">[[string.op>]]</a>
2643
-
2644
  ``` cpp
2645
  template<class charT, class traits, class Allocator>
2646
- bool operator> (const basic_string<charT, traits, Allocator>& lhs,
2647
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2648
  ```
2649
 
2650
- *Returns:* `lhs.compare(rhs) > 0`.
2651
 
2652
  ``` cpp
2653
- template<class charT, class traits, class Allocator>
2654
- bool operator> (const charT* lhs,
2655
- const basic_string<charT, traits, Allocator>& rhs);
2656
  ```
2657
 
2658
- *Returns:* `rhs.compare(lhs) < 0`.
2659
-
2660
  ``` cpp
2661
  template<class charT, class traits, class Allocator>
2662
- bool operator> (const basic_string<charT, traits, Allocator>& lhs,
2663
- const charT* rhs);
2664
  ```
2665
 
2666
- *Returns:* `lhs.compare(rhs) > 0`.
2667
-
2668
- #### `operator<=` <a id="string.op<=">[[string.op<=]]</a>
2669
 
2670
  ``` cpp
2671
- template<class charT, class traits, class Allocator>
2672
- bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
2673
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2674
  ```
2675
 
2676
- *Returns:* `lhs.compare(rhs) <= 0`.
2677
 
2678
  ``` cpp
2679
  template<class charT, class traits, class Allocator>
2680
- bool operator<=(const charT* lhs,
2681
- const basic_string<charT, traits, Allocator>& rhs);
2682
- ```
2683
-
2684
- *Returns:* `rhs.compare(lhs) >= 0`.
2685
-
2686
- ``` cpp
2687
  template<class charT, class traits, class Allocator>
2688
- bool operator<=(const basic_string<charT, traits, Allocator>& lhs,
2689
  const charT* rhs);
2690
- ```
2691
 
2692
- *Returns:* `lhs.compare(rhs) <= 0`.
2693
-
2694
- #### `operator>=` <a id="string.op>=">[[string.op>=]]</a>
2695
-
2696
- ``` cpp
2697
  template<class charT, class traits, class Allocator>
2698
- bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
2699
- const basic_string<charT, traits, Allocator>& rhs) noexcept;
2700
- ```
2701
-
2702
- *Returns:* `lhs.compare(rhs) >= 0`.
2703
-
2704
- ``` cpp
2705
  template<class charT, class traits, class Allocator>
2706
- bool operator>=(const charT* lhs,
2707
- const basic_string<charT, traits, Allocator>& rhs);
2708
  ```
2709
 
2710
- *Returns:* `rhs.compare(lhs) <= 0`.
2711
 
2712
  ``` cpp
2713
- template<class charT, class traits, class Allocator>
2714
- bool operator>=(const basic_string<charT, traits, Allocator>& lhs,
2715
- const charT* rhs);
2716
  ```
2717
 
2718
- *Returns:* `lhs.compare(rhs) >= 0`.
2719
-
2720
  #### `swap` <a id="string.special">[[string.special]]</a>
2721
 
2722
  ``` cpp
2723
  template<class charT, class traits, class Allocator>
2724
- void swap(basic_string<charT, traits, Allocator>& lhs,
 
2725
  basic_string<charT, traits, Allocator>& rhs)
2726
  noexcept(noexcept(lhs.swap(rhs)));
2727
  ```
2728
 
2729
- *Effects:* Equivalent to: `lhs.swap(rhs);`
2730
 
2731
  #### Inserters and extractors <a id="string.io">[[string.io]]</a>
2732
 
2733
  ``` cpp
2734
  template<class charT, class traits, class Allocator>
2735
  basic_istream<charT, traits>&
2736
- operator>>(basic_istream<charT, traits>& is,
2737
- basic_string<charT, traits, Allocator>& str);
2738
  ```
2739
 
2740
  *Effects:* Behaves as a formatted input
2741
- function ([[istream.formatted.reqmts]]). After constructing a `sentry`
2742
  object, if the sentry converts to `true`, calls `str.erase()` and then
2743
  extracts characters from `is` and appends them to `str` as if by calling
2744
  `str.append(1, c)`. If `is.width()` is greater than zero, the maximum
2745
  number `n` of characters appended is `is.width()`; otherwise `n` is
2746
  `str.max_size()`. Characters are extracted and appended until any of the
@@ -2753,12 +2351,12 @@ following occurs:
2753
 
2754
  After the last character (if any) is extracted, `is.width(0)` is called
2755
  and the `sentry` object is destroyed.
2756
 
2757
  If the function extracts no characters, it calls
2758
- `is.setstate(ios::failbit)`, which may throw
2759
- `ios_base::failure` ([[iostate.flags]]).
2760
 
2761
  *Returns:* `is`.
2762
 
2763
  ``` cpp
2764
  template<class charT, class traits, class Allocator>
@@ -2782,30 +2380,30 @@ template<class charT, class traits, class Allocator>
2782
  basic_string<charT, traits, Allocator>& str,
2783
  charT delim);
2784
  ```
2785
 
2786
  *Effects:* Behaves as an unformatted input
2787
- function ([[istream.unformatted]]), except that it does not affect the
2788
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2789
  constructing a `sentry` object, if the sentry converts to `true`, calls
2790
  `str.erase()` and then extracts characters from `is` and appends them to
2791
  `str` as if by calling `str.append(1, c)` until any of the following
2792
  occurs:
2793
 
2794
  - end-of-file occurs on the input sequence (in which case, the `getline`
2795
  function calls `is.setstate(ios_base::eofbit)`).
2796
  - `traits::eq(c, delim)` for the next available input character *c* (in
2797
- which case, *c* is extracted but not appended) ([[iostate.flags]])
2798
  - `str.max_size()` characters are stored (in which case, the function
2799
- calls `is.setstate(ios_base::failbit))` ([[iostate.flags]])
2800
 
2801
  The conditions are tested in the order shown. In any case, after the
2802
  last character is extracted, the `sentry` object is destroyed.
2803
 
2804
  If the function extracts no characters, it calls
2805
- `is.setstate(ios_base::failbit)` which may throw
2806
- `ios_base::failure` ([[iostate.flags]]).
2807
 
2808
  *Returns:* `is`.
2809
 
2810
  ``` cpp
2811
  template<class charT, class traits, class Allocator>
@@ -2818,21 +2416,53 @@ template<class charT, class traits, class Allocator>
2818
  basic_string<charT, traits, Allocator>& str);
2819
  ```
2820
 
2821
  *Returns:* `getline(is, str, is.widen(’\n’))`.
2822
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2823
  ### Numeric conversions <a id="string.conversions">[[string.conversions]]</a>
2824
 
2825
  ``` cpp
2826
- int stoi(const string& str, size_t* idx = 0, int base = 10);
2827
- long stol(const string& str, size_t* idx = 0, int base = 10);
2828
- unsigned long stoul(const string& str, size_t* idx = 0, int base = 10);
2829
- long long stoll(const string& str, size_t* idx = 0, int base = 10);
2830
- unsigned long long stoull(const string& str, size_t* idx = 0, int base = 10);
2831
  ```
2832
 
2833
- *Effects:* the first two functions call
2834
  `strtol(str.c_str(), ptr, base)`, and the last three functions call
2835
  `strtoul(str.c_str(), ptr, base)`, `strtoll(str.c_str(), ptr, base)`,
2836
  and `strtoull(str.c_str(), ptr, base)`, respectively. Each function
2837
  returns the converted result, if any. The argument `ptr` designates a
2838
  pointer to an object internal to the function that is used to determine
@@ -2847,13 +2477,13 @@ unconverted element of `str`.
2847
  `out_of_range` if `strtol`, `strtoul`, `strtoll` or `strtoull` sets
2848
  `errno` to `ERANGE`, or if the converted value is outside the range of
2849
  representable values for the return type.
2850
 
2851
  ``` cpp
2852
- float stof(const string& str, size_t* idx = 0);
2853
- double stod(const string& str, size_t* idx = 0);
2854
- long double stold(const string& str, size_t* idx = 0);
2855
  ```
2856
 
2857
  *Effects:* These functions call `strtof(str.c_str(), ptr)`,
2858
  `strtod(str.c_str(), ptr)`, and `strtold(str.c_str(), ptr)`,
2859
  respectively. Each function returns the converted result, if any. The
@@ -2888,18 +2518,18 @@ calling `sprintf(buf, fmt, val)` with a format specifier of `"%d"`,
2888
  `"%u"`, `"%ld"`, `"%lu"`, `"%lld"`, `"%llu"`, `"%f"`, `"%f"`, or
2889
  `"%Lf"`, respectively, where `buf` designates an internal character
2890
  buffer of sufficient size.
2891
 
2892
  ``` cpp
2893
- int stoi(const wstring& str, size_t* idx = 0, int base = 10);
2894
- long stol(const wstring& str, size_t* idx = 0, int base = 10);
2895
- unsigned long stoul(const wstring& str, size_t* idx = 0, int base = 10);
2896
- long long stoll(const wstring& str, size_t* idx = 0, int base = 10);
2897
- unsigned long long stoull(const wstring& str, size_t* idx = 0, int base = 10);
2898
  ```
2899
 
2900
- *Effects:* the first two functions call
2901
  `wcstol(str.c_str(), ptr, base)`, and the last three functions call
2902
  `wcstoul(str.c_str(), ptr, base)`, `wcstoll(str.c_str(), ptr, base)`,
2903
  and `wcstoull(str.c_str(), ptr, base)`, respectively. Each function
2904
  returns the converted result, if any. The argument `ptr` designates a
2905
  pointer to an object internal to the function that is used to determine
@@ -2913,13 +2543,13 @@ unconverted element of `str`.
2913
  `wcstoull` reports that no conversion could be performed. Throws
2914
  `out_of_range` if the converted value is outside the range of
2915
  representable values for the return type.
2916
 
2917
  ``` cpp
2918
- float stof(const wstring& str, size_t* idx = 0);
2919
- double stod(const wstring& str, size_t* idx = 0);
2920
- long double stold(const wstring& str, size_t* idx = 0);
2921
  ```
2922
 
2923
  *Effects:* These functions call `wcstof(str.c_str(), ptr)`,
2924
  `wcstod(str.c_str(), ptr)`, and `wcstold(str.c_str(), ptr)`,
2925
  respectively. Each function returns the converted result, if any. The
@@ -2955,41 +2585,53 @@ internal character buffer of sufficient size `buffsz`.
2955
 
2956
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2957
 
2958
  ``` cpp
2959
  template<> struct hash<string>;
 
2960
  template<> struct hash<u16string>;
2961
  template<> struct hash<u32string>;
2962
  template<> struct hash<wstring>;
 
 
 
 
 
2963
  ```
2964
 
2965
  If `S` is one of these string types, `SV` is the corresponding string
2966
  view type, and `s` is an object of type `S`, then
2967
  `hash<S>()(s) == hash<SV>()(SV(s))`.
2968
 
2969
  ### Suffix for `basic_string` literals <a id="basic.string.literals">[[basic.string.literals]]</a>
2970
 
2971
  ``` cpp
2972
- string operator""s(const char* str, size_t len);
2973
  ```
2974
 
2975
  *Returns:* `string{str, len}`.
2976
 
2977
  ``` cpp
2978
- u16string operator""s(const char16_t* str, size_t len);
 
 
 
 
 
 
2979
  ```
2980
 
2981
  *Returns:* `u16string{str, len}`.
2982
 
2983
  ``` cpp
2984
- u32string operator""s(const char32_t* str, size_t len);
2985
  ```
2986
 
2987
  *Returns:* `u32string{str, len}`.
2988
 
2989
  ``` cpp
2990
- wstring operator""s(const wchar_t* str, size_t len);
2991
  ```
2992
 
2993
  *Returns:* `wstring{str, len}`.
2994
 
2995
  [*Note 1*: The same suffix `s` is used for `chrono::duration` literals
@@ -2998,78 +2640,74 @@ to numbers and string literal suffixes apply to character array
2998
  literals. — *end note*]
2999
 
3000
  ## String view classes <a id="string.view">[[string.view]]</a>
3001
 
3002
  The class template `basic_string_view` describes an object that can
3003
- refer to a constant contiguous sequence of char-like (
3004
- [[strings.general]]) objects with the first element of the sequence at
3005
- position zero. In the rest of this section, the type of the char-like
3006
- objects held in a `basic_string_view` object is designated by `charT`.
3007
 
3008
  [*Note 1*: The library provides implicit conversions from
3009
  `const charT*` and `std::basic_string<charT, ...>` to
3010
  `std::basic_string_view<charT, ...>` so that user code can accept just
3011
  `std::basic_string_view<charT>` as a non-templated parameter wherever a
3012
  sequence of characters is expected. User-defined types should define
3013
  their own implicit conversions to `std::basic_string_view` in order to
3014
  interoperate with these functions. — *end note*]
3015
 
3016
- The complexity of `basic_string_view` member functions is 𝑂(1) unless
3017
- otherwise specified.
3018
-
3019
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
3020
 
3021
  ``` cpp
 
 
3022
  namespace std {
3023
  // [string.view.template], class template basic_string_view
3024
  template<class charT, class traits = char_traits<charT>>
3025
  class basic_string_view;
3026
 
 
 
 
 
 
3027
  // [string.view.comparison], non-member comparison functions
3028
  template<class charT, class traits>
3029
  constexpr bool operator==(basic_string_view<charT, traits> x,
3030
  basic_string_view<charT, traits> y) noexcept;
3031
  template<class charT, class traits>
3032
- constexpr bool operator!=(basic_string_view<charT, traits> x,
3033
- basic_string_view<charT, traits> y) noexcept;
3034
- template<class charT, class traits>
3035
- constexpr bool operator< (basic_string_view<charT, traits> x,
3036
- basic_string_view<charT, traits> y) noexcept;
3037
- template<class charT, class traits>
3038
- constexpr bool operator> (basic_string_view<charT, traits> x,
3039
- basic_string_view<charT, traits> y) noexcept;
3040
- template<class charT, class traits>
3041
- constexpr bool operator<=(basic_string_view<charT, traits> x,
3042
- basic_string_view<charT, traits> y) noexcept;
3043
- template<class charT, class traits>
3044
- constexpr bool operator>=(basic_string_view<charT, traits> x,
3045
- basic_string_view<charT, traits> y) noexcept;
3046
  // see [string.view.comparison], sufficient additional overloads of comparison functions
3047
 
3048
  // [string.view.io], inserters and extractors
3049
  template<class charT, class traits>
3050
  basic_ostream<charT, traits>&
3051
  operator<<(basic_ostream<charT, traits>& os,
3052
  basic_string_view<charT, traits> str);
3053
 
3054
  // basic_string_view typedef names
3055
  using string_view = basic_string_view<char>;
 
3056
  using u16string_view = basic_string_view<char16_t>;
3057
  using u32string_view = basic_string_view<char32_t>;
3058
  using wstring_view = basic_string_view<wchar_t>;
3059
 
3060
  // [string.view.hash], hash support
3061
  template<class T> struct hash;
3062
  template<> struct hash<string_view>;
 
3063
  template<> struct hash<u16string_view>;
3064
  template<> struct hash<u32string_view>;
3065
  template<> struct hash<wstring_view>;
3066
 
3067
  inline namespace literals {
3068
  inline namespace string_view_literals {
3069
  // [string.view.literals], suffix for basic_string_view literals
3070
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
 
3071
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3072
  constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
3073
  constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
3074
  }
3075
  }
@@ -3104,10 +2742,12 @@ public:
3104
  constexpr basic_string_view() noexcept;
3105
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
3106
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
3107
  constexpr basic_string_view(const charT* str);
3108
  constexpr basic_string_view(const charT* str, size_type len);
 
 
3109
 
3110
  // [string.view.iterators], iterator support
3111
  constexpr const_iterator begin() const noexcept;
3112
  constexpr const_iterator end() const noexcept;
3113
  constexpr const_iterator cbegin() const noexcept;
@@ -3119,11 +2759,11 @@ public:
3119
 
3120
  // [string.view.capacity], capacity
3121
  constexpr size_type size() const noexcept;
3122
  constexpr size_type length() const noexcept;
3123
  constexpr size_type max_size() const noexcept;
3124
- constexpr bool empty() const noexcept;
3125
 
3126
  // [string.view.access], element access
3127
  constexpr const_reference operator[](size_type pos) const;
3128
  constexpr const_reference at(size_type pos) const;
3129
  constexpr const_reference front() const;
@@ -3134,29 +2774,39 @@ public:
3134
  constexpr void remove_prefix(size_type n);
3135
  constexpr void remove_suffix(size_type n);
3136
  constexpr void swap(basic_string_view& s) noexcept;
3137
 
3138
  // [string.view.ops], string operations
3139
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
3140
 
3141
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
 
3142
  constexpr int compare(basic_string_view s) const noexcept;
3143
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
3144
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
3145
  size_type pos2, size_type n2) const;
3146
  constexpr int compare(const charT* s) const;
3147
  constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
3148
- constexpr int compare(size_type pos1, size_type n1, const charT* s,
3149
- size_type n2) const;
 
 
 
 
 
 
 
 
3150
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
3151
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
3152
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
3153
  constexpr size_type find(const charT* s, size_type pos = 0) const;
3154
  constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
3155
  constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
3156
  constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
3157
  constexpr size_type rfind(const charT* s, size_type pos = npos) const;
 
3158
  constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
3159
  constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
3160
  constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
3161
  constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
3162
  constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
@@ -3177,73 +2827,102 @@ public:
3177
 
3178
  private:
3179
  const_pointer data_; // exposition only
3180
  size_type size_; // exposition only
3181
  };
 
 
 
 
3182
  ```
3183
 
3184
  In every specialization `basic_string_view<charT, traits>`, the type
3185
- `traits` shall satisfy the character traits requirements (
3186
- [[char.traits]]), and the type `traits::char_type` shall name the same
3187
- type as `charT`.
 
 
 
 
 
 
 
 
 
3188
 
3189
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
3190
 
3191
  ``` cpp
3192
  constexpr basic_string_view() noexcept;
3193
  ```
3194
 
3195
- *Effects:* Constructs an empty `basic_string_view`.
3196
-
3197
- *Postconditions:* `size_ == 0` and `data_ == nullptr`.
3198
 
3199
  ``` cpp
3200
  constexpr basic_string_view(const charT* str);
3201
  ```
3202
 
3203
- *Requires:* \[`str`, `str + traits::length(str)`) is a valid range.
3204
 
3205
- *Effects:* Constructs a `basic_string_view`, with the postconditions in
3206
- Table  [[tab:string.view.ctr.2]].
3207
 
3208
  *Complexity:* 𝑂(`traits::length(str)`).
3209
 
3210
  ``` cpp
3211
  constexpr basic_string_view(const charT* str, size_type len);
3212
  ```
3213
 
3214
- *Requires:* \[`str`, `str + len`) is a valid range.
3215
 
3216
- *Effects:* Constructs a `basic_string_view`, with the postconditions in
3217
- Table  [[tab:string.view.ctr.3]].
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3218
 
3219
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
3220
 
3221
  ``` cpp
3222
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
3223
  ```
3224
 
3225
- A type that meets the requirements of a constant random access
3226
- iterator ([[random.access.iterators]]) and of a contiguous
3227
- iterator ([[iterator.requirements.general]]) whose `value_type` is the
3228
- template parameter `charT`.
 
3229
 
3230
- For a `basic_string_view str`, any operation that invalidates a pointer
3231
- in the range \[`str.data()`, `str.data() + str.size()`) invalidates
3232
- pointers, iterators, and references returned from `str`’s methods.
3233
-
3234
- All requirements on container iterators ([[container.requirements]])
3235
- apply to `basic_string_view::const_iterator` as well.
3236
 
3237
  ``` cpp
3238
  constexpr const_iterator begin() const noexcept;
3239
  constexpr const_iterator cbegin() const noexcept;
3240
  ```
3241
 
3242
  *Returns:* An iterator such that
3243
 
3244
- - if `!empty()`, `&*begin() == data_`,
3245
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
3246
  valid range.
3247
 
3248
  ``` cpp
3249
  constexpr const_iterator end() const noexcept;
@@ -3268,15 +2947,10 @@ constexpr const_reverse_iterator crend() const noexcept;
3268
 
3269
  #### Capacity <a id="string.view.capacity">[[string.view.capacity]]</a>
3270
 
3271
  ``` cpp
3272
  constexpr size_type size() const noexcept;
3273
- ```
3274
-
3275
- *Returns:* `size_`.
3276
-
3277
- ``` cpp
3278
  constexpr size_type length() const noexcept;
3279
  ```
3280
 
3281
  *Returns:* `size_`.
3282
 
@@ -3286,22 +2960,22 @@ constexpr size_type max_size() const noexcept;
3286
 
3287
  *Returns:* The largest possible number of char-like objects that can be
3288
  referred to by a `basic_string_view`.
3289
 
3290
  ``` cpp
3291
- constexpr bool empty() const noexcept;
3292
  ```
3293
 
3294
  *Returns:* `size_ == 0`.
3295
 
3296
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
3297
 
3298
  ``` cpp
3299
  constexpr const_reference operator[](size_type pos) const;
3300
  ```
3301
 
3302
- *Requires:* `pos < size()`.
3303
 
3304
  *Returns:* `data_[pos]`.
3305
 
3306
  *Throws:* Nothing.
3307
 
@@ -3319,21 +2993,21 @@ constexpr const_reference at(size_type pos) const;
3319
 
3320
  ``` cpp
3321
  constexpr const_reference front() const;
3322
  ```
3323
 
3324
- *Requires:* `!empty()`.
3325
 
3326
  *Returns:* `data_[0]`.
3327
 
3328
  *Throws:* Nothing.
3329
 
3330
  ``` cpp
3331
  constexpr const_reference back() const;
3332
  ```
3333
 
3334
- *Requires:* `!empty()`.
3335
 
3336
  *Returns:* `data_[size() - 1]`.
3337
 
3338
  *Throws:* Nothing.
3339
 
@@ -3341,30 +3015,31 @@ constexpr const_reference back() const;
3341
  constexpr const_pointer data() const noexcept;
3342
  ```
3343
 
3344
  *Returns:* `data_`.
3345
 
3346
- [*Note 2*: Unlike `basic_string::data()` and string literals, `data()`
3347
- may return a pointer to a buffer that is not null-terminated. Therefore
3348
- it is typically a mistake to pass `data()` to a function that takes just
3349
- a `const charT*` and expects a null-terminated string. — *end note*]
 
3350
 
3351
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
3352
 
3353
  ``` cpp
3354
  constexpr void remove_prefix(size_type n);
3355
  ```
3356
 
3357
- *Requires:* `n <= size()`.
3358
 
3359
  *Effects:* Equivalent to: `data_ += n; size_ -= n;`
3360
 
3361
  ``` cpp
3362
  constexpr void remove_suffix(size_type n);
3363
  ```
3364
 
3365
- *Requires:* `n <= size()`.
3366
 
3367
  *Effects:* Equivalent to: `size_ -= n;`
3368
 
3369
  ``` cpp
3370
  constexpr void swap(basic_string_view& s) noexcept;
@@ -3373,18 +3048,18 @@ constexpr void swap(basic_string_view& s) noexcept;
3373
  *Effects:* Exchanges the values of `*this` and `s`.
3374
 
3375
  #### String operations <a id="string.view.ops">[[string.view.ops]]</a>
3376
 
3377
  ``` cpp
3378
- size_type copy(charT* s, size_type n, size_type pos = 0) const;
3379
  ```
3380
 
3381
  Let `rlen` be the smaller of `n` and `size() - pos`.
3382
 
3383
  *Throws:* `out_of_range` if `pos > size()`.
3384
 
3385
- *Requires:* \[`s`, `s + rlen`) is a valid range.
3386
 
3387
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
3388
 
3389
  *Returns:* `rlen`.
3390
 
@@ -3415,13 +3090,13 @@ compare. The function then compares the two strings by calling
3415
 
3416
  *Complexity:* 𝑂(`rlen`).
3417
 
3418
  *Returns:* The nonzero result if the result of the comparison is
3419
  nonzero. Otherwise, returns a value as indicated in
3420
- Table  [[tab:string.view.compare]].
3421
 
3422
- **Table: `compare()` results** <a id="tab:string.view.compare">[tab:string.view.compare]</a>
3423
 
3424
  | Condition | Return Value |
3425
  | ---------------------- | ------------ |
3426
  | `size() < str.size()` | `< 0` |
3427
  | `size() == str.size()` | ` 0` |
@@ -3453,50 +3128,84 @@ constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
3453
 
3454
  *Effects:* Equivalent to:
3455
  `return substr(pos1, n1).compare(basic_string_view(s));`
3456
 
3457
  ``` cpp
3458
- constexpr int compare(size_type pos1, size_type n1,
3459
- const charT* s, size_type n2) const;
3460
  ```
3461
 
3462
  *Effects:* Equivalent to:
3463
  `return substr(pos1, n1).compare(basic_string_view(s, n2));`
3464
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3465
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
3466
 
3467
- This section specifies the `basic_string_view` member functions named
3468
- `find`, `rfind`, `find_first_of`, `find_last_of`, `find_first_not_of`,
3469
- and `find_last_not_of`.
3470
 
3471
- Member functions in this section have complexity
3472
- 𝑂(`size() * str.size()`) at worst, although implementations are
3473
- encouraged to do better.
3474
-
3475
- Each member function of the form
3476
 
 
3477
  ``` cpp
3478
- constexpr return-type F(const charT* s, size_type pos);
3479
  ```
3480
 
3481
- is equivalent to `return F(basic_string_view(s), pos);`
3482
-
3483
- Each member function of the form
3484
-
3485
  ``` cpp
3486
- constexpr return-type F(const charT* s, size_type pos, size_type n);
3487
  ```
3488
 
3489
- is equivalent to `return F(basic_string_view(s, n), pos);`
3490
-
3491
- Each member function of the form
3492
-
3493
  ``` cpp
3494
- constexpr return-type F(charT c, size_type pos);
3495
  ```
3496
 
3497
- is equivalent to `return F(basic_string_view(&c, 1), pos);`
 
3498
 
3499
  ``` cpp
3500
  constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
3501
  ```
3502
 
@@ -3596,19 +3305,31 @@ conditions hold:
3596
  *Effects:* Determines `xpos`.
3597
 
3598
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
3599
  Otherwise, returns `npos`.
3600
 
 
 
 
 
 
 
 
 
 
 
 
 
3601
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
3602
 
3603
  Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
3604
  of `S`. Implementations shall provide sufficient additional overloads
3605
  marked `constexpr` and `noexcept` so that an object `t` with an implicit
3606
- conversion to `S` can be compared according to Table 
3607
- [[tab:string.view.comparison.overloads]].
3608
 
3609
- **Table: Additional `basic_string_view` comparison overloads** <a id="tab:string.view.comparison.overloads">[tab:string.view.comparison.overloads]</a>
3610
 
3611
  | Expression | Equivalent to |
3612
  | ---------- | ------------- |
3613
  | `t == sv` | `S(t) == sv` |
3614
  | `sv == t` | `sv == S(t)` |
@@ -3620,31 +3341,27 @@ conversion to `S` can be compared according to Table 
3620
  | `sv > t` | `sv > S(t)` |
3621
  | `t <= sv` | `S(t) <= sv` |
3622
  | `sv <= t` | `sv <= S(t)` |
3623
  | `t >= sv` | `S(t) >= sv` |
3624
  | `sv >= t` | `sv >= S(t)` |
 
 
3625
 
3626
 
3627
  [*Example 1*:
3628
 
3629
  A sample conforming implementation for `operator==` would be:
3630
 
3631
  ``` cpp
3632
- template<class T> using __identity = decay_t<T>;
3633
  template<class charT, class traits>
3634
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
3635
  basic_string_view<charT, traits> rhs) noexcept {
3636
  return lhs.compare(rhs) == 0;
3637
  }
3638
  template<class charT, class traits>
3639
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
3640
- __identity<basic_string_view<charT, traits>> rhs) noexcept {
3641
- return lhs.compare(rhs) == 0;
3642
- }
3643
- template<class charT, class traits>
3644
- constexpr bool operator==(__identity<basic_string_view<charT, traits>> lhs,
3645
- basic_string_view<charT, traits> rhs) noexcept {
3646
  return lhs.compare(rhs) == 0;
3647
  }
3648
  ```
3649
 
3650
  — *end example*]
@@ -3657,59 +3374,29 @@ template<class charT, class traits>
3657
 
3658
  *Returns:* `lhs.compare(rhs) == 0`.
3659
 
3660
  ``` cpp
3661
  template<class charT, class traits>
3662
- constexpr bool operator!=(basic_string_view<charT, traits> lhs,
3663
- basic_string_view<charT, traits> rhs) noexcept;
3664
  ```
3665
 
3666
- *Returns:* `lhs.compare(rhs) != 0`.
 
3667
 
3668
- ``` cpp
3669
- template<class charT, class traits>
3670
- constexpr bool operator< (basic_string_view<charT, traits> lhs,
3671
- basic_string_view<charT, traits> rhs) noexcept;
3672
- ```
3673
-
3674
- *Returns:* `lhs.compare(rhs) < 0`.
3675
-
3676
- ``` cpp
3677
- template<class charT, class traits>
3678
- constexpr bool operator> (basic_string_view<charT, traits> lhs,
3679
- basic_string_view<charT, traits> rhs) noexcept;
3680
- ```
3681
-
3682
- *Returns:* `lhs.compare(rhs) > 0`.
3683
-
3684
- ``` cpp
3685
- template<class charT, class traits>
3686
- constexpr bool operator<=(basic_string_view<charT, traits> lhs,
3687
- basic_string_view<charT, traits> rhs) noexcept;
3688
- ```
3689
-
3690
- *Returns:* `lhs.compare(rhs) <= 0`.
3691
-
3692
- ``` cpp
3693
- template<class charT, class traits>
3694
- constexpr bool operator>=(basic_string_view<charT, traits> lhs,
3695
- basic_string_view<charT, traits> rhs) noexcept;
3696
- ```
3697
-
3698
- *Returns:* `lhs.compare(rhs) >= 0`.
3699
 
3700
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
3701
 
3702
  ``` cpp
3703
  template<class charT, class traits>
3704
  basic_ostream<charT, traits>&
3705
- operator<<(basic_ostream<charT, traits>& os,
3706
- basic_string_view<charT, traits> str);
3707
  ```
3708
 
3709
  *Effects:* Behaves as a formatted output
3710
- function ([[ostream.formatted.reqmts]]) of `os`. Forms a character
3711
  sequence `seq`, initially consisting of the elements defined by the
3712
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
3713
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
3714
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
3715
  `os.width()` and `str.size()`; then calls `os.width(0)`.
@@ -3718,29 +3405,36 @@ calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
3718
 
3719
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
3720
 
3721
  ``` cpp
3722
  template<> struct hash<string_view>;
 
3723
  template<> struct hash<u16string_view>;
3724
  template<> struct hash<u32string_view>;
3725
  template<> struct hash<wstring_view>;
3726
  ```
3727
 
3728
- The specialization is enabled ([[unord.hash]]).
3729
 
3730
  [*Note 1*: The hash value of a string view object is equal to the hash
3731
- value of the corresponding string object
3732
- ([[basic.string.hash]]). — *end note*]
3733
 
3734
  ### Suffix for `basic_string_view` literals <a id="string.view.literals">[[string.view.literals]]</a>
3735
 
3736
  ``` cpp
3737
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
3738
  ```
3739
 
3740
  *Returns:* `string_view{str, len}`.
3741
 
 
 
 
 
 
 
3742
  ``` cpp
3743
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3744
  ```
3745
 
3746
  *Returns:* `u16string_view{str, len}`.
@@ -3781,11 +3475,11 @@ namespace std {
3781
  ```
3782
 
3783
  The contents and meaning of the header `<cctype>` are the same as the C
3784
  standard library header `<ctype.h>`.
3785
 
3786
- ISO C 7.4
3787
 
3788
  ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
3789
 
3790
  ``` cpp
3791
  namespace std {
@@ -3817,11 +3511,11 @@ namespace std {
3817
  ```
3818
 
3819
  The contents and meaning of the header `<cwctype>` are the same as the C
3820
  standard library header `<wctype.h>`.
3821
 
3822
- ISO C 7.30
3823
 
3824
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
3825
 
3826
  ``` cpp
3827
  namespace std {
@@ -3837,21 +3531,21 @@ namespace std {
3837
  int strcmp(const char* s1, const char* s2);
3838
  int strcoll(const char* s1, const char* s2);
3839
  int strncmp(const char* s1, const char* s2, size_t n);
3840
  size_t strxfrm(char* s1, const char* s2, size_t n);
3841
  const void* memchr(const void* s, int c, size_t n); // see [library.c]
3842
- void* memchr(void* s, int c, size_t n) // see [library.c]
3843
- const char* strchr(const char* s, int c) // see [library.c]
3844
- char* strchr(char* s, int c) // see [library.c]
3845
  size_t strcspn(const char* s1, const char* s2);
3846
- const char* strpbrk(const char* s1, const char* s2) // see [library.c]
3847
- char* strpbrk(char* s1, const char* s2) // see [library.c]
3848
- const char* strrchr(const char* s, int c) // see [library.c]
3849
- char* strrchr(char* s, int c) // see [library.c]
3850
  size_t strspn(const char* s1, const char* s2);
3851
- const char* strstr(const char* s1, const char* s2) // see [library.c]
3852
- char* strstr(char* s1, const char* s2) // see [library.c]
3853
  char* strtok(char* s1, const char* s2);
3854
  void* memset(void* s, int c, size_t n);
3855
  char* strerror(int errnum);
3856
  size_t strlen(const char* s);
3857
  }
@@ -3861,20 +3555,22 @@ namespace std {
3861
 
3862
  The contents and meaning of the header `<cstring>` are the same as the C
3863
  standard library header `<string.h>`.
3864
 
3865
  The functions `strerror` and `strtok` are not required to avoid data
3866
- races ([[res.on.data.races]]).
3867
 
3868
- The functions `memcpy` and `memmove` are signal-safe ([[csignal.syn]]).
 
 
 
3869
 
3870
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
3871
- `memchr`, have different signatures in this International Standard, but
3872
- they have the same behavior as in the C standard library (
3873
- [[library.c]]). — *end note*]
3874
 
3875
- ISO C 7.24.
3876
 
3877
  ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
3878
 
3879
  ``` cpp
3880
  namespace std {
@@ -3922,23 +3618,23 @@ namespace std {
3922
  int wcscmp(const wchar_t* s1, const wchar_t* s2);
3923
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
3924
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3925
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
3926
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3927
- const wchar_t* wcschr(const wchar_t* s, wchar_t c) // see [library.c]
3928
- wchar_t* wcschr(wchar_t* s, wchar_t c) // see [library.c]
3929
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
3930
- const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2) // see [library.c]
3931
- wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2) // see [library.c]
3932
- const wchar_t* wcsrchr(const wchar_t* s, wchar_t c) // see [library.c]
3933
- wchar_t* wcsrchr(wchar_t* s, wchar_t c) // see [library.c]
3934
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
3935
- const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2) // see [library.c]
3936
- wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2) // see [library.c]
3937
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
3938
- const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n) // see [library.c]
3939
- wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n) // see [library.c]
3940
  size_t wcslen(const wchar_t* s);
3941
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
3942
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
3943
  wint_t btowc(int c);
3944
  int wctob(wint_t c);
@@ -3961,41 +3657,42 @@ namespace std {
3961
  The contents and meaning of the header `<cwchar>` are the same as the C
3962
  standard library header `<wchar.h>`, except that it does not declare a
3963
  type `wchar_t`.
3964
 
3965
  [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
3966
- `wmemchr` have different signatures in this International Standard, but
3967
- they have the same behavior as in the C standard library (
3968
- [[library.c]]). — *end note*]
3969
 
3970
- ISO C 7.29
3971
 
3972
  ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
3973
 
3974
  ``` cpp
3975
  namespace std {
3976
  using mbstate_t = see below;
3977
  using size_t = see [support.types.layout];
3978
 
 
 
3979
  size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
3980
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
3981
  size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
3982
  size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
3983
  }
3984
  ```
3985
 
3986
  The contents and meaning of the header `<cuchar>` are the same as the C
3987
- standard library header `<uchar.h>`, except that it does not declare
3988
- types `char16_t` nor `char32_t`.
 
3989
 
3990
- ISO C 7.28
3991
 
3992
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
3993
 
3994
- [*Note 1*: The headers `<cstdlib>` ([[cstdlib.syn]]) and `<cwchar>` (
3995
- [[cwchar.syn]]) declare the functions described in this
3996
- subclause. — *end note*]
3997
 
3998
  ``` cpp
3999
  int mbsinit(const mbstate_t* ps);
4000
  int mblen(const char* s, size_t n);
4001
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
@@ -4003,24 +3700,24 @@ size_t wcstombs(char* s, const wchar_t* pwcs, size_t n);
4003
  ```
4004
 
4005
  *Effects:* These functions have the semantics specified in the C
4006
  standard library.
4007
 
4008
- ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
4009
 
4010
  ``` cpp
4011
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
4012
  int wctomb(char* s, wchar_t wchar);
4013
  ```
4014
 
4015
  *Effects:* These functions have the semantics specified in the C
4016
  standard library.
4017
 
4018
  *Remarks:* Calls to these functions may introduce a data
4019
- race ([[res.on.data.races]]) with other calls to the same function.
4020
 
4021
- ISO C 7.22.7
4022
 
4023
  ``` cpp
4024
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
4025
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
4026
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
@@ -4030,97 +3727,160 @@ size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
4030
 
4031
  *Effects:* These functions have the semantics specified in the C
4032
  standard library.
4033
 
4034
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
4035
- a null pointer value may introduce a data race ([[res.on.data.races]])
4036
  with other calls to the same function with an `mbstate_t*` argument that
4037
  is a null pointer value.
4038
 
4039
- ISO C 7.29.6.3
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4040
 
4041
  <!-- Link reference definitions -->
4042
  [basic.string]: #basic.string
4043
  [basic.string.hash]: #basic.string.hash
4044
  [basic.string.literals]: #basic.string.literals
4045
  [basic.types]: basic.md#basic.types
4046
  [c.mb.wcs]: #c.mb.wcs
4047
  [c.strings]: #c.strings
4048
  [cctype.syn]: #cctype.syn
4049
  [char.traits]: #char.traits
 
4050
  [char.traits.require]: #char.traits.require
4051
  [char.traits.specializations]: #char.traits.specializations
4052
  [char.traits.specializations.char]: #char.traits.specializations.char
4053
- [char.traits.specializations.char16_t]: #char.traits.specializations.char16_t
4054
- [char.traits.specializations.char32_t]: #char.traits.specializations.char32_t
 
4055
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
4056
  [char.traits.typedefs]: #char.traits.typedefs
4057
  [container.requirements]: containers.md#container.requirements
4058
  [container.requirements.general]: containers.md#container.requirements.general
4059
- [csignal.syn]: language.md#csignal.syn
4060
- [cstdlib.syn]: language.md#cstdlib.syn
 
 
 
4061
  [cstring.syn]: #cstring.syn
4062
  [cuchar.syn]: #cuchar.syn
4063
  [cwchar.syn]: #cwchar.syn
4064
  [cwctype.syn]: #cwctype.syn
 
4065
  [input.output]: input.md#input.output
 
4066
  [iostate.flags]: input.md#iostate.flags
4067
  [iostream.forward]: input.md#iostream.forward
4068
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
4069
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
4070
  [istream.unformatted]: input.md#istream.unformatted
 
4071
  [iterator.range]: iterators.md#iterator.range
4072
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
4073
- [length.error]: diagnostics.md#length.error
4074
  [library.c]: library.md#library.c
4075
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
4076
- [out.of.range]: diagnostics.md#out.of.range
4077
  [random.access.iterators]: iterators.md#random.access.iterators
4078
  [res.on.data.races]: library.md#res.on.data.races
4079
- [sequence.reqmts]: containers.md#sequence.reqmts
4080
  [string.access]: #string.access
4081
  [string.accessors]: #string.accessors
4082
  [string.append]: #string.append
4083
  [string.assign]: #string.assign
4084
  [string.capacity]: #string.capacity
4085
  [string.classes]: #string.classes
 
4086
  [string.compare]: #string.compare
4087
  [string.cons]: #string.cons
4088
  [string.conversions]: #string.conversions
4089
  [string.copy]: #string.copy
 
4090
  [string.erase]: #string.erase
 
4091
  [string.find]: #string.find
4092
- [string.find.first.not.of]: #string.find.first.not.of
4093
- [string.find.first.of]: #string.find.first.of
4094
- [string.find.last.not.of]: #string.find.last.not.of
4095
- [string.find.last.of]: #string.find.last.of
4096
  [string.insert]: #string.insert
4097
  [string.io]: #string.io
4098
  [string.iterators]: #string.iterators
4099
  [string.modifiers]: #string.modifiers
4100
  [string.nonmembers]: #string.nonmembers
4101
- [string.op!=]: #string.op!=
4102
- [string.op+]: #string.op+
4103
- [string.op+=]: #string.op+=
4104
- [string.op<]: #string.op<
4105
- [string.op<=]: #string.op<=
4106
- [string.op>]: #string.op>
4107
- [string.op>=]: #string.op>=
4108
- [string.operator==]: #string.operator==
4109
  [string.ops]: #string.ops
4110
  [string.replace]: #string.replace
4111
  [string.require]: #string.require
4112
- [string.rfind]: #string.rfind
4113
  [string.special]: #string.special
 
4114
  [string.substr]: #string.substr
4115
  [string.swap]: #string.swap
4116
  [string.syn]: #string.syn
4117
  [string.view]: #string.view
4118
  [string.view.access]: #string.view.access
4119
  [string.view.capacity]: #string.view.capacity
 
4120
  [string.view.comparison]: #string.view.comparison
 
4121
  [string.view.cons]: #string.view.cons
 
4122
  [string.view.find]: #string.view.find
4123
  [string.view.hash]: #string.view.hash
4124
  [string.view.io]: #string.view.io
4125
  [string.view.iterators]: #string.view.iterators
4126
  [string.view.literals]: #string.view.literals
@@ -4128,39 +3888,16 @@ ISO C 7.29.6.3
4128
  [string.view.ops]: #string.view.ops
4129
  [string.view.synop]: #string.view.synop
4130
  [string.view.template]: #string.view.template
4131
  [strings]: #strings
4132
  [strings.general]: #strings.general
4133
- [tab:char.traits.require]: #tab:char.traits.require
4134
- [tab:copyassignable]: #tab:copyassignable
4135
- [tab:copyconstructible]: #tab:copyconstructible
4136
- [tab:defaultconstructible]: #tab:defaultconstructible
4137
- [tab:string.view.compare]: #tab:string.view.compare
4138
- [tab:string.view.comparison.overloads]: #tab:string.view.comparison.overloads
4139
- [tab:string.view.ctr.2]: #tab:string.view.ctr.2
4140
- [tab:string.view.ctr.3]: #tab:string.view.ctr.3
4141
- [tab:strings.compare]: #tab:strings.compare
4142
- [tab:strings.ctr.1]: #tab:strings.ctr.1
4143
- [tab:strings.ctr.2]: #tab:strings.ctr.2
4144
- [tab:strings.ctr.3]: #tab:strings.ctr.3
4145
- [tab:strings.ctr.4]: #tab:strings.ctr.4
4146
- [tab:strings.ctr.5]: #tab:strings.ctr.5
4147
- [tab:strings.ctr.6]: #tab:strings.ctr.6
4148
- [tab:strings.ctr.cpy]: #tab:strings.ctr.cpy
4149
- [tab:strings.lib.summary]: #tab:strings.lib.summary
4150
- [tab:strings.op=]: #tab:strings.op=
4151
  [unord.hash]: utilities.md#unord.hash
4152
  [utility.swap]: utilities.md#utility.swap
4153
 
4154
  [^1]: If `eof()` can be held in `char_type` then some iostreams
4155
- operations may give surprising results.
4156
 
4157
- [^2]: `Allocator::value_type` must name the same type as `charT` (
4158
- [[string.require]]).
4159
-
4160
- [^3]: For example, as an argument to non-member functions `swap()` (
4161
- [[string.special]]), `operator>{}>()` ([[string.io]]), and
4162
- `getline()` ([[string.io]]), or as an argument to
4163
- `basic_string::swap()`.
4164
-
4165
- [^4]: `reserve()` uses `allocator_traits<Allocator>::allocate()` which
4166
- may throw an appropriate exception.
 
1
  # Strings library <a id="strings">[[strings]]</a>
2
 
3
  ## General <a id="strings.general">[[strings.general]]</a>
4
 
5
  This Clause describes components for manipulating sequences of any
6
+ non-array trivial standard-layout [[basic.types]] type. Such types are
7
+ called *char-like types*, and objects of char-like types are called
8
+ *char-like objects* or simply *characters*.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
 
10
+ The following subclauses describe a character traits class, string
11
+ classes, and null-terminated sequence utilities, as summarized in
12
+ [[strings.summary]].
13
 
14
  ## Character traits <a id="char.traits">[[char.traits]]</a>
15
 
16
  This subclause defines requirements on classes representing *character
17
  traits*, and defines a class template `char_traits<charT>`, along with
18
+ five specializations, `char_traits<char>`, `char_traits<char8_t>`,
19
+ `char_traits<char16_t>`, `char_traits<char32_t>`, and
20
+ `char_traits<wchar_t>`, that meet those requirements.
21
 
22
+ Most classes specified in [[string.classes]], [[string.view]], and
23
  [[input.output]] need a set of related types and functions to complete
24
  the definition of their semantics. These types and functions are
25
  provided as a set of member *typedef-name*s and functions in the
26
  template parameter `traits` used by each such template. This subclause
27
  defines the semantics of these members.
28
 
29
+ To specialize those templates to generate a string, string view, or
30
+ iostream class to handle a particular character container type
31
+ [[defns.character.container]] `C`, that and its related character traits
32
+ class `X` are passed as a pair of parameters to the string, string view,
33
+ or iostream template as parameters `charT` and `traits`. If
34
+ `X::char_type` is not the same type as `C`, the program is ill-formed.
 
 
 
 
 
35
 
36
  ### Character traits requirements <a id="char.traits.require">[[char.traits.require]]</a>
37
 
38
+ In [[char.traits.req]], `X` denotes a traits class defining types and
39
+ functions for the character container type `C`; `c` and `d` denote
40
+ values of type `C`; `p` and `q` denote values of type `const C*`; `s`
41
+ denotes a value of type `C*`; `n`, `i` and `j` denote values of type
42
+ `size_t`; `e` and `f` denote values of type `X::int_type`; `pos` denotes
43
+ a value of type `X::pos_type`; and `r` denotes an lvalue of type `C`.
44
+ Operations on `X` shall not throw exceptions.
 
45
 
46
  The class template
47
 
48
  ``` cpp
49
  template<class charT> struct char_traits;
50
  ```
51
 
52
+ is provided in the header `<string>` as a basis for explicit
53
  specializations.
54
 
55
  ### Traits typedefs <a id="char.traits.typedefs">[[char.traits.typedefs]]</a>
56
 
57
  ``` cpp
58
+ using int_type = see below;
59
  ```
60
 
61
+ *Preconditions:* `int_type` shall be able to represent all of the valid
62
+ characters converted from the corresponding `char_type` values, as well
63
+ as an end-of-file value, `eof()`. [^1]
64
 
65
  ``` cpp
66
+ using state_type = see below;
67
  ```
68
 
69
+ *Preconditions:* `state_type` meets the *Cpp17Destructible*
70
+ ([[cpp17.destructible]]), *Cpp17CopyAssignable*
71
+ ([[cpp17.copyassignable]]), *Cpp17CopyConstructible*
72
+ ([[cpp17.copyconstructible]]), and *Cpp17DefaultConstructible*
73
+ ([[cpp17.defaultconstructible]]) requirements.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
74
 
75
  ### `char_traits` specializations <a id="char.traits.specializations">[[char.traits.specializations]]</a>
76
 
77
  ``` cpp
78
  namespace std {
79
  template<> struct char_traits<char>;
80
+ template<> struct char_traits<char8_t>;
81
  template<> struct char_traits<char16_t>;
82
  template<> struct char_traits<char32_t>;
83
  template<> struct char_traits<wchar_t>;
84
  }
85
  ```
86
 
87
+ The header `<string>` defines five specializations of the class template
88
+ `char_traits`: `char_traits<{}char>`, `char_traits<char8_t>`,
89
+ `char_traits<char16_t>`, `char_traits<char32_t>`, and
90
+ `char_traits<wchar_t>`.
 
 
91
 
92
  #### `struct char_traits<char>` <a id="char.traits.specializations.char">[[char.traits.specializations.char]]</a>
93
 
94
  ``` cpp
95
  namespace std {
 
97
  using char_type = char;
98
  using int_type = int;
99
  using off_type = streamoff;
100
  using pos_type = streampos;
101
  using state_type = mbstate_t;
102
+ using comparison_category = strong_ordering;
103
 
104
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
105
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
106
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
107
 
108
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
109
  static constexpr size_t length(const char_type* s);
110
  static constexpr const char_type* find(const char_type* s, size_t n,
111
  const char_type& a);
112
+ static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);
113
+ static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);
114
+ static constexpr char_type* assign(char_type* s, size_t n, char_type a);
115
 
116
  static constexpr int_type not_eof(int_type c) noexcept;
117
  static constexpr char_type to_char_type(int_type c) noexcept;
118
  static constexpr int_type to_int_type(char_type c) noexcept;
119
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
120
  static constexpr int_type eof() noexcept;
121
  };
122
  }
123
  ```
124
 
 
 
 
 
 
 
 
 
 
 
 
 
125
  The type `mbstate_t` is defined in `<cwchar>` and can represent any of
126
  the conversion states that can occur in an *implementation-defined* set
127
  of supported multibyte character encoding rules.
128
 
129
+ The two-argument member `assign` is defined identically to the built-in
130
+ operator `=`. The two-argument members `eq` and `lt` are defined
131
+ identically to the built-in operators `==` and `<` for type
132
  `unsigned char`.
133
 
134
+ The member `eof()` returns `EOF`.
135
 
136
+ #### `struct char_traits<char8_t>` <a id="char.traits.specializations.char8.t">[[char.traits.specializations.char8.t]]</a>
137
+
138
+ ``` cpp
139
+ namespace std {
140
+ template<> struct char_traits<char8_t> {
141
+ using char_type = char8_t;
142
+ using int_type = unsigned int;
143
+ using off_type = streamoff;
144
+ using pos_type = u8streampos;
145
+ using state_type = mbstate_t;
146
+ using comparison_category = strong_ordering;
147
+
148
+ static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
149
+ static constexpr bool eq(char_type c1, char_type c2) noexcept;
150
+ static constexpr bool lt(char_type c1, char_type c2) noexcept;
151
+
152
+ static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
153
+ static constexpr size_t length(const char_type* s);
154
+ static constexpr const char_type* find(const char_type* s, size_t n,
155
+ const char_type& a);
156
+ static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);
157
+ static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);
158
+ static constexpr char_type* assign(char_type* s, size_t n, char_type a);
159
+ static constexpr int_type not_eof(int_type c) noexcept;
160
+ static constexpr char_type to_char_type(int_type c) noexcept;
161
+ static constexpr int_type to_int_type(char_type c) noexcept;
162
+ static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
163
+ static constexpr int_type eof() noexcept;
164
+ };
165
+ }
166
+ ```
167
+
168
+ The two-argument members `assign`, `eq`, and `lt` are defined
169
+ identically to the built-in operators `=`, `==`, and `<` respectively.
170
+
171
+ The member `eof()` returns an implementation-defined constant that
172
+ cannot appear as a valid UTF-8 code unit.
173
+
174
+ #### `struct char_traits<char16_t>` <a id="char.traits.specializations.char16.t">[[char.traits.specializations.char16.t]]</a>
175
 
176
  ``` cpp
177
  namespace std {
178
  template<> struct char_traits<char16_t> {
179
  using char_type = char16_t;
180
  using int_type = uint_least16_t;
181
  using off_type = streamoff;
182
  using pos_type = u16streampos;
183
  using state_type = mbstate_t;
184
+ using comparison_category = strong_ordering;
185
 
186
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
187
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
188
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
189
 
190
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
191
  static constexpr size_t length(const char_type* s);
192
  static constexpr const char_type* find(const char_type* s, size_t n,
193
  const char_type& a);
194
+ static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);
195
+ static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);
196
+ static constexpr char_type* assign(char_type* s, size_t n, char_type a);
197
 
198
  static constexpr int_type not_eof(int_type c) noexcept;
199
  static constexpr char_type to_char_type(int_type c) noexcept;
200
  static constexpr int_type to_int_type(char_type c) noexcept;
201
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
202
  static constexpr int_type eof() noexcept;
203
  };
204
  }
205
  ```
206
 
207
+ The two-argument members `assign`, `eq`, and `lt` are defined
208
+ identically to the built-in operators `=`, `==`, and `<`, respectively.
 
209
 
210
+ The member `eof()` returns an *implementation-defined* constant that
211
+ cannot appear as a valid UTF-16 code unit.
212
 
213
+ #### `struct char_traits<char32_t>` <a id="char.traits.specializations.char32.t">[[char.traits.specializations.char32.t]]</a>
 
 
 
214
 
215
  ``` cpp
216
  namespace std {
217
  template<> struct char_traits<char32_t> {
218
  using char_type = char32_t;
219
  using int_type = uint_least32_t;
220
  using off_type = streamoff;
221
  using pos_type = u32streampos;
222
  using state_type = mbstate_t;
223
+ using comparison_category = strong_ordering;
224
 
225
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
226
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
227
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
228
 
229
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
230
  static constexpr size_t length(const char_type* s);
231
  static constexpr const char_type* find(const char_type* s, size_t n,
232
  const char_type& a);
233
+ static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);
234
+ static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);
235
+ static constexpr char_type* assign(char_type* s, size_t n, char_type a);
236
 
237
  static constexpr int_type not_eof(int_type c) noexcept;
238
  static constexpr char_type to_char_type(int_type c) noexcept;
239
  static constexpr int_type to_int_type(char_type c) noexcept;
240
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
241
  static constexpr int_type eof() noexcept;
242
  };
243
  }
244
  ```
245
 
246
+ The two-argument members `assign`, `eq`, and `lt` are defined
247
+ identically to the built-in operators `=`, `==`, and `<`, respectively.
 
248
 
249
+ The member `eof()` returns an *implementation-defined* constant that
250
+ cannot appear as a Unicode code point.
 
 
 
251
 
252
  #### `struct char_traits<wchar_t>` <a id="char.traits.specializations.wchar.t">[[char.traits.specializations.wchar.t]]</a>
253
 
254
  ``` cpp
255
  namespace std {
 
257
  using char_type = wchar_t;
258
  using int_type = wint_t;
259
  using off_type = streamoff;
260
  using pos_type = wstreampos;
261
  using state_type = mbstate_t;
262
+ using comparison_category = strong_ordering;
263
 
264
  static constexpr void assign(char_type& c1, const char_type& c2) noexcept;
265
  static constexpr bool eq(char_type c1, char_type c2) noexcept;
266
  static constexpr bool lt(char_type c1, char_type c2) noexcept;
267
 
268
  static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);
269
  static constexpr size_t length(const char_type* s);
270
  static constexpr const char_type* find(const char_type* s, size_t n,
271
  const char_type& a);
272
+ static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);
273
+ static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);
274
+ static constexpr char_type* assign(char_type* s, size_t n, char_type a);
275
 
276
  static constexpr int_type not_eof(int_type c) noexcept;
277
  static constexpr char_type to_char_type(int_type c) noexcept;
278
  static constexpr int_type to_int_type(char_type c) noexcept;
279
  static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;
280
  static constexpr int_type eof() noexcept;
281
  };
282
  }
283
  ```
284
 
285
+ The two-argument members `assign`, `eq`, and `lt` are defined
286
+ identically to the built-in operators `=`, `==`, and `<`, respectively.
287
 
288
+ The member `eof()` returns `WEOF`.
 
 
 
 
 
 
 
 
 
 
 
289
 
290
  ## String classes <a id="string.classes">[[string.classes]]</a>
291
 
292
  The header `<string>` defines the `basic_string` class template for
293
+ manipulating varying-length sequences of char-like objects and five
294
+ *typedef-name*s, `string`, `u8string`, `u16string`, `u32string`, and
295
+ `wstring`, that name the specializations `basic_string<char>`,
296
+ `basic_string<char8_t>`, `basic_string<char16_t>`,
297
  `basic_string<char32_t>`, and `basic_string<{}wchar_t>`, respectively.
298
 
299
  ### Header `<string>` synopsis <a id="string.syn">[[string.syn]]</a>
300
 
301
  ``` cpp
302
+ #include <compare> // see [compare.syn]
303
+ #include <initializer_list> // see [initializer.list.syn]
304
 
305
  namespace std {
306
  // [char.traits], character traits
307
  template<class charT> struct char_traits;
308
  template<> struct char_traits<char>;
309
+ template<> struct char_traits<char8_t>;
310
  template<> struct char_traits<char16_t>;
311
  template<> struct char_traits<char32_t>;
312
  template<> struct char_traits<wchar_t>;
313
 
314
  // [basic.string], basic_string
315
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
 
316
  class basic_string;
317
 
318
  template<class charT, class traits, class Allocator>
319
+ constexpr basic_string<charT, traits, Allocator>
320
  operator+(const basic_string<charT, traits, Allocator>& lhs,
321
  const basic_string<charT, traits, Allocator>& rhs);
322
  template<class charT, class traits, class Allocator>
323
+ constexpr basic_string<charT, traits, Allocator>
324
  operator+(basic_string<charT, traits, Allocator>&& lhs,
325
  const basic_string<charT, traits, Allocator>& rhs);
326
  template<class charT, class traits, class Allocator>
327
+ constexpr basic_string<charT, traits, Allocator>
328
  operator+(const basic_string<charT, traits, Allocator>& lhs,
329
  basic_string<charT, traits, Allocator>&& rhs);
330
  template<class charT, class traits, class Allocator>
331
+ constexpr basic_string<charT, traits, Allocator>
332
  operator+(basic_string<charT, traits, Allocator>&& lhs,
333
  basic_string<charT, traits, Allocator>&& rhs);
334
  template<class charT, class traits, class Allocator>
335
+ constexpr basic_string<charT, traits, Allocator>
336
  operator+(const charT* lhs,
337
  const basic_string<charT, traits, Allocator>& rhs);
338
  template<class charT, class traits, class Allocator>
339
+ constexpr basic_string<charT, traits, Allocator>
340
  operator+(const charT* lhs,
341
  basic_string<charT, traits, Allocator>&& rhs);
342
  template<class charT, class traits, class Allocator>
343
+ constexpr basic_string<charT, traits, Allocator>
344
+ operator+(charT lhs,
345
+ const basic_string<charT, traits, Allocator>& rhs);
346
  template<class charT, class traits, class Allocator>
347
+ constexpr basic_string<charT, traits, Allocator>
348
+ operator+(charT lhs,
349
+ basic_string<charT, traits, Allocator>&& rhs);
350
  template<class charT, class traits, class Allocator>
351
+ constexpr basic_string<charT, traits, Allocator>
352
  operator+(const basic_string<charT, traits, Allocator>& lhs,
353
  const charT* rhs);
354
  template<class charT, class traits, class Allocator>
355
+ constexpr basic_string<charT, traits, Allocator>
356
  operator+(basic_string<charT, traits, Allocator>&& lhs,
357
  const charT* rhs);
358
  template<class charT, class traits, class Allocator>
359
+ constexpr basic_string<charT, traits, Allocator>
360
+ operator+(const basic_string<charT, traits, Allocator>& lhs,
361
+ charT rhs);
362
  template<class charT, class traits, class Allocator>
363
+ constexpr basic_string<charT, traits, Allocator>
364
+ operator+(basic_string<charT, traits, Allocator>&& lhs,
365
+ charT rhs);
366
 
367
  template<class charT, class traits, class Allocator>
368
+ constexpr bool
369
+ operator==(const basic_string<charT, traits, Allocator>& lhs,
 
 
 
 
 
 
 
 
370
  const basic_string<charT, traits, Allocator>& rhs) noexcept;
371
  template<class charT, class traits, class Allocator>
372
+ constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,
 
 
 
373
  const charT* rhs);
374
 
375
  template<class charT, class traits, class Allocator>
376
+ constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,
377
+ \itcorr const basic_string<charT, traits, Allocator>& rhs) noexcept;
378
  template<class charT, class traits, class Allocator>
379
+ constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,
380
+ \itcorr const charT* rhs);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
381
 
382
  // [string.special], swap
383
  template<class charT, class traits, class Allocator>
384
+ constexpr void
385
+ swap(basic_string<charT, traits, Allocator>& lhs,
386
  basic_string<charT, traits, Allocator>& rhs)
387
  noexcept(noexcept(lhs.swap(rhs)));
388
 
389
  // [string.io], inserters and extractors
390
  template<class charT, class traits, class Allocator>
 
412
  template<class charT, class traits, class Allocator>
413
  basic_istream<charT, traits>&
414
  getline(basic_istream<charT, traits>&& is,
415
  basic_string<charT, traits, Allocator>& str);
416
 
417
+ // [string.erasure], erasure
418
+ template<class charT, class traits, class Allocator, class U>
419
+ constexpr typename basic_string<charT, traits, Allocator>::size_type
420
+ erase(basic_string<charT, traits, Allocator>& c, const U& value);
421
+ template<class charT, class traits, class Allocator, class Predicate>
422
+ constexpr typename basic_string<charT, traits, Allocator>::size_type
423
+ erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
424
+
425
  // basic_string typedef names
426
  using string = basic_string<char>;
427
+ using u8string = basic_string<char8_t>;
428
  using u16string = basic_string<char16_t>;
429
  using u32string = basic_string<char32_t>;
430
  using wstring = basic_string<wchar_t>;
431
 
432
  // [string.conversions], numeric conversions
433
+ int stoi(const string& str, size_t* idx = nullptr, int base = 10);
434
+ long stol(const string& str, size_t* idx = nullptr, int base = 10);
435
+ unsigned long stoul(const string& str, size_t* idx = nullptr, int base = 10);
436
+ long long stoll(const string& str, size_t* idx = nullptr, int base = 10);
437
+ unsigned long long stoull(const string& str, size_t* idx = nullptr, int base = 10);
438
+ float stof(const string& str, size_t* idx = nullptr);
439
+ double stod(const string& str, size_t* idx = nullptr);
440
+ long double stold(const string& str, size_t* idx = nullptr);
441
  string to_string(int val);
442
  string to_string(unsigned val);
443
  string to_string(long val);
444
  string to_string(unsigned long val);
445
  string to_string(long long val);
446
  string to_string(unsigned long long val);
447
  string to_string(float val);
448
  string to_string(double val);
449
  string to_string(long double val);
450
 
451
+ int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
452
+ long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
453
+ unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
454
+ long long stoll(const wstring& str, size_t* idx = nullptr, int base = 10);
455
+ unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base = 10);
456
+ float stof(const wstring& str, size_t* idx = nullptr);
457
+ double stod(const wstring& str, size_t* idx = nullptr);
458
+ long double stold(const wstring& str, size_t* idx = nullptr);
459
  wstring to_wstring(int val);
460
  wstring to_wstring(unsigned val);
461
  wstring to_wstring(long val);
462
  wstring to_wstring(unsigned long val);
463
  wstring to_wstring(long long val);
464
  wstring to_wstring(unsigned long long val);
465
  wstring to_wstring(float val);
466
  wstring to_wstring(double val);
467
  wstring to_wstring(long double val);
468
 
 
 
 
 
 
 
 
469
  namespace pmr {
470
  template<class charT, class traits = char_traits<charT>>
471
+ using basic_string = std::basic_string<charT, traits, polymorphic_allocator<charT>>;
 
472
 
473
  using string = basic_string<char>;
474
+ using u8string = basic_string<char8_t>;
475
  using u16string = basic_string<char16_t>;
476
  using u32string = basic_string<char32_t>;
477
  using wstring = basic_string<wchar_t>;
478
  }
479
 
480
+ // [basic.string.hash], hash support
481
+ template<class T> struct hash;
482
+ template<> struct hash<string>;
483
+ template<> struct hash<u8string>;
484
+ template<> struct hash<u16string>;
485
+ template<> struct hash<u32string>;
486
+ template<> struct hash<wstring>;
487
+ template<> struct hash<pmr::string>;
488
+ template<> struct hash<pmr::u8string>;
489
+ template<> struct hash<pmr::u16string>;
490
+ template<> struct hash<pmr::u32string>;
491
+ template<> struct hash<pmr::wstring>;
492
+
493
  inline namespace literals {
494
  inline namespace string_literals {
495
  // [basic.string.literals], suffix for basic_string literals
496
+ constexpr string operator""s(const char* str, size_t len);
497
+ constexpr u8string operator""s(const char8_t* str, size_t len);
498
+ constexpr u16string operator""s(const char16_t* str, size_t len);
499
+ constexpr u32string operator""s(const char32_t* str, size_t len);
500
+ constexpr wstring operator""s(const wchar_t* str, size_t len);
501
  }
502
  }
503
  }
504
  ```
505
 
 
511
  is also called a “string” if the type of the char-like objects that it
512
  holds is clear from context. In the rest of this Clause, the type of the
513
  char-like objects held in a `basic_string` object is designated by
514
  `charT`.
515
 
516
+ A specialization of `basic_string` is a contiguous container
517
+ [[container.requirements.general]].
 
518
 
519
+ In all cases, \[`data()`, `data() + size()`\] is a valid range,
520
+ `data() + size()` points at an object with value `charT()` (a “null
521
+ terminator”), and `size() <= capacity()` is `true`.
 
 
 
 
 
 
 
 
 
522
 
523
  ``` cpp
524
  namespace std {
525
  template<class charT, class traits = char_traits<charT>,
526
  class Allocator = allocator<charT>>
527
  class basic_string {
528
  public:
529
+ // types
530
  using traits_type = traits;
531
  using value_type = charT;
532
  using allocator_type = Allocator;
533
  using size_type = typename allocator_traits<Allocator>::size_type;
534
  using difference_type = typename allocator_traits<Allocator>::difference_type;
 
542
  using reverse_iterator = std::reverse_iterator<iterator>;
543
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
544
  static const size_type npos = -1;
545
 
546
  // [string.cons], construct/copy/destroy
547
+ constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
548
+ constexpr explicit basic_string(const Allocator& a) noexcept;
549
+ constexpr basic_string(const basic_string& str);
550
+ constexpr basic_string(basic_string&& str) noexcept;
551
+ constexpr basic_string(const basic_string& str, size_type pos,
552
  const Allocator& a = Allocator());
553
+ constexpr basic_string(const basic_string& str, size_type pos, size_type n,
554
  const Allocator& a = Allocator());
555
  template<class T>
556
+ constexpr basic_string(const T& t, size_type pos, size_type n,
557
  const Allocator& a = Allocator());
558
+ template<class T>
559
+ constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
560
+ constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
561
+ constexpr basic_string(const charT* s, const Allocator& a = Allocator());
562
+ constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
 
563
  template<class InputIterator>
564
+ constexpr basic_string(InputIterator begin, InputIterator end,
565
  const Allocator& a = Allocator());
566
+ constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());
567
+ constexpr basic_string(const basic_string&, const Allocator&);
568
+ constexpr basic_string(basic_string&&, const Allocator&);
569
+ constexpr ~basic_string();
570
 
571
+ constexpr basic_string& operator=(const basic_string& str);
572
+ constexpr basic_string& operator=(basic_string&& str)
 
573
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
574
  allocator_traits<Allocator>::is_always_equal::value);
575
+ template<class T>
576
+ constexpr basic_string& operator=(const T& t);
577
+ constexpr basic_string& operator=(const charT* s);
578
+ constexpr basic_string& operator=(charT c);
579
+ constexpr basic_string& operator=(initializer_list<charT>);
580
 
581
  // [string.iterators], iterators
582
+ constexpr iterator begin() noexcept;
583
+ constexpr const_iterator begin() const noexcept;
584
+ constexpr iterator end() noexcept;
585
+ constexpr const_iterator end() const noexcept;
586
 
587
+ constexpr reverse_iterator rbegin() noexcept;
588
+ constexpr const_reverse_iterator rbegin() const noexcept;
589
+ constexpr reverse_iterator rend() noexcept;
590
+ constexpr const_reverse_iterator rend() const noexcept;
591
 
592
+ constexpr const_iterator cbegin() const noexcept;
593
+ constexpr const_iterator cend() const noexcept;
594
+ constexpr const_reverse_iterator crbegin() const noexcept;
595
+ constexpr const_reverse_iterator crend() const noexcept;
596
 
597
  // [string.capacity], capacity
598
+ constexpr size_type size() const noexcept;
599
+ constexpr size_type length() const noexcept;
600
+ constexpr size_type max_size() const noexcept;
601
+ constexpr void resize(size_type n, charT c);
602
+ constexpr void resize(size_type n);
603
+ constexpr size_type capacity() const noexcept;
604
+ constexpr void reserve(size_type res_arg);
605
+ constexpr void shrink_to_fit();
606
+ constexpr void clear() noexcept;
607
+ [[nodiscard]] constexpr bool empty() const noexcept;
608
 
609
  // [string.access], element access
610
+ constexpr const_reference operator[](size_type pos) const;
611
+ constexpr reference operator[](size_type pos);
612
+ constexpr const_reference at(size_type n) const;
613
+ constexpr reference at(size_type n);
614
 
615
+ constexpr const charT& front() const;
616
+ constexpr charT& front();
617
+ constexpr const charT& back() const;
618
+ constexpr charT& back();
619
 
620
  // [string.modifiers], modifiers
621
+ constexpr basic_string& operator+=(const basic_string& str);
 
 
 
 
 
 
 
 
622
  template<class T>
623
+ constexpr basic_string& operator+=(const T& t);
624
+ constexpr basic_string& operator+=(const charT* s);
625
+ constexpr basic_string& operator+=(charT c);
626
+ constexpr basic_string& operator+=(initializer_list<charT>);
627
+ constexpr basic_string& append(const basic_string& str);
628
+ constexpr basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
629
+ template<class T>
630
+ constexpr basic_string& append(const T& t);
631
+ template<class T>
632
+ constexpr basic_string& append(const T& t, size_type pos, size_type n = npos);
633
+ constexpr basic_string& append(const charT* s, size_type n);
634
+ constexpr basic_string& append(const charT* s);
635
+ constexpr basic_string& append(size_type n, charT c);
636
  template<class InputIterator>
637
+ constexpr basic_string& append(InputIterator first, InputIterator last);
638
+ constexpr basic_string& append(initializer_list<charT>);
 
639
 
640
+ constexpr void push_back(charT c);
641
+
642
+ constexpr basic_string& assign(const basic_string& str);
643
+ constexpr basic_string& assign(basic_string&& str)
644
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
645
  allocator_traits<Allocator>::is_always_equal::value);
646
+ constexpr basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
 
 
647
  template<class T>
648
+ constexpr basic_string& assign(const T& t);
649
+ template<class T>
650
+ constexpr basic_string& assign(const T& t, size_type pos, size_type n = npos);
651
+ constexpr basic_string& assign(const charT* s, size_type n);
652
+ constexpr basic_string& assign(const charT* s);
653
+ constexpr basic_string& assign(size_type n, charT c);
654
  template<class InputIterator>
655
+ constexpr basic_string& assign(InputIterator first, InputIterator last);
656
+ constexpr basic_string& assign(initializer_list<charT>);
657
 
658
+ constexpr basic_string& insert(size_type pos, const basic_string& str);
659
+ constexpr basic_string& insert(size_type pos1, const basic_string& str,
660
  size_type pos2, size_type n = npos);
 
661
  template<class T>
662
+ constexpr basic_string& insert(size_type pos, const T& t);
663
+ template<class T>
664
+ constexpr basic_string& insert(size_type pos1, const T& t,
665
  size_type pos2, size_type n = npos);
666
+ constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
667
+ constexpr basic_string& insert(size_type pos, const charT* s);
668
+ constexpr basic_string& insert(size_type pos, size_type n, charT c);
669
+ constexpr iterator insert(const_iterator p, charT c);
670
+ constexpr iterator insert(const_iterator p, size_type n, charT c);
671
  template<class InputIterator>
672
+ constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
673
+ constexpr iterator insert(const_iterator p, initializer_list<charT>);
674
 
675
+ constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
676
+ constexpr iterator erase(const_iterator p);
677
+ constexpr iterator erase(const_iterator first, const_iterator last);
678
 
679
+ constexpr void pop_back();
680
 
681
+ constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
682
+ constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
 
 
683
  size_type pos2, size_type n2 = npos);
 
 
684
  template<class T>
685
+ constexpr basic_string& replace(size_type pos1, size_type n1, const T& t);
686
+ template<class T>
687
+ constexpr basic_string& replace(size_type pos1, size_type n1, const T& t,
688
  size_type pos2, size_type n2 = npos);
689
+ constexpr basic_string& replace(size_type pos, size_type n1, const charT* s, size_type n2);
690
+ constexpr basic_string& replace(size_type pos, size_type n1, const charT* s);
691
+ constexpr basic_string& replace(size_type pos, size_type n1, size_type n2, charT c);
692
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2,
 
 
 
693
  const basic_string& str);
694
+ template<class T>
695
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
696
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s,
697
  size_type n);
698
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
699
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
 
700
  template<class InputIterator>
701
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2,
702
  InputIterator j1, InputIterator j2);
703
+ constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
704
 
705
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
706
+
707
+ constexpr void swap(basic_string& str)
708
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
709
  allocator_traits<Allocator>::is_always_equal::value);
710
 
711
  // [string.ops], string operations
712
+ constexpr const charT* c_str() const noexcept;
713
+ constexpr const charT* data() const noexcept;
714
+ constexpr charT* data() noexcept;
715
+ constexpr operator basic_string_view<charT, traits>() const noexcept;
716
+ constexpr allocator_type get_allocator() const noexcept;
717
 
718
+ template<class T>
719
+ constexpr size_type find(const T& t, size_type pos = 0) const noexcept(see below);
720
+ constexpr size_type find(const basic_string& str, size_type pos = 0) const noexcept;
721
+ constexpr size_type find(const charT* s, size_type pos, size_type n) const;
722
+ constexpr size_type find(const charT* s, size_type pos = 0) const;
723
+ constexpr size_type find(charT c, size_type pos = 0) const noexcept;
724
+ template<class T>
725
+ constexpr size_type rfind(const T& t, size_type pos = npos) const noexcept(see below);
726
+ constexpr size_type rfind(const basic_string& str, size_type pos = npos) const noexcept;
727
+ constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
728
+ constexpr size_type rfind(const charT* s, size_type pos = npos) const;
729
+ constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
730
 
731
+ template<class T>
732
+ constexpr size_type find_first_of(const T& t, size_type pos = 0) const noexcept(see below);
733
+ constexpr size_type find_first_of(const basic_string& str, size_type pos = 0) const noexcept;
734
+ constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
735
+ constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
736
+ constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
737
+ template<class T>
738
+ constexpr size_type find_last_of(const T& t,
739
+ size_type pos = npos) const noexcept(see below);
740
+ constexpr size_type find_last_of(const basic_string& str,
 
741
  size_type pos = npos) const noexcept;
742
+ constexpr size_type find_last_of(const charT* s, size_type pos, size_type n) const;
743
+ constexpr size_type find_last_of(const charT* s, size_type pos = npos) const;
744
+ constexpr size_type find_last_of(charT c, size_type pos = npos) const noexcept;
 
745
 
746
+ template<class T>
747
+ constexpr size_type find_first_not_of(const T& t,
748
+ size_type pos = 0) const noexcept(see below);
749
+ constexpr size_type find_first_not_of(const basic_string& str,
750
  size_type pos = 0) const noexcept;
751
+ constexpr size_type find_first_not_of(const charT* s, size_type pos, size_type n) const;
752
+ constexpr size_type find_first_not_of(const charT* s, size_type pos = 0) const;
753
+ constexpr size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;
754
+ template<class T>
755
+ constexpr size_type find_last_not_of(const T& t,
756
+ size_type pos = npos) const noexcept(see below);
757
+ constexpr size_type find_last_not_of(const basic_string& str,
758
  size_type pos = npos) const noexcept;
759
+ constexpr size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
760
+ constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
761
+ constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
 
 
762
 
763
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
764
+
765
+ template<class T>
766
+ constexpr int compare(const T& t) const noexcept(see below);
767
  template<class T>
768
+ constexpr int compare(size_type pos1, size_type n1, const T& t) const;
769
+ template<class T>
770
+ constexpr int compare(size_type pos1, size_type n1, const T& t,
771
  size_type pos2, size_type n2 = npos) const;
772
+ constexpr int compare(const basic_string& str) const noexcept;
773
+ constexpr int compare(size_type pos1, size_type n1, const basic_string& str) const;
774
+ constexpr int compare(size_type pos1, size_type n1, const basic_string& str,
 
 
775
  size_type pos2, size_type n2 = npos) const;
776
+ constexpr int compare(const charT* s) const;
777
+ constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
778
+ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
779
+
780
+ constexpr bool starts_with(basic_string_view<charT, traits> x) const noexcept;
781
+ constexpr bool starts_with(charT x) const noexcept;
782
+ constexpr bool starts_with(const charT* x) const;
783
+ constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
784
+ constexpr bool ends_with(charT x) const noexcept;
785
+ constexpr bool ends_with(const charT* x) const;
786
  };
787
 
788
  template<class InputIterator,
789
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
790
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
791
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
792
  char_traits<typename iterator_traits<InputIterator>::value_type>,
793
  Allocator>;
794
+
795
+ template<class charT,
796
+ class traits,
797
+ class Allocator = allocator<charT>>
798
+ explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
799
+ -> basic_string<charT, traits, Allocator>;
800
+
801
+ template<class charT,
802
+ class traits,
803
+ class Allocator = allocator<charT>>
804
+ basic_string(basic_string_view<charT, traits>,
805
+ typename see below::size_type, typename see below::size_type,
806
+ const Allocator& = Allocator())
807
+ -> basic_string<charT, traits, Allocator>;
808
  }
809
  ```
810
 
811
+ A `size_type` parameter type in a `basic_string` deduction guide refers
812
+ to the `size_type` member type of the type deduced by the deduction
813
+ guide.
814
+
815
+ #### General requirements <a id="string.require">[[string.require]]</a>
816
 
817
  If any operation would cause `size()` to exceed `max_size()`, that
818
+ operation throws an exception object of type `length_error`.
819
 
820
  If any member function or operator of `basic_string` throws an
821
+ exception, that function or operator has no other effect on the
822
+ `basic_string` object.
823
 
824
  In every specialization `basic_string<charT, traits, Allocator>`, the
825
  type `allocator_traits<Allocator>::value_type` shall name the same type
826
  as `charT`. Every object of type
827
+ `basic_string<charT, traits, Allocator>` uses an object of type
828
  `Allocator` to allocate and free storage for the contained `charT`
829
+ objects as needed. The `Allocator` object used is obtained as described
830
+ in [[container.requirements.general]]. In every specialization
831
+ `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
832
+ the character traits requirements [[char.traits]].
833
+
834
+ [*Note 1*: The program is ill-formed if `traits::char_type` is not the
835
+ same type as `charT`. — *end note*]
836
 
837
  References, pointers, and iterators referring to the elements of a
838
  `basic_string` sequence may be invalidated by the following uses of that
839
  `basic_string` object:
840
 
841
+ - Passing as an argument to any standard library function taking a
842
+ reference to non-const `basic_string` as an argument.[^2]
843
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
844
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
845
 
846
+ #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
847
 
848
  ``` cpp
849
+ constexpr explicit basic_string(const Allocator& a) noexcept;
850
  ```
851
 
852
+ *Ensures:* `size()` is equal to `0`.
 
 
 
 
 
 
 
 
 
 
853
 
854
  ``` cpp
855
+ constexpr basic_string(const basic_string& str);
856
+ constexpr basic_string(basic_string&& str) noexcept;
857
  ```
858
 
859
+ *Effects:* Constructs an object whose value is that of `str` prior to
860
+ this call.
 
 
 
861
 
862
+ *Remarks:* In the second form, `str` is left in a valid but unspecified
863
+ state.
 
 
 
864
 
865
  ``` cpp
866
+ constexpr basic_string(const basic_string& str, size_type pos,
867
+ const Allocator& a = Allocator());
868
+ constexpr basic_string(const basic_string& str, size_type pos, size_type n,
869
  const Allocator& a = Allocator());
870
  ```
871
 
872
+ *Effects:* Let `n` be `npos` for the first overload. Equivalent to:
 
 
 
 
873
 
874
  ``` cpp
875
+ basic_string(basic_string_view<charT, traits>(str).substr(pos, n), a)
 
876
  ```
877
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
878
  ``` cpp
879
  template<class T>
880
+ constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
 
881
  ```
882
 
883
+ *Constraints:*
884
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
885
+ `true`.
886
+
887
  *Effects:* Creates a variable, `sv`, as if by
888
  `basic_string_view<charT, traits> sv = t;` and then behaves the same as:
889
 
890
  ``` cpp
891
  basic_string(sv.substr(pos, n), a);
892
  ```
893
 
 
 
 
 
894
  ``` cpp
895
+ template<class T>
896
+ constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
897
  ```
898
 
899
+ *Constraints:*
900
+
901
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
902
+ `true` and
903
+ - `is_convertible_v<const T&, const charT*>` is `false`.
904
+
905
+ *Effects:* Creates a variable, `sv`, as if by
906
+ `basic_string_view<charT, traits> sv = t;` and then behaves the same as
907
+ `basic_string(sv.data(), sv.size(), a)`.
908
 
909
  ``` cpp
910
+ constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
 
911
  ```
912
 
913
+ *Preconditions:* \[`s`, `s + n`) is a valid range.
914
 
915
+ *Effects:* Constructs an object whose initial value is the range \[`s`,
916
+ `s + n`).
 
 
917
 
918
+ *Ensures:* `size()` is equal to `n`, and `traits::compare(data(), s, n)`
919
+ is equal to `0`.
 
 
 
 
 
920
 
921
  ``` cpp
922
+ constexpr basic_string(const charT* s, const Allocator& a = Allocator());
923
  ```
924
 
925
+ *Constraints:* `Allocator` is a type that qualifies as an
926
+ allocator [[container.requirements.general]].
 
 
 
 
 
927
 
928
+ [*Note 1*: This affects class template argument
929
+ deduction. — *end note*]
930
 
931
+ *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
 
 
 
 
932
 
933
  ``` cpp
934
+ constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
935
  ```
936
 
937
+ *Constraints:* `Allocator` is a type that qualifies as an
938
+ allocator [[container.requirements.general]].
 
 
 
939
 
940
+ [*Note 2*: This affects class template argument
941
+ deduction. — *end note*]
942
 
943
+ *Effects:* Constructs an object whose value consists of `n` copies of
944
+ `c`.
 
 
 
945
 
946
  ``` cpp
947
  template<class InputIterator>
948
+ constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
 
949
  ```
950
 
951
+ *Constraints:* `InputIterator` is a type that qualifies as an input
952
+ iterator [[container.requirements.general]].
953
 
954
+ *Effects:* Constructs a string from the values in the range \[`begin`,
955
+ `end`), as indicated in [[container.seq.req]].
 
 
 
 
 
956
 
957
  ``` cpp
958
+ constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
959
  ```
960
 
961
+ *Effects:* Equivalent to `basic_string(il.begin(), il.end(), a)`.
962
 
963
  ``` cpp
964
+ constexpr basic_string(const basic_string& str, const Allocator& alloc);
965
+ constexpr basic_string(basic_string&& str, const Allocator& alloc);
966
  ```
967
 
968
+ *Effects:* Constructs an object whose value is that of `str` prior to
969
+ this call. The stored allocator is constructed from `alloc`. In the
970
+ second form, `str` is left in a valid but unspecified state.
 
 
 
 
 
 
 
 
 
 
 
 
971
 
972
  *Throws:* The second form throws nothing if
973
  `alloc == str.get_allocator()`.
974
 
975
  ``` cpp
 
979
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
980
  char_traits<typename iterator_traits<InputIterator>::value_type>,
981
  Allocator>;
982
  ```
983
 
984
+ *Constraints:* `InputIterator` is a type that qualifies as an input
985
+ iterator, and `Allocator` is a type that qualifies as an
986
+ allocator [[container.requirements.general]].
 
987
 
988
  ``` cpp
989
+ template<class charT,
990
+ class traits,
991
+ class Allocator = allocator<charT>>
992
+ explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
993
+ -> basic_string<charT, traits, Allocator>;
994
+
995
+ template<class charT,
996
+ class traits,
997
+ class Allocator = allocator<charT>>
998
+ basic_string(basic_string_view<charT, traits>,
999
+ typename see below::size_type, typename see below::size_type,
1000
+ const Allocator& = Allocator())
1001
+ -> basic_string<charT, traits, Allocator>;
1002
  ```
1003
 
1004
+ *Constraints:* `Allocator` is a type that qualifies as an
1005
+ allocator [[container.requirements.general]].
1006
+
1007
+ ``` cpp
1008
+ constexpr basic_string& operator=(const basic_string& str);
1009
+ ```
1010
 
1011
+ *Effects:* If `*this` and `str` are the same object, has no effect.
1012
+ Otherwise, replaces the value of `*this` with a copy of `str`.
1013
 
1014
  *Returns:* `*this`.
1015
 
 
 
 
 
 
 
 
 
1016
  ``` cpp
1017
+ constexpr basic_string& operator=(basic_string&& str)
1018
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1019
  allocator_traits<Allocator>::is_always_equal::value);
1020
  ```
1021
 
1022
  *Effects:* Move assigns as a sequence
1023
+ container [[container.requirements]], except that iterators, pointers
1024
  and references may be invalidated.
1025
 
1026
  *Returns:* `*this`.
1027
 
1028
  ``` cpp
1029
+ template<class T>
1030
+ constexpr basic_string& operator=(const T& t);
1031
  ```
1032
 
1033
+ *Constraints:*
1034
+
1035
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1036
+ `true` and
1037
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1038
+
1039
+ *Effects:* Equivalent to:
1040
 
1041
  ``` cpp
1042
+ basic_string_view<charT, traits> sv = t;
1043
+ return assign(sv);
1044
  ```
1045
 
1046
+ ``` cpp
1047
+ constexpr basic_string& operator=(const charT* s);
1048
+ ```
1049
 
1050
+ *Effects:* Equivalent to:
1051
+ `return *this = basic_string_view<charT, traits>(s);`
1052
 
1053
  ``` cpp
1054
+ constexpr basic_string& operator=(charT c);
1055
  ```
1056
 
1057
+ *Effects:* Equivalent to:
1058
 
1059
  ``` cpp
1060
+ return *this = basic_string_view<charT, traits>(addressof(c), 1);
1061
  ```
1062
 
1063
+ ``` cpp
1064
+ constexpr basic_string& operator=(initializer_list<charT> il);
1065
+ ```
1066
+
1067
+ *Effects:* Equivalent to:
1068
 
1069
+ ``` cpp
1070
+ return *this = basic_string_view<charT, traits>(il.begin(), il.size());
1071
+ ```
1072
 
1073
+ #### Iterator support <a id="string.iterators">[[string.iterators]]</a>
1074
 
1075
  ``` cpp
1076
+ constexpr iterator begin() noexcept;
1077
+ constexpr const_iterator begin() const noexcept;
1078
+ constexpr const_iterator cbegin() const noexcept;
1079
  ```
1080
 
1081
  *Returns:* An iterator referring to the first character in the string.
1082
 
1083
  ``` cpp
1084
+ constexpr iterator end() noexcept;
1085
+ constexpr const_iterator end() const noexcept;
1086
+ constexpr const_iterator cend() const noexcept;
1087
  ```
1088
 
1089
  *Returns:* An iterator which is the past-the-end value.
1090
 
1091
  ``` cpp
1092
+ constexpr reverse_iterator rbegin() noexcept;
1093
+ constexpr const_reverse_iterator rbegin() const noexcept;
1094
+ constexpr const_reverse_iterator crbegin() const noexcept;
1095
  ```
1096
 
1097
  *Returns:* An iterator which is semantically equivalent to
1098
  `reverse_iterator(end())`.
1099
 
1100
  ``` cpp
1101
+ constexpr reverse_iterator rend() noexcept;
1102
+ constexpr const_reverse_iterator rend() const noexcept;
1103
+ constexpr const_reverse_iterator crend() const noexcept;
1104
  ```
1105
 
1106
  *Returns:* An iterator which is semantically equivalent to
1107
  `reverse_iterator(begin())`.
1108
 
1109
+ #### Capacity <a id="string.capacity">[[string.capacity]]</a>
1110
 
1111
  ``` cpp
1112
+ constexpr size_type size() const noexcept;
1113
+ constexpr size_type length() const noexcept;
1114
  ```
1115
 
1116
  *Returns:* A count of the number of char-like objects currently in the
1117
  string.
1118
 
1119
  *Complexity:* Constant time.
1120
 
1121
  ``` cpp
1122
+ constexpr size_type max_size() const noexcept;
 
 
 
 
 
 
1123
  ```
1124
 
1125
  *Returns:* The largest possible number of char-like objects that can be
1126
  stored in a `basic_string`.
1127
 
1128
  *Complexity:* Constant time.
1129
 
1130
  ``` cpp
1131
+ constexpr void resize(size_type n, charT c);
1132
  ```
1133
 
1134
+ *Effects:* Alters the value of `*this` as follows:
1135
 
1136
+ - If `n <= size()`, erases the last `size() - n` elements.
1137
+ - If `n > size()`, appends `n - size()` copies of `c`.
 
 
 
 
 
 
 
 
1138
 
1139
  ``` cpp
1140
+ constexpr void resize(size_type n);
1141
  ```
1142
 
1143
+ *Effects:* Equivalent to `resize(n, charT())`.
1144
 
1145
  ``` cpp
1146
+ constexpr size_type capacity() const noexcept;
1147
  ```
1148
 
1149
  *Returns:* The size of the allocated storage in the string.
1150
 
1151
+ *Complexity:* Constant time.
1152
+
1153
  ``` cpp
1154
+ constexpr void reserve(size_type res_arg);
1155
  ```
1156
 
1157
+ *Effects:* A directive that informs a `basic_string` of a planned change
1158
+ in size, so that the storage allocation can be managed accordingly.
1159
+ After `reserve()`, `capacity()` is greater or equal to the argument of
1160
+ `reserve` if reallocation happens; and equal to the previous value of
1161
+ `capacity()` otherwise. Reallocation happens at this point if and only
1162
+ if the current capacity is less than the argument of `reserve()`.
1163
 
1164
+ *Throws:* `length_error` if `res_arg > max_size()` or any exceptions
1165
+ thrown by `allocator_traits` `<Allocator>::allocate`.
 
 
 
 
 
 
 
1166
 
1167
  ``` cpp
1168
+ constexpr void shrink_to_fit();
1169
  ```
1170
 
1171
  *Effects:* `shrink_to_fit` is a non-binding request to reduce
1172
  `capacity()` to `size()`.
1173
 
1174
+ [*Note 1*: The request is non-binding to allow latitude for
1175
  implementation-specific optimizations. — *end note*]
1176
 
1177
  It does not increase `capacity()`, but may reduce `capacity()` by
1178
  causing reallocation.
1179
 
1180
+ *Complexity:* If the size is not equal to the old capacity, linear in
1181
+ the size of the sequence; otherwise constant.
1182
 
1183
  *Remarks:* Reallocation invalidates all the references, pointers, and
1184
+ iterators referring to the elements in the sequence, as well as the
1185
+ past-the-end iterator.
1186
 
1187
+ [*Note 2*: If no reallocation happens, they remain
1188
+ valid. *end note*]
 
 
 
1189
 
1190
  ``` cpp
1191
+ constexpr void clear() noexcept;
1192
  ```
1193
 
1194
+ *Effects:* Equivalent to: `erase(begin(), end());`
1195
+
1196
  ``` cpp
1197
+ [[nodiscard]] constexpr bool empty() const noexcept;
1198
  ```
1199
 
1200
+ *Effects:* Equivalent to: `return size() == 0;`
1201
 
1202
+ #### Element access <a id="string.access">[[string.access]]</a>
1203
 
1204
  ``` cpp
1205
+ constexpr const_reference operator[](size_type pos) const;
1206
+ constexpr reference operator[](size_type pos);
1207
  ```
1208
 
1209
+ *Preconditions:* `pos <= size()`.
1210
 
1211
  *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
1212
  reference to an object of type `charT` with value `charT()`, where
1213
  modifying the object to any value other than `charT()` leads to
1214
  undefined behavior.
 
1216
  *Throws:* Nothing.
1217
 
1218
  *Complexity:* Constant time.
1219
 
1220
  ``` cpp
1221
+ constexpr const_reference at(size_type pos) const;
1222
+ constexpr reference at(size_type pos);
1223
  ```
1224
 
1225
  *Throws:* `out_of_range` if `pos >= size()`.
1226
 
1227
  *Returns:* `operator[](pos)`.
1228
 
1229
  ``` cpp
1230
+ constexpr const charT& front() const;
1231
+ constexpr charT& front();
1232
  ```
1233
 
1234
+ *Preconditions:* `!empty()`.
1235
 
1236
  *Effects:* Equivalent to: `return operator[](0);`
1237
 
1238
  ``` cpp
1239
+ constexpr const charT& back() const;
1240
+ constexpr charT& back();
1241
  ```
1242
 
1243
+ *Preconditions:* `!empty()`.
1244
 
1245
  *Effects:* Equivalent to: `return operator[](size() - 1);`
1246
 
1247
+ #### Modifiers <a id="string.modifiers">[[string.modifiers]]</a>
1248
 
1249
+ ##### `basic_string::operator+=` <a id="string.op.append">[[string.op.append]]</a>
1250
 
1251
  ``` cpp
1252
+ constexpr basic_string& operator+=(const basic_string& str);
 
1253
  ```
1254
 
1255
+ *Effects:* Equivalent to: `return append(str);`
 
 
1256
 
1257
  ``` cpp
1258
+ template<class T>
1259
+ constexpr basic_string& operator+=(const T& t);
1260
  ```
1261
 
1262
+ *Constraints:*
1263
+
1264
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1265
+ `true` and
1266
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1267
 
1268
+ *Effects:* Equivalent to:
1269
 
1270
  ``` cpp
1271
+ basic_string_view<charT, traits> sv = t;
1272
+ return append(sv);
1273
  ```
1274
 
1275
+ ``` cpp
1276
+ constexpr basic_string& operator+=(const charT* s);
1277
+ ```
1278
 
1279
+ *Effects:* Equivalent to: `return append(s);`
1280
 
1281
  ``` cpp
1282
+ constexpr basic_string& operator+=(charT c);
1283
  ```
1284
 
1285
+ *Effects:* Equivalent to: `return append(size_type{1}, c);`
 
 
1286
 
1287
  ``` cpp
1288
+ constexpr basic_string& operator+=(initializer_list<charT> il);
1289
  ```
1290
 
1291
+ *Effects:* Equivalent to: `return append(il);`
 
 
1292
 
1293
  ##### `basic_string::append` <a id="string.append">[[string.append]]</a>
1294
 
1295
  ``` cpp
1296
+ constexpr basic_string& append(const basic_string& str);
 
1297
  ```
1298
 
1299
+ *Effects:* Equivalent to: `return append(str.data(), str.size());`
 
 
1300
 
1301
  ``` cpp
1302
+ constexpr basic_string& append(const basic_string& str, size_type pos, size_type n = npos);
 
1303
  ```
1304
 
1305
+ *Effects:* Equivalent to:
 
 
 
 
 
 
1306
 
1307
  ``` cpp
1308
+ return append(basic_string_view<charT, traits>(str).substr(pos, n));
1309
  ```
1310
 
 
 
1311
  ``` cpp
1312
  template<class T>
1313
+ constexpr basic_string& append(const T& t);
1314
  ```
1315
 
1316
+ *Constraints:*
1317
 
1318
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1319
+ `true` and
1320
+ - `is_convertible_v<const T&, const charT*>` is `false`.
 
1321
 
1322
+ *Effects:* Equivalent to:
 
 
1323
 
1324
+ ``` cpp
1325
+ basic_string_view<charT, traits> sv = t;
1326
+ return append(sv.data(), sv.size());
1327
+ ```
1328
 
1329
  ``` cpp
1330
+ template<class T>
1331
+ constexpr basic_string& append(const T& t, size_type pos, size_type n = npos);
1332
  ```
1333
 
1334
+ *Constraints:*
1335
 
1336
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1337
+ `true` and
1338
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1339
 
1340
+ *Effects:* Equivalent to:
 
 
 
1341
 
1342
+ ``` cpp
1343
+ basic_string_view<charT, traits> sv = t;
1344
+ return append(sv.substr(pos, n));
1345
+ ```
1346
 
1347
  ``` cpp
1348
+ constexpr basic_string& append(const charT* s, size_type n);
1349
  ```
1350
 
1351
+ *Preconditions:* \[`s`, `s + n`) is a valid range.
 
1352
 
1353
+ *Effects:* Appends a copy of the range \[`s`, `s + n`) to the string.
1354
 
1355
  *Returns:* `*this`.
1356
 
1357
  ``` cpp
1358
+ constexpr basic_string& append(const charT* s);
1359
+ ```
1360
+
1361
+ *Effects:* Equivalent to: `return append(s, traits::length(s));`
1362
+
1363
+ ``` cpp
1364
+ constexpr basic_string& append(size_type n, charT c);
1365
  ```
1366
 
1367
+ *Effects:* Appends `n` copies of `c` to the string.
1368
 
1369
  *Returns:* `*this`.
1370
 
1371
  ``` cpp
1372
  template<class InputIterator>
1373
+ constexpr basic_string& append(InputIterator first, InputIterator last);
1374
  ```
1375
 
1376
+ *Constraints:* `InputIterator` is a type that qualifies as an input
1377
+ iterator [[container.requirements.general]].
1378
 
1379
+ *Effects:* Equivalent to:
1380
+ `return append(basic_string(first, last, get_allocator()));`
 
 
1381
 
1382
  ``` cpp
1383
+ constexpr basic_string& append(initializer_list<charT> il);
1384
  ```
1385
 
1386
+ *Effects:* Equivalent to: `return append(il.begin(), il.size());`
 
 
1387
 
1388
  ``` cpp
1389
+ constexpr void push_back(charT c);
1390
  ```
1391
 
1392
+ *Effects:* Equivalent to `append(size_type{1}, c)`.
1393
 
1394
  ##### `basic_string::assign` <a id="string.assign">[[string.assign]]</a>
1395
 
1396
  ``` cpp
1397
+ constexpr basic_string& assign(const basic_string& str);
1398
  ```
1399
 
1400
+ *Effects:* Equivalent to: `return *this = str;`
 
 
1401
 
1402
  ``` cpp
1403
+ constexpr basic_string& assign(basic_string&& str)
1404
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
1405
  allocator_traits<Allocator>::is_always_equal::value);
1406
  ```
1407
 
1408
+ *Effects:* Equivalent to: `return *this = std::move(str);`
 
 
1409
 
1410
  ``` cpp
1411
+ constexpr basic_string& assign(const basic_string& str, size_type pos, size_type n = npos);
 
 
1412
  ```
1413
 
1414
+ *Effects:* Equivalent to:
 
 
 
 
 
 
1415
 
1416
  ``` cpp
1417
+ return assign(basic_string_view<charT, traits>(str).substr(pos, n));
1418
  ```
1419
 
 
 
1420
  ``` cpp
1421
  template<class T>
1422
+ constexpr basic_string& assign(const T& t);
1423
  ```
1424
 
1425
+ *Constraints:*
1426
 
1427
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1428
+ `true` and
1429
+ - `is_convertible_v<const T&, const charT*>` is `false`.
 
1430
 
1431
+ *Effects:* Equivalent to:
 
 
1432
 
1433
+ ``` cpp
1434
+ basic_string_view<charT, traits> sv = t;
1435
+ return assign(sv.data(), sv.size());
1436
+ ```
1437
 
1438
  ``` cpp
1439
+ template<class T>
1440
+ constexpr basic_string& assign(const T& t, size_type pos, size_type n = npos);
1441
  ```
1442
 
1443
+ *Constraints:*
1444
 
1445
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1446
+ `true` and
1447
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1448
 
1449
+ *Effects:* Equivalent to:
 
1450
 
1451
+ ``` cpp
1452
+ basic_string_view<charT, traits> sv = t;
1453
+ return assign(sv.substr(pos, n));
1454
+ ```
1455
 
1456
  ``` cpp
1457
+ constexpr basic_string& assign(const charT* s, size_type n);
1458
  ```
1459
 
1460
+ *Preconditions:* \[`s`, `s + n`) is a valid range.
 
1461
 
1462
+ *Effects:* Replaces the string controlled by `*this` with a copy of the
1463
+ range \[`s`, `s + n`).
1464
 
1465
  *Returns:* `*this`.
1466
 
1467
  ``` cpp
1468
+ constexpr basic_string& assign(const charT* s);
1469
  ```
1470
 
1471
+ *Effects:* Equivalent to: `return assign(s, traits::length(s));`
1472
 
1473
+ ``` cpp
1474
+ constexpr basic_string& assign(initializer_list<charT> il);
1475
+ ```
1476
+
1477
+ *Effects:* Equivalent to: `return assign(il.begin(), il.size());`
1478
 
1479
  ``` cpp
1480
+ constexpr basic_string& assign(size_type n, charT c);
1481
  ```
1482
 
1483
+ *Effects:* Equivalent to:
1484
 
1485
+ ``` cpp
1486
+ clear();
1487
+ resize(n, c);
1488
+ return *this;
1489
+ ```
1490
 
1491
  ``` cpp
1492
  template<class InputIterator>
1493
+ constexpr basic_string& assign(InputIterator first, InputIterator last);
1494
  ```
1495
 
1496
+ *Constraints:* `InputIterator` is a type that qualifies as an input
1497
+ iterator [[container.requirements.general]].
1498
 
1499
+ *Effects:* Equivalent to:
1500
+ `return assign(basic_string(first, last, get_allocator()));`
1501
 
1502
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1503
 
1504
  ``` cpp
1505
+ constexpr basic_string& insert(size_type pos, const basic_string& str);
 
 
1506
  ```
1507
 
1508
  *Effects:* Equivalent to: `return insert(pos, str.data(), str.size());`
1509
 
1510
  ``` cpp
1511
+ constexpr basic_string& insert(size_type pos1, const basic_string& str,
 
 
1512
  size_type pos2, size_type n = npos);
1513
  ```
1514
 
1515
+ *Effects:* Equivalent to:
1516
 
1517
+ ``` cpp
1518
+ return insert(pos1, basic_string_view<charT, traits>(str), pos2, n);
1519
+ ```
 
 
1520
 
1521
  ``` cpp
1522
+ template<class T>
1523
+ constexpr basic_string& insert(size_type pos, const T& t);
1524
  ```
1525
 
1526
+ *Constraints:*
1527
+
1528
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1529
+ `true` and
1530
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1531
+
1532
+ *Effects:* Equivalent to:
1533
+
1534
+ ``` cpp
1535
+ basic_string_view<charT, traits> sv = t;
1536
+ return insert(pos, sv.data(), sv.size());
1537
+ ```
1538
 
1539
  ``` cpp
1540
  template<class T>
1541
+ constexpr basic_string& insert(size_type pos1, const T& t,
1542
  size_type pos2, size_type n = npos);
1543
  ```
1544
 
1545
+ *Constraints:*
1546
 
1547
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1548
+ `true` and
1549
+ - `is_convertible_v<const T&, const charT*>` is `false`.
 
1550
 
1551
+ *Effects:* Equivalent to:
 
 
1552
 
1553
+ ``` cpp
1554
+ basic_string_view<charT, traits> sv = t;
1555
+ return insert(pos1, sv.substr(pos2, n));
1556
+ ```
1557
 
1558
  ``` cpp
1559
+ constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
 
1560
  ```
1561
 
1562
+ *Preconditions:* \[`s`, `s + n`) is a valid range.
1563
+
1564
+ *Throws:*
1565
 
1566
+ - `out_of_range` if `pos > size()`,
1567
+ - `length_error` if `n > max_size() - size()`, or
1568
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1569
 
1570
+ *Effects:* Inserts a copy of the range \[`s`, `s + n`) immediately
1571
+ before the character at position `pos` if `pos < size()`, or otherwise
1572
+ at the end of the string.
 
 
 
1573
 
1574
  *Returns:* `*this`.
1575
 
1576
  ``` cpp
1577
+ constexpr basic_string& insert(size_type pos, const charT* s);
 
1578
  ```
1579
 
 
 
 
1580
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
1581
 
1582
  ``` cpp
1583
+ constexpr basic_string& insert(size_type pos, size_type n, charT c);
 
1584
  ```
1585
 
1586
+ *Effects:* Inserts `n` copies of `c` before the character at position
1587
+ `pos` if `pos < size()`, or otherwise at the end of the string.
1588
 
1589
+ *Returns:* `*this`
1590
+
1591
+ *Throws:*
1592
+
1593
+ - `out_of_range` if `pos > size()`,
1594
+ - `length_error` if `n > max_size() - size()`, or
1595
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1596
 
1597
  ``` cpp
1598
+ constexpr iterator insert(const_iterator p, charT c);
1599
  ```
1600
 
1601
+ *Preconditions:* `p` is a valid iterator on `*this`.
1602
 
1603
+ *Effects:* Inserts a copy of `c` at the position `p`.
 
1604
 
1605
+ *Returns:* An iterator which refers to the inserted character.
 
1606
 
1607
  ``` cpp
1608
+ constexpr iterator insert(const_iterator p, size_type n, charT c);
1609
  ```
1610
 
1611
+ *Preconditions:* `p` is a valid iterator on `*this`.
1612
 
1613
+ *Effects:* Inserts `n` copies of `c` at the position `p`.
 
1614
 
1615
+ *Returns:* An iterator which refers to the first inserted character, or
1616
+ `p` if `n == 0`.
1617
 
1618
  ``` cpp
1619
  template<class InputIterator>
1620
+ constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
1621
  ```
1622
 
1623
+ *Constraints:* `InputIterator` is a type that qualifies as an input
1624
+ iterator [[container.requirements.general]].
1625
+
1626
+ *Preconditions:* `p` is a valid iterator on `*this`.
1627
 
1628
  *Effects:* Equivalent to
1629
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1630
 
1631
+ *Returns:* An iterator which refers to the first inserted character, or
1632
+ `p` if `first == last`.
1633
 
1634
  ``` cpp
1635
+ constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1636
  ```
1637
 
1638
+ *Effects:* Equivalent to: `return insert(p, il.begin(), il.end());`
 
 
 
1639
 
1640
  ##### `basic_string::erase` <a id="string.erase">[[string.erase]]</a>
1641
 
1642
  ``` cpp
1643
+ constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1644
  ```
1645
 
1646
  *Throws:* `out_of_range` if `pos` `> size()`.
1647
 
1648
  *Effects:* Determines the effective length `xlen` of the string to be
1649
+ removed as the smaller of `n` and `size() - pos`. Removes the characters
1650
+ in the range \[`begin() + pos`, `begin() + pos + xlen`).
 
 
 
 
 
1651
 
1652
  *Returns:* `*this`.
1653
 
1654
  ``` cpp
1655
+ constexpr iterator erase(const_iterator p);
1656
  ```
1657
 
1658
+ *Preconditions:* `p` is a valid dereferenceable iterator on `*this`.
1659
+
1660
  *Throws:* Nothing.
1661
 
1662
  *Effects:* Removes the character referred to by `p`.
1663
 
1664
  *Returns:* An iterator which points to the element immediately following
1665
  `p` prior to the element being erased. If no such element exists,
1666
  `end()` is returned.
1667
 
1668
  ``` cpp
1669
+ constexpr iterator erase(const_iterator first, const_iterator last);
1670
  ```
1671
 
1672
+ *Preconditions:* `first` and `last` are valid iterators on `*this`.
1673
+ \[`first`, `last`) is a valid range.
1674
 
1675
  *Throws:* Nothing.
1676
 
1677
  *Effects:* Removes the characters in the range `[first, last)`.
1678
 
1679
  *Returns:* An iterator which points to the element pointed to by `last`
1680
  prior to the other elements being erased. If no such element exists,
1681
  `end()` is returned.
1682
 
1683
  ``` cpp
1684
+ constexpr void pop_back();
1685
  ```
1686
 
1687
+ *Preconditions:* `!empty()`.
1688
 
1689
  *Throws:* Nothing.
1690
 
1691
+ *Effects:* Equivalent to `erase(end() - 1)`.
1692
 
1693
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1694
 
1695
  ``` cpp
1696
+ constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
 
 
1697
  ```
1698
 
1699
  *Effects:* Equivalent to:
1700
  `return replace(pos1, n1, str.data(), str.size());`
1701
 
1702
  ``` cpp
1703
+ constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str,
 
 
1704
  size_type pos2, size_type n2 = npos);
1705
  ```
1706
 
1707
+ *Effects:* Equivalent to:
 
 
 
 
1708
 
1709
+ ``` cpp
1710
+ return replace(pos1, n1, basic_string_view<charT, traits>(str).substr(pos2, n2));
1711
+ ```
1712
 
1713
  ``` cpp
1714
+ template<class T>
1715
+ constexpr basic_string& replace(size_type pos1, size_type n1, const T& t);
1716
  ```
1717
 
1718
+ *Constraints:*
1719
+
1720
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1721
+ `true` and
1722
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1723
+
1724
  *Effects:* Equivalent to:
1725
+
1726
+ ``` cpp
1727
+ basic_string_view<charT, traits> sv = t;
1728
+ return replace(pos1, n1, sv.data(), sv.size());
1729
+ ```
1730
 
1731
  ``` cpp
1732
  template<class T>
1733
+ constexpr basic_string& replace(size_type pos1, size_type n1, const T& t,
1734
  size_type pos2, size_type n2 = npos);
1735
  ```
1736
 
1737
+ *Constraints:*
1738
 
1739
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1740
+ `true` and
1741
+ - `is_convertible_v<const T&, const charT*>` is `false`.
 
 
1742
 
1743
+ *Effects:* Equivalent to:
 
 
1744
 
1745
+ ``` cpp
1746
+ basic_string_view<charT, traits> sv = t;
1747
+ return replace(pos1, n1, sv.substr(pos2, n2));
1748
+ ```
1749
 
1750
  ``` cpp
1751
+ constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
 
1752
  ```
1753
 
1754
+ *Preconditions:* \[`s`, `s + n2`) is a valid range.
1755
+
1756
+ *Throws:*
1757
 
1758
+ - `out_of_range` if `pos1 > size()`,
1759
+ - `length_error` if the length of the resulting string would exceed
1760
+ `max_size()` (see below), or
1761
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1762
 
1763
  *Effects:* Determines the effective length `xlen` of the string to be
1764
  removed as the smaller of `n1` and `size() - pos1`. If
1765
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1766
+ function replaces the characters in the range \[`begin() + pos1`,
1767
+ `begin() + pos1 + xlen`) with a copy of the range \[`s`, `s + n2`).
 
 
 
 
1768
 
1769
  *Returns:* `*this`.
1770
 
1771
  ``` cpp
1772
+ constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
 
1773
  ```
1774
 
 
 
 
1775
  *Effects:* Equivalent to:
1776
  `return replace(pos, n, s, traits::length(s));`
1777
 
1778
  ``` cpp
1779
+ constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
 
 
1780
  ```
1781
 
1782
+ *Throws:*
1783
+
1784
+ - `out_of_range` if `pos1 > size()`,
1785
+ - `length_error` if the length of the resulting string would exceed
1786
+ `max_size()` (see below), or
1787
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
1788
+
1789
+ *Effects:* Determines the effective length `xlen` of the string to be
1790
+ removed as the smaller of `n1` and `size() - pos1`. If
1791
+ `size() - xlen >=` `max_size() - n2` throws `length_error`. Otherwise,
1792
+ the function replaces the characters in the range \[`begin() + pos1`,
1793
+ `begin() + pos1 + xlen`) with `n2` copies of `c`.
1794
 
1795
  *Returns:* `*this`.
1796
 
1797
  ``` cpp
1798
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1799
  ```
1800
 
1801
+ *Effects:* Equivalent to:
1802
+ `return replace(i1, i2, basic_string_view<charT, traits>(str));`
 
 
 
1803
 
1804
  ``` cpp
1805
+ template<class T>
1806
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const T& t);
1807
  ```
1808
 
1809
+ *Constraints:*
1810
 
1811
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1812
+ `true` and
1813
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1814
 
1815
+ *Preconditions:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1816
+
1817
+ *Effects:* Equivalent to:
1818
 
1819
  ``` cpp
1820
+ basic_string_view<charT, traits> sv = t;
1821
+ return replace(i1 - begin(), i2 - i1, sv.data(), sv.size());
1822
  ```
1823
 
 
 
 
 
 
 
 
1824
  ``` cpp
1825
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s, size_type n);
1826
  ```
1827
 
1828
+ *Effects:* Equivalent to:
1829
+ `return replace(i1, i2, basic_string_view<charT, traits>(s, n));`
 
1830
 
1831
+ ``` cpp
1832
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
1833
+ ```
1834
 
1835
+ *Effects:* Equivalent to:
1836
+ `return replace(i1, i2, basic_string_view<charT, traits>(s));`
1837
 
1838
  ``` cpp
1839
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
 
1840
  ```
1841
 
1842
+ *Preconditions:* \[`begin()`, `i1`) and \[`i1`, `i2`) are valid ranges.
1843
 
1844
+ *Effects:* Equivalent to: `return replace(i1 - begin(), i2 - i1, n, c);`
 
 
1845
 
1846
  ``` cpp
1847
  template<class InputIterator>
1848
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2,
1849
  InputIterator j1, InputIterator j2);
1850
  ```
1851
 
1852
+ *Constraints:* `InputIterator` is a type that qualifies as an input
1853
+ iterator [[container.requirements.general]].
1854
 
1855
+ *Effects:* Equivalent to:
1856
+ `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
 
 
1857
 
1858
  ``` cpp
1859
+ constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
 
1860
  ```
1861
 
1862
+ *Effects:* Equivalent to:
1863
+ `return replace(i1, i2, il.begin(), il.size());`
 
 
 
 
1864
 
1865
  ##### `basic_string::copy` <a id="string.copy">[[string.copy]]</a>
1866
 
1867
  ``` cpp
1868
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
1869
  ```
1870
 
1871
+ *Effects:* Equivalent to:
1872
+ `return basic_string_view<charT, traits>(*this).copy(s, n, pos);`
 
 
 
 
 
1873
 
1874
  [*Note 1*: This does not terminate `s` with a null
1875
  object. — *end note*]
1876
 
 
 
1877
  ##### `basic_string::swap` <a id="string.swap">[[string.swap]]</a>
1878
 
1879
  ``` cpp
1880
+ constexpr void swap(basic_string& s)
1881
  noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value ||
1882
  allocator_traits<Allocator>::is_always_equal::value);
1883
  ```
1884
 
1885
+ *Preconditions:*
1886
+ `allocator_traits<Allocator>::propagate_on_container_swap::value` is
1887
+ `true` or `get_allocator() == s.get_allocator()`.
1888
+
1889
+ *Ensures:* `*this` contains the same sequence of characters that was in
1890
+ `s`, `s` contains the same sequence of characters that was in `*this`.
1891
 
1892
  *Throws:* Nothing.
1893
 
1894
  *Complexity:* Constant time.
1895
 
1896
+ #### String operations <a id="string.ops">[[string.ops]]</a>
1897
 
1898
+ ##### Accessors <a id="string.accessors">[[string.accessors]]</a>
1899
 
1900
  ``` cpp
1901
+ constexpr const charT* c_str() const noexcept;
1902
+ constexpr const charT* data() const noexcept;
1903
  ```
1904
 
1905
+ *Returns:* A pointer `p` such that `p + i == addressof(operator[](i))`
1906
+ for each `i` in \[`0`, `size()`\].
1907
 
1908
  *Complexity:* Constant time.
1909
 
1910
+ *Remarks:* The program shall not modify any of the values stored in the
1911
+ character array; otherwise, the behavior is undefined.
1912
 
1913
  ``` cpp
1914
+ constexpr charT* data() noexcept;
1915
  ```
1916
 
1917
+ *Returns:* A pointer `p` such that `p + i == addressof(operator[](i))`
1918
+ for each `i` in \[`0`, `size()`\].
1919
 
1920
  *Complexity:* Constant time.
1921
 
1922
+ *Remarks:* The program shall not modify the value stored at `p + size()`
1923
+ to any value other than `charT()`; otherwise, the behavior is undefined.
1924
 
1925
  ``` cpp
1926
+ constexpr operator basic_string_view<charT, traits>() const noexcept;
1927
  ```
1928
 
1929
  *Effects:* Equivalent to:
1930
  `return basic_string_view<charT, traits>(data(), size());`
1931
 
1932
  ``` cpp
1933
+ constexpr allocator_type get_allocator() const noexcept;
1934
  ```
1935
 
1936
  *Returns:* A copy of the `Allocator` object used to construct the string
1937
  or, if that allocator has been replaced, a copy of the most recent
1938
  replacement.
1939
 
1940
+ ##### Searching <a id="string.find">[[string.find]]</a>
1941
 
1942
+ Let *F* be one of `find`, `rfind`, `find_first_of`, `find_last_of`,
1943
+ `find_first_not_of`, and `find_last_not_of`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1944
 
1945
+ - Each member function of the form
1946
  ``` cpp
1947
+ constexpr size_type F(const basic_string& str, size_type pos) const noexcept;
1948
  ```
1949
 
1950
+ has effects equivalent to:
1951
+ `return F(basic_string_view<charT, traits>(str), pos);`
1952
+ - Each member function of the form
 
 
1953
  ``` cpp
1954
+ constexpr size_type F(const charT* s, size_type pos) const;
1955
  ```
1956
 
1957
+ has effects equivalent to:
1958
+ `return F(basic_string_view<charT, traits>(s), pos);`
1959
+ - Each member function of the form
 
1960
  ``` cpp
1961
+ constexpr size_type F(const charT* s, size_type pos, size_type n) const;
1962
  ```
1963
 
1964
+ has effects equivalent to:
1965
+ `return F(basic_string_view<charT, traits>(s, n), pos);`
1966
+ - Each member function of the form
 
 
 
 
 
 
 
1967
  ``` cpp
1968
+ constexpr size_type F(charT c, size_type pos) const noexcept;
1969
  ```
1970
 
1971
+ has effects equivalent to:
 
 
1972
  ``` cpp
1973
+ return F(basic_string_view<charT, traits>(addressof(c), 1), pos);
1974
  ```
1975
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1976
  ``` cpp
1977
+ template<class T>
1978
+ constexpr size_type find(const T& t, size_type pos = 0) const noexcept(see below);
1979
+ template<class T>
1980
+ constexpr size_type rfind(const T& t, size_type pos = npos) const noexcept(see below);
1981
+ template<class T>
1982
+ constexpr size_type find_first_of(const T& t, size_type pos = 0) const noexcept(see below);
1983
+ template<class T>
1984
+ constexpr size_type find_last_of(const T& t, size_type pos = npos) const noexcept(see below);
1985
+ template<class T>
1986
+ constexpr size_type find_first_not_of(const T& t, size_type pos = 0) const noexcept(see below);
1987
+ template<class T>
1988
+ constexpr size_type find_last_not_of(const T& t, size_type pos = npos) const noexcept(see below);
1989
  ```
1990
 
1991
+ *Constraints:*
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1992
 
1993
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
1994
+ `true` and
1995
+ - `is_convertible_v<const T&, const charT*>` is `false`.
1996
 
1997
+ *Effects:* Let *G* be the name of the function. Equivalent to:
1998
 
1999
  ``` cpp
2000
+ basic_string_view<charT, traits> s = *this, sv = t;
2001
+ return s.G(sv, pos);
2002
  ```
2003
 
2004
+ *Remarks:* The expression inside `noexcept` is equivalent to
2005
+ `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
2006
 
2007
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
2008
 
2009
  ``` cpp
2010
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
2011
  ```
2012
 
2013
  *Throws:* `out_of_range` if `pos > size()`.
2014
 
2015
  *Effects:* Determines the effective length `rlen` of the string to copy
 
2018
  *Returns:* `basic_string(data()+pos, rlen)`.
2019
 
2020
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
2021
 
2022
  ``` cpp
2023
+ template<class T>
2024
+ constexpr int compare(const T& t) const noexcept(see below);
2025
  ```
2026
 
2027
+ *Constraints:*
 
 
 
2028
 
2029
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
2030
+ `true` and
2031
+ - `is_convertible_v<const T&, const charT*>` is `false`.
2032
 
2033
+ *Effects:* Equivalent to:
2034
+ `return basic_string_view<charT, traits>(*this).compare(t);`
2035
 
2036
+ *Remarks:* The expression inside `noexcept` is equivalent to
2037
+ `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
 
 
 
2038
 
2039
  ``` cpp
2040
+ template<class T>
2041
+ constexpr int compare(size_type pos1, size_type n1, const T& t) const;
2042
  ```
2043
 
2044
+ *Constraints:*
2045
+
2046
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
2047
+ `true` and
2048
+ - `is_convertible_v<const T&, const charT*>` is `false`.
2049
+
2050
  *Effects:* Equivalent to:
2051
 
2052
  ``` cpp
2053
+ return basic_string_view<charT, traits>(*this).substr(pos1, n1).compare(t);
2054
  ```
2055
 
2056
  ``` cpp
2057
  template<class T>
2058
+ constexpr int compare(size_type pos1, size_type n1, const T& t,
2059
  size_type pos2, size_type n2 = npos) const;
2060
  ```
2061
 
2062
+ *Constraints:*
2063
+
2064
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
2065
+ `true` and
2066
+ - `is_convertible_v<const T&, const charT*>` is `false`.
2067
+
2068
  *Effects:* Equivalent to:
2069
 
2070
  ``` cpp
2071
+ basic_string_view<charT, traits> s = *this, sv = t;
2072
+ return s.substr(pos1, n1).compare(sv.substr(pos2, n2));
 
2073
  ```
2074
 
 
 
 
 
2075
  ``` cpp
2076
+ constexpr int compare(const basic_string& str) const noexcept;
2077
  ```
2078
 
2079
  *Effects:* Equivalent to:
2080
  `return compare(basic_string_view<charT, traits>(str));`
2081
 
2082
  ``` cpp
2083
+ constexpr int compare(size_type pos1, size_type n1, const basic_string& str) const;
2084
  ```
2085
 
2086
  *Effects:* Equivalent to:
2087
  `return compare(pos1, n1, basic_string_view<charT, traits>(str));`
2088
 
2089
  ``` cpp
2090
+ constexpr int compare(size_type pos1, size_type n1, const basic_string& str,
 
2091
  size_type pos2, size_type n2 = npos) const;
2092
  ```
2093
 
2094
  *Effects:* Equivalent to:
2095
 
2096
  ``` cpp
2097
  return compare(pos1, n1, basic_string_view<charT, traits>(str), pos2, n2);
2098
  ```
2099
 
2100
  ``` cpp
2101
+ constexpr int compare(const charT* s) const;
2102
  ```
2103
 
2104
+ *Effects:* Equivalent to:
2105
+ `return compare(basic_string_view<charT, traits>(s));`
2106
 
2107
  ``` cpp
2108
+ constexpr int compare(size_type pos, size_type n1, const charT* s) const;
2109
  ```
2110
 
2111
+ *Effects:* Equivalent to:
2112
+ `return compare(pos, n1, basic_string_view<charT, traits>(s));`
2113
 
2114
  ``` cpp
2115
+ constexpr int compare(size_type pos, size_type n1, const charT* s, size_type n2) const;
2116
  ```
2117
 
2118
+ *Effects:* Equivalent to:
2119
+ `return compare(pos, n1, basic_string_view<charT, traits>(s, n2));`
2120
 
2121
+ ##### `basic_string::starts_with` <a id="string.starts.with">[[string.starts.with]]</a>
 
 
2122
 
2123
  ``` cpp
2124
+ constexpr bool starts_with(basic_string_view<charT, traits> x) const noexcept;
2125
+ constexpr bool starts_with(charT x) const noexcept;
2126
+ constexpr bool starts_with(const charT* x) const;
 
2127
  ```
2128
 
2129
+ *Effects:* Equivalent to:
2130
 
2131
  ``` cpp
2132
+ return basic_string_view<charT, traits>(data(), size()).starts_with(x);
 
 
 
2133
  ```
2134
 
2135
+ ##### `basic_string::ends_with` <a id="string.ends.with">[[string.ends.with]]</a>
2136
 
2137
  ``` cpp
2138
+ constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
2139
+ constexpr bool ends_with(charT x) const noexcept;
2140
+ constexpr bool ends_with(const charT* x) const;
 
2141
  ```
2142
 
2143
+ *Effects:* Equivalent to:
2144
 
2145
  ``` cpp
2146
+ return basic_string_view<charT, traits>(data(), size()).ends_with(x);
 
 
 
2147
  ```
2148
 
2149
+ ### Non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
2150
 
2151
+ #### `operator+` <a id="string.op.plus">[[string.op.plus]]</a>
 
2152
 
2153
  ``` cpp
2154
  template<class charT, class traits, class Allocator>
2155
+ constexpr basic_string<charT, traits, Allocator>
2156
+ operator+(const basic_string<charT, traits, Allocator>& lhs,
2157
  const basic_string<charT, traits, Allocator>& rhs);
2158
+ template<class charT, class traits, class Allocator>
2159
+ constexpr basic_string<charT, traits, Allocator>
2160
+ operator+(const basic_string<charT, traits, Allocator>& lhs, const charT* rhs);
2161
  ```
2162
 
2163
+ *Effects:* Equivalent to:
 
 
2164
 
2165
  ``` cpp
2166
+ basic_string<charT, traits, Allocator> r = lhs;
2167
+ r.append(rhs);
2168
+ return r;
 
2169
  ```
2170
 
 
 
 
 
2171
  ``` cpp
2172
  template<class charT, class traits, class Allocator>
2173
+ constexpr basic_string<charT, traits, Allocator>
2174
+ operator+(basic_string<charT, traits, Allocator>&& lhs,
2175
  const basic_string<charT, traits, Allocator>& rhs);
 
 
 
 
 
2176
  template<class charT, class traits, class Allocator>
2177
+ constexpr basic_string<charT, traits, Allocator>
2178
+ operator+(basic_string<charT, traits, Allocator>&& lhs, const charT* rhs);
 
2179
  ```
2180
 
2181
+ *Effects:* Equivalent to:
2182
 
2183
  ``` cpp
2184
+ lhs.append(rhs);
2185
+ return std::move(lhs);
 
 
2186
  ```
2187
 
 
 
 
 
2188
  ``` cpp
2189
  template<class charT, class traits, class Allocator>
2190
+ constexpr basic_string<charT, traits, Allocator>
2191
  operator+(basic_string<charT, traits, Allocator>&& lhs,
2192
+ basic_string<charT, traits, Allocator>&& rhs);
 
 
 
 
 
 
 
 
 
 
 
2193
  ```
2194
 
2195
+ *Effects:* Equivalent to:
2196
 
2197
  ``` cpp
2198
+ lhs.append(rhs);
2199
+ return std::move(lhs);
 
 
2200
  ```
2201
 
2202
+ except that both `lhs` and `rhs` are left in valid but unspecified
2203
+ states.
2204
 
2205
+ [*Note 1*: If `lhs` and `rhs` have equal allocators, the implementation
2206
+ may move from either. — *end note*]
2207
 
2208
  ``` cpp
2209
  template<class charT, class traits, class Allocator>
2210
+ constexpr basic_string<charT, traits, Allocator>
2211
+ operator+(const basic_string<charT, traits, Allocator>& lhs,
2212
+ basic_string<charT, traits, Allocator>&& rhs);
 
 
 
 
2213
  template<class charT, class traits, class Allocator>
2214
+ constexpr basic_string<charT, traits, Allocator>
2215
+ operator+(const charT* lhs, basic_string<charT, traits, Allocator>&& rhs);
2216
  ```
2217
 
2218
+ *Effects:* Equivalent to:
2219
 
2220
  ``` cpp
2221
+ rhs.insert(0, lhs);
2222
+ return std::move(rhs);
 
2223
  ```
2224
 
 
 
 
 
 
 
 
2225
  ``` cpp
2226
  template<class charT, class traits, class Allocator>
2227
+ constexpr basic_string<charT, traits, Allocator>
2228
+ operator+(const charT* lhs, const basic_string<charT, traits, Allocator>& rhs);
2229
  ```
2230
 
2231
+ *Effects:* Equivalent to:
2232
 
2233
  ``` cpp
2234
+ basic_string<charT, traits, Allocator> r = rhs;
2235
+ r.insert(0, lhs);
2236
+ return r;
2237
  ```
2238
 
 
 
2239
  ``` cpp
2240
  template<class charT, class traits, class Allocator>
2241
+ constexpr basic_string<charT, traits, Allocator>
2242
+ operator+(charT lhs, const basic_string<charT, traits, Allocator>& rhs);
2243
  ```
2244
 
2245
+ *Effects:* Equivalent to:
 
 
 
 
 
2246
 
2247
  ``` cpp
2248
+ basic_string<charT, traits, Allocator> r = rhs;
2249
+ r.insert(r.begin(), lhs);
2250
+ return r;
2251
  ```
2252
 
 
 
2253
  ``` cpp
2254
  template<class charT, class traits, class Allocator>
2255
+ constexpr basic_string<charT, traits, Allocator>
2256
+ operator+(charT lhs, basic_string<charT, traits, Allocator>&& rhs);
2257
  ```
2258
 
2259
+ *Effects:* Equivalent to:
2260
 
2261
  ``` cpp
2262
+ rhs.insert(rhs.begin(), lhs);
2263
+ return std::move(rhs);
 
2264
  ```
2265
 
 
 
 
 
2266
  ``` cpp
2267
  template<class charT, class traits, class Allocator>
2268
+ constexpr basic_string<charT, traits, Allocator>
2269
+ operator+(const basic_string<charT, traits, Allocator>& lhs, charT rhs);
2270
  ```
2271
 
2272
+ *Effects:* Equivalent to:
2273
 
2274
  ``` cpp
2275
+ basic_string<charT, traits, Allocator> r = lhs;
2276
+ r.push_back(rhs);
2277
+ return r;
2278
  ```
2279
 
 
 
2280
  ``` cpp
2281
  template<class charT, class traits, class Allocator>
2282
+ constexpr basic_string<charT, traits, Allocator>
2283
+ operator+(basic_string<charT, traits, Allocator>&& lhs, charT rhs);
2284
  ```
2285
 
2286
+ *Effects:* Equivalent to:
 
 
2287
 
2288
  ``` cpp
2289
+ lhs.push_back(rhs);
2290
+ return std::move(lhs);
 
2291
  ```
2292
 
2293
+ #### Non-member comparison functions <a id="string.cmp">[[string.cmp]]</a>
2294
 
2295
  ``` cpp
2296
  template<class charT, class traits, class Allocator>
2297
+ constexpr bool
2298
+ operator==(const basic_string<charT, traits, Allocator>& lhs,
2299
+ const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
 
 
 
2300
  template<class charT, class traits, class Allocator>
2301
+ constexpr bool operator==(const basic_string<charT, traits, Allocator>& lhs,
2302
  const charT* rhs);
 
2303
 
 
 
 
 
 
2304
  template<class charT, class traits, class Allocator>
2305
+ constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,
2306
+ \itcorr const basic_string<charT, traits, Allocator>& rhs) noexcept;
 
 
 
 
 
2307
  template<class charT, class traits, class Allocator>
2308
+ constexpr see below operator<=>(const basic_string<charT, traits, Allocator>& lhs,
2309
+ \itcorr const charT* rhs);
2310
  ```
2311
 
2312
+ *Effects:* Let *`op`* be the operator. Equivalent to:
2313
 
2314
  ``` cpp
2315
+ return basic_string_view<charT, traits>(lhs) op basic_string_view<charT, traits>(rhs);
 
 
2316
  ```
2317
 
 
 
2318
  #### `swap` <a id="string.special">[[string.special]]</a>
2319
 
2320
  ``` cpp
2321
  template<class charT, class traits, class Allocator>
2322
+ constexpr void
2323
+ swap(basic_string<charT, traits, Allocator>& lhs,
2324
  basic_string<charT, traits, Allocator>& rhs)
2325
  noexcept(noexcept(lhs.swap(rhs)));
2326
  ```
2327
 
2328
+ *Effects:* Equivalent to `lhs.swap(rhs)`.
2329
 
2330
  #### Inserters and extractors <a id="string.io">[[string.io]]</a>
2331
 
2332
  ``` cpp
2333
  template<class charT, class traits, class Allocator>
2334
  basic_istream<charT, traits>&
2335
+ operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);
 
2336
  ```
2337
 
2338
  *Effects:* Behaves as a formatted input
2339
+ function [[istream.formatted.reqmts]]. After constructing a `sentry`
2340
  object, if the sentry converts to `true`, calls `str.erase()` and then
2341
  extracts characters from `is` and appends them to `str` as if by calling
2342
  `str.append(1, c)`. If `is.width()` is greater than zero, the maximum
2343
  number `n` of characters appended is `is.width()`; otherwise `n` is
2344
  `str.max_size()`. Characters are extracted and appended until any of the
 
2351
 
2352
  After the last character (if any) is extracted, `is.width(0)` is called
2353
  and the `sentry` object is destroyed.
2354
 
2355
  If the function extracts no characters, it calls
2356
+ `is.setstate(ios_base::failbit)`, which may throw `ios_base::failure`
2357
+ [[iostate.flags]].
2358
 
2359
  *Returns:* `is`.
2360
 
2361
  ``` cpp
2362
  template<class charT, class traits, class Allocator>
 
2380
  basic_string<charT, traits, Allocator>& str,
2381
  charT delim);
2382
  ```
2383
 
2384
  *Effects:* Behaves as an unformatted input
2385
+ function [[istream.unformatted]], except that it does not affect the
2386
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2387
  constructing a `sentry` object, if the sentry converts to `true`, calls
2388
  `str.erase()` and then extracts characters from `is` and appends them to
2389
  `str` as if by calling `str.append(1, c)` until any of the following
2390
  occurs:
2391
 
2392
  - end-of-file occurs on the input sequence (in which case, the `getline`
2393
  function calls `is.setstate(ios_base::eofbit)`).
2394
  - `traits::eq(c, delim)` for the next available input character *c* (in
2395
+ which case, *c* is extracted but not appended) [[iostate.flags]]
2396
  - `str.max_size()` characters are stored (in which case, the function
2397
+ calls `is.setstate(ios_base::failbit))` [[iostate.flags]]
2398
 
2399
  The conditions are tested in the order shown. In any case, after the
2400
  last character is extracted, the `sentry` object is destroyed.
2401
 
2402
  If the function extracts no characters, it calls
2403
+ `is.setstate(ios_base::failbit)` which may throw `ios_base::failure`
2404
+ [[iostate.flags]].
2405
 
2406
  *Returns:* `is`.
2407
 
2408
  ``` cpp
2409
  template<class charT, class traits, class Allocator>
 
2416
  basic_string<charT, traits, Allocator>& str);
2417
  ```
2418
 
2419
  *Returns:* `getline(is, str, is.widen(’\n’))`.
2420
 
2421
+ #### Erasure <a id="string.erasure">[[string.erasure]]</a>
2422
+
2423
+ ``` cpp
2424
+ template<class charT, class traits, class Allocator, class U>
2425
+ constexpr typename basic_string<charT, traits, Allocator>::size_type
2426
+ erase(basic_string<charT, traits, Allocator>& c, const U& value);
2427
+ ```
2428
+
2429
+ *Effects:* Equivalent to:
2430
+
2431
+ ``` cpp
2432
+ auto it = remove(c.begin(), c.end(), value);
2433
+ auto r = distance(it, c.end());
2434
+ c.erase(it, c.end());
2435
+ return r;
2436
+ ```
2437
+
2438
+ ``` cpp
2439
+ template<class charT, class traits, class Allocator, class Predicate>
2440
+ constexpr typename basic_string<charT, traits, Allocator>::size_type
2441
+ erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
2442
+ ```
2443
+
2444
+ *Effects:* Equivalent to:
2445
+
2446
+ ``` cpp
2447
+ auto it = remove_if(c.begin(), c.end(), pred);
2448
+ auto r = distance(it, c.end());
2449
+ c.erase(it, c.end());
2450
+ return r;
2451
+ ```
2452
+
2453
  ### Numeric conversions <a id="string.conversions">[[string.conversions]]</a>
2454
 
2455
  ``` cpp
2456
+ int stoi(const string& str, size_t* idx = nullptr, int base = 10);
2457
+ long stol(const string& str, size_t* idx = nullptr, int base = 10);
2458
+ unsigned long stoul(const string& str, size_t* idx = nullptr, int base = 10);
2459
+ long long stoll(const string& str, size_t* idx = nullptr, int base = 10);
2460
+ unsigned long long stoull(const string& str, size_t* idx = nullptr, int base = 10);
2461
  ```
2462
 
2463
+ *Effects:* The first two functions call
2464
  `strtol(str.c_str(), ptr, base)`, and the last three functions call
2465
  `strtoul(str.c_str(), ptr, base)`, `strtoll(str.c_str(), ptr, base)`,
2466
  and `strtoull(str.c_str(), ptr, base)`, respectively. Each function
2467
  returns the converted result, if any. The argument `ptr` designates a
2468
  pointer to an object internal to the function that is used to determine
 
2477
  `out_of_range` if `strtol`, `strtoul`, `strtoll` or `strtoull` sets
2478
  `errno` to `ERANGE`, or if the converted value is outside the range of
2479
  representable values for the return type.
2480
 
2481
  ``` cpp
2482
+ float stof(const string& str, size_t* idx = nullptr);
2483
+ double stod(const string& str, size_t* idx = nullptr);
2484
+ long double stold(const string& str, size_t* idx = nullptr);
2485
  ```
2486
 
2487
  *Effects:* These functions call `strtof(str.c_str(), ptr)`,
2488
  `strtod(str.c_str(), ptr)`, and `strtold(str.c_str(), ptr)`,
2489
  respectively. Each function returns the converted result, if any. The
 
2518
  `"%u"`, `"%ld"`, `"%lu"`, `"%lld"`, `"%llu"`, `"%f"`, `"%f"`, or
2519
  `"%Lf"`, respectively, where `buf` designates an internal character
2520
  buffer of sufficient size.
2521
 
2522
  ``` cpp
2523
+ int stoi(const wstring& str, size_t* idx = nullptr, int base = 10);
2524
+ long stol(const wstring& str, size_t* idx = nullptr, int base = 10);
2525
+ unsigned long stoul(const wstring& str, size_t* idx = nullptr, int base = 10);
2526
+ long long stoll(const wstring& str, size_t* idx = nullptr, int base = 10);
2527
+ unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base = 10);
2528
  ```
2529
 
2530
+ *Effects:* The first two functions call
2531
  `wcstol(str.c_str(), ptr, base)`, and the last three functions call
2532
  `wcstoul(str.c_str(), ptr, base)`, `wcstoll(str.c_str(), ptr, base)`,
2533
  and `wcstoull(str.c_str(), ptr, base)`, respectively. Each function
2534
  returns the converted result, if any. The argument `ptr` designates a
2535
  pointer to an object internal to the function that is used to determine
 
2543
  `wcstoull` reports that no conversion could be performed. Throws
2544
  `out_of_range` if the converted value is outside the range of
2545
  representable values for the return type.
2546
 
2547
  ``` cpp
2548
+ float stof(const wstring& str, size_t* idx = nullptr);
2549
+ double stod(const wstring& str, size_t* idx = nullptr);
2550
+ long double stold(const wstring& str, size_t* idx = nullptr);
2551
  ```
2552
 
2553
  *Effects:* These functions call `wcstof(str.c_str(), ptr)`,
2554
  `wcstod(str.c_str(), ptr)`, and `wcstold(str.c_str(), ptr)`,
2555
  respectively. Each function returns the converted result, if any. The
 
2585
 
2586
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2587
 
2588
  ``` cpp
2589
  template<> struct hash<string>;
2590
+ template<> struct hash<u8string>;
2591
  template<> struct hash<u16string>;
2592
  template<> struct hash<u32string>;
2593
  template<> struct hash<wstring>;
2594
+ template<> struct hash<pmr::string>;
2595
+ template<> struct hash<pmr::u8string>;
2596
+ template<> struct hash<pmr::u16string>;
2597
+ template<> struct hash<pmr::u32string>;
2598
+ template<> struct hash<pmr::wstring>;
2599
  ```
2600
 
2601
  If `S` is one of these string types, `SV` is the corresponding string
2602
  view type, and `s` is an object of type `S`, then
2603
  `hash<S>()(s) == hash<SV>()(SV(s))`.
2604
 
2605
  ### Suffix for `basic_string` literals <a id="basic.string.literals">[[basic.string.literals]]</a>
2606
 
2607
  ``` cpp
2608
+ constexpr string operator""s(const char* str, size_t len);
2609
  ```
2610
 
2611
  *Returns:* `string{str, len}`.
2612
 
2613
  ``` cpp
2614
+ constexpr u8string operator""s(const char8_t* str, size_t len);
2615
+ ```
2616
+
2617
+ *Returns:* `u8string{str, len}`.
2618
+
2619
+ ``` cpp
2620
+ constexpr u16string operator""s(const char16_t* str, size_t len);
2621
  ```
2622
 
2623
  *Returns:* `u16string{str, len}`.
2624
 
2625
  ``` cpp
2626
+ constexpr u32string operator""s(const char32_t* str, size_t len);
2627
  ```
2628
 
2629
  *Returns:* `u32string{str, len}`.
2630
 
2631
  ``` cpp
2632
+ constexpr wstring operator""s(const wchar_t* str, size_t len);
2633
  ```
2634
 
2635
  *Returns:* `wstring{str, len}`.
2636
 
2637
  [*Note 1*: The same suffix `s` is used for `chrono::duration` literals
 
2640
  literals. — *end note*]
2641
 
2642
  ## String view classes <a id="string.view">[[string.view]]</a>
2643
 
2644
  The class template `basic_string_view` describes an object that can
2645
+ refer to a constant contiguous sequence of char-like [[strings.general]]
2646
+ objects with the first element of the sequence at position zero. In the
2647
+ rest of this subclause, the type of the char-like objects held in a
2648
+ `basic_string_view` object is designated by `charT`.
2649
 
2650
  [*Note 1*: The library provides implicit conversions from
2651
  `const charT*` and `std::basic_string<charT, ...>` to
2652
  `std::basic_string_view<charT, ...>` so that user code can accept just
2653
  `std::basic_string_view<charT>` as a non-templated parameter wherever a
2654
  sequence of characters is expected. User-defined types should define
2655
  their own implicit conversions to `std::basic_string_view` in order to
2656
  interoperate with these functions. — *end note*]
2657
 
 
 
 
2658
  ### Header `<string_view>` synopsis <a id="string.view.synop">[[string.view.synop]]</a>
2659
 
2660
  ``` cpp
2661
+ #include <compare> // see [compare.syn]
2662
+
2663
  namespace std {
2664
  // [string.view.template], class template basic_string_view
2665
  template<class charT, class traits = char_traits<charT>>
2666
  class basic_string_view;
2667
 
2668
+ template<class charT, class traits>
2669
+ inline constexpr bool ranges::enable_view<basic_string_view<charT, traits>> = true;
2670
+ template<class charT, class traits>
2671
+ inline constexpr bool ranges::enable_borrowed_range<basic_string_view<charT, traits>> = true;
2672
+
2673
  // [string.view.comparison], non-member comparison functions
2674
  template<class charT, class traits>
2675
  constexpr bool operator==(basic_string_view<charT, traits> x,
2676
  basic_string_view<charT, traits> y) noexcept;
2677
  template<class charT, class traits>
2678
+ constexpr see below operator<=>(basic_string_view<charT, traits> x,
2679
+ \itcorr basic_string_view<charT, traits> y) noexcept;
2680
+
 
 
 
 
 
 
 
 
 
 
 
2681
  // see [string.view.comparison], sufficient additional overloads of comparison functions
2682
 
2683
  // [string.view.io], inserters and extractors
2684
  template<class charT, class traits>
2685
  basic_ostream<charT, traits>&
2686
  operator<<(basic_ostream<charT, traits>& os,
2687
  basic_string_view<charT, traits> str);
2688
 
2689
  // basic_string_view typedef names
2690
  using string_view = basic_string_view<char>;
2691
+ using u8string_view = basic_string_view<char8_t>;
2692
  using u16string_view = basic_string_view<char16_t>;
2693
  using u32string_view = basic_string_view<char32_t>;
2694
  using wstring_view = basic_string_view<wchar_t>;
2695
 
2696
  // [string.view.hash], hash support
2697
  template<class T> struct hash;
2698
  template<> struct hash<string_view>;
2699
+ template<> struct hash<u8string_view>;
2700
  template<> struct hash<u16string_view>;
2701
  template<> struct hash<u32string_view>;
2702
  template<> struct hash<wstring_view>;
2703
 
2704
  inline namespace literals {
2705
  inline namespace string_view_literals {
2706
  // [string.view.literals], suffix for basic_string_view literals
2707
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
2708
+ constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
2709
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
2710
  constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
2711
  constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
2712
  }
2713
  }
 
2742
  constexpr basic_string_view() noexcept;
2743
  constexpr basic_string_view(const basic_string_view&) noexcept = default;
2744
  constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
2745
  constexpr basic_string_view(const charT* str);
2746
  constexpr basic_string_view(const charT* str, size_type len);
2747
+ template<class It, class End>
2748
+ constexpr basic_string_view(It begin, End end);
2749
 
2750
  // [string.view.iterators], iterator support
2751
  constexpr const_iterator begin() const noexcept;
2752
  constexpr const_iterator end() const noexcept;
2753
  constexpr const_iterator cbegin() const noexcept;
 
2759
 
2760
  // [string.view.capacity], capacity
2761
  constexpr size_type size() const noexcept;
2762
  constexpr size_type length() const noexcept;
2763
  constexpr size_type max_size() const noexcept;
2764
+ [[nodiscard]] constexpr bool empty() const noexcept;
2765
 
2766
  // [string.view.access], element access
2767
  constexpr const_reference operator[](size_type pos) const;
2768
  constexpr const_reference at(size_type pos) const;
2769
  constexpr const_reference front() const;
 
2774
  constexpr void remove_prefix(size_type n);
2775
  constexpr void remove_suffix(size_type n);
2776
  constexpr void swap(basic_string_view& s) noexcept;
2777
 
2778
  // [string.view.ops], string operations
2779
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
2780
 
2781
  constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
2782
+
2783
  constexpr int compare(basic_string_view s) const noexcept;
2784
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
2785
  constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
2786
  size_type pos2, size_type n2) const;
2787
  constexpr int compare(const charT* s) const;
2788
  constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
2789
+ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
2790
+
2791
+ constexpr bool starts_with(basic_string_view x) const noexcept;
2792
+ constexpr bool starts_with(charT x) const noexcept;
2793
+ constexpr bool starts_with(const charT* x) const;
2794
+ constexpr bool ends_with(basic_string_view x) const noexcept;
2795
+ constexpr bool ends_with(charT x) const noexcept;
2796
+ constexpr bool ends_with(const charT* x) const;
2797
+
2798
+ // [string.view.find], searching
2799
  constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
2800
  constexpr size_type find(charT c, size_type pos = 0) const noexcept;
2801
  constexpr size_type find(const charT* s, size_type pos, size_type n) const;
2802
  constexpr size_type find(const charT* s, size_type pos = 0) const;
2803
  constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
2804
  constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
2805
  constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
2806
  constexpr size_type rfind(const charT* s, size_type pos = npos) const;
2807
+
2808
  constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
2809
  constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
2810
  constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
2811
  constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
2812
  constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
 
2827
 
2828
  private:
2829
  const_pointer data_; // exposition only
2830
  size_type size_; // exposition only
2831
  };
2832
+
2833
+ // [string.view.deduct], deduction guide
2834
+ template<class It, class End>
2835
+ basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
2836
  ```
2837
 
2838
  In every specialization `basic_string_view<charT, traits>`, the type
2839
+ `traits` shall meet the character traits requirements [[char.traits]].
2840
+
2841
+ [*Note 1*: The program is ill-formed if `traits::char_type` is not the
2842
+ same type as `charT`. — *end note*]
2843
+
2844
+ For a `basic_string_view str`, any operation that invalidates a pointer
2845
+ in the range \[`str.data()`, `str.data() + str.size()`) invalidates
2846
+ pointers, iterators, and references returned from `str`’s member
2847
+ functions.
2848
+
2849
+ The complexity of `basic_string_view` member functions is 𝑂(1) unless
2850
+ otherwise specified.
2851
 
2852
  #### Construction and assignment <a id="string.view.cons">[[string.view.cons]]</a>
2853
 
2854
  ``` cpp
2855
  constexpr basic_string_view() noexcept;
2856
  ```
2857
 
2858
+ *Ensures:* `size_ == 0` and `data_ == nullptr`.
 
 
2859
 
2860
  ``` cpp
2861
  constexpr basic_string_view(const charT* str);
2862
  ```
2863
 
2864
+ *Preconditions:* \[`str`, `str + traits::length(str)`) is a valid range.
2865
 
2866
+ *Effects:* Constructs a `basic_string_view`, initializing `data_` with
2867
+ `str` and initializing `size_` with `traits::length(str)`.
2868
 
2869
  *Complexity:* 𝑂(`traits::length(str)`).
2870
 
2871
  ``` cpp
2872
  constexpr basic_string_view(const charT* str, size_type len);
2873
  ```
2874
 
2875
+ *Preconditions:* \[`str`, `str + len`) is a valid range.
2876
 
2877
+ *Effects:* Constructs a `basic_string_view`, initializing `data_` with
2878
+ `str` and initializing `size_` with `len`.
2879
+
2880
+ ``` cpp
2881
+ template<class It, class End>
2882
+ constexpr basic_string_view(It begin, End end);
2883
+ ```
2884
+
2885
+ *Constraints:*
2886
+
2887
+ - `It` satisfies `contiguous_iterator`.
2888
+ - `End` satisfies `sized_sentinel_for<It>`.
2889
+ - `is_same_v<iter_value_t<It>, charT>` is `true`.
2890
+ - `is_convertible_v<End, size_type>` is `false`.
2891
+
2892
+ *Preconditions:*
2893
+
2894
+ - \[`begin`, `end`) is a valid range.
2895
+ - `It` models `contiguous_iterator`.
2896
+ - `End` models `sized_sentinel_for<It>`.
2897
+
2898
+ *Effects:* Initializes `data_` with `to_address(begin)` and initializes
2899
+ `size_` with `end - begin`.
2900
 
2901
  #### Iterator support <a id="string.view.iterators">[[string.view.iterators]]</a>
2902
 
2903
  ``` cpp
2904
  using const_iterator = implementation-defined // type of basic_string_view::const_iterator;
2905
  ```
2906
 
2907
+ A type that meets the requirements of a constant
2908
+ *Cpp17RandomAccessIterator*[[random.access.iterators]], models
2909
+ `contiguous_iterator` [[iterator.concept.contiguous]], and meets the
2910
+ constexpr iterator requirements [[iterator.requirements.general]], whose
2911
+ `value_type` is the template parameter `charT`.
2912
 
2913
+ All requirements on container iterators [[container.requirements]] apply
2914
+ to `basic_string_view::const_iterator` as well.
 
 
 
 
2915
 
2916
  ``` cpp
2917
  constexpr const_iterator begin() const noexcept;
2918
  constexpr const_iterator cbegin() const noexcept;
2919
  ```
2920
 
2921
  *Returns:* An iterator such that
2922
 
2923
+ - if `!empty()`, `addressof(*begin()) == data_`,
2924
  - otherwise, an unspecified value such that \[`begin()`, `end()`) is a
2925
  valid range.
2926
 
2927
  ``` cpp
2928
  constexpr const_iterator end() const noexcept;
 
2947
 
2948
  #### Capacity <a id="string.view.capacity">[[string.view.capacity]]</a>
2949
 
2950
  ``` cpp
2951
  constexpr size_type size() const noexcept;
 
 
 
 
 
2952
  constexpr size_type length() const noexcept;
2953
  ```
2954
 
2955
  *Returns:* `size_`.
2956
 
 
2960
 
2961
  *Returns:* The largest possible number of char-like objects that can be
2962
  referred to by a `basic_string_view`.
2963
 
2964
  ``` cpp
2965
+ [[nodiscard]] constexpr bool empty() const noexcept;
2966
  ```
2967
 
2968
  *Returns:* `size_ == 0`.
2969
 
2970
  #### Element access <a id="string.view.access">[[string.view.access]]</a>
2971
 
2972
  ``` cpp
2973
  constexpr const_reference operator[](size_type pos) const;
2974
  ```
2975
 
2976
+ *Preconditions:* `pos < size()`.
2977
 
2978
  *Returns:* `data_[pos]`.
2979
 
2980
  *Throws:* Nothing.
2981
 
 
2993
 
2994
  ``` cpp
2995
  constexpr const_reference front() const;
2996
  ```
2997
 
2998
+ *Preconditions:* `!empty()`.
2999
 
3000
  *Returns:* `data_[0]`.
3001
 
3002
  *Throws:* Nothing.
3003
 
3004
  ``` cpp
3005
  constexpr const_reference back() const;
3006
  ```
3007
 
3008
+ *Preconditions:* `!empty()`.
3009
 
3010
  *Returns:* `data_[size() - 1]`.
3011
 
3012
  *Throws:* Nothing.
3013
 
 
3015
  constexpr const_pointer data() const noexcept;
3016
  ```
3017
 
3018
  *Returns:* `data_`.
3019
 
3020
+ [*Note 2*: Unlike `basic_string::data()` and *string-literal*s,
3021
+ `data()` may return a pointer to a buffer that is not null-terminated.
3022
+ Therefore it is typically a mistake to pass `data()` to a function that
3023
+ takes just a `const charT*` and expects a null-terminated
3024
+ string. — *end note*]
3025
 
3026
  #### Modifiers <a id="string.view.modifiers">[[string.view.modifiers]]</a>
3027
 
3028
  ``` cpp
3029
  constexpr void remove_prefix(size_type n);
3030
  ```
3031
 
3032
+ *Preconditions:* `n <= size()`.
3033
 
3034
  *Effects:* Equivalent to: `data_ += n; size_ -= n;`
3035
 
3036
  ``` cpp
3037
  constexpr void remove_suffix(size_type n);
3038
  ```
3039
 
3040
+ *Preconditions:* `n <= size()`.
3041
 
3042
  *Effects:* Equivalent to: `size_ -= n;`
3043
 
3044
  ``` cpp
3045
  constexpr void swap(basic_string_view& s) noexcept;
 
3048
  *Effects:* Exchanges the values of `*this` and `s`.
3049
 
3050
  #### String operations <a id="string.view.ops">[[string.view.ops]]</a>
3051
 
3052
  ``` cpp
3053
+ constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
3054
  ```
3055
 
3056
  Let `rlen` be the smaller of `n` and `size() - pos`.
3057
 
3058
  *Throws:* `out_of_range` if `pos > size()`.
3059
 
3060
+ *Preconditions:* \[`s`, `s + rlen`) is a valid range.
3061
 
3062
  *Effects:* Equivalent to `traits::copy(s, data() + pos, rlen)`.
3063
 
3064
  *Returns:* `rlen`.
3065
 
 
3090
 
3091
  *Complexity:* 𝑂(`rlen`).
3092
 
3093
  *Returns:* The nonzero result if the result of the comparison is
3094
  nonzero. Otherwise, returns a value as indicated in
3095
+ [[string.view.compare]].
3096
 
3097
+ **Table: `compare()` results** <a id="string.view.compare">[string.view.compare]</a>
3098
 
3099
  | Condition | Return Value |
3100
  | ---------------------- | ------------ |
3101
  | `size() < str.size()` | `< 0` |
3102
  | `size() == str.size()` | ` 0` |
 
3128
 
3129
  *Effects:* Equivalent to:
3130
  `return substr(pos1, n1).compare(basic_string_view(s));`
3131
 
3132
  ``` cpp
3133
+ constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
 
3134
  ```
3135
 
3136
  *Effects:* Equivalent to:
3137
  `return substr(pos1, n1).compare(basic_string_view(s, n2));`
3138
 
3139
+ ``` cpp
3140
+ constexpr bool starts_with(basic_string_view x) const noexcept;
3141
+ ```
3142
+
3143
+ *Effects:* Equivalent to: `return substr(0, x.size()) == x;`
3144
+
3145
+ ``` cpp
3146
+ constexpr bool starts_with(charT x) const noexcept;
3147
+ ```
3148
+
3149
+ *Effects:* Equivalent to: `return !empty() && traits::eq(front(), x);`
3150
+
3151
+ ``` cpp
3152
+ constexpr bool starts_with(const charT* x) const;
3153
+ ```
3154
+
3155
+ *Effects:* Equivalent to: `return starts_with(basic_string_view(x));`
3156
+
3157
+ ``` cpp
3158
+ constexpr bool ends_with(basic_string_view x) const noexcept;
3159
+ ```
3160
+
3161
+ *Effects:* Equivalent to:
3162
+
3163
+ ``` cpp
3164
+ return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
3165
+ ```
3166
+
3167
+ ``` cpp
3168
+ constexpr bool ends_with(charT x) const noexcept;
3169
+ ```
3170
+
3171
+ *Effects:* Equivalent to: `return !empty() && traits::eq(back(), x);`
3172
+
3173
+ ``` cpp
3174
+ constexpr bool ends_with(const charT* x) const;
3175
+ ```
3176
+
3177
+ *Effects:* Equivalent to: `return ends_with(basic_string_view(x));`
3178
+
3179
  #### Searching <a id="string.view.find">[[string.view.find]]</a>
3180
 
3181
+ Member functions in this subclause have complexity
3182
+ 𝑂(`size() * str.size()`) at worst, although implementations should do
3183
+ better.
3184
 
3185
+ Let *F* be one of `find`, `rfind`, `find_first_of`, `find_last_of`,
3186
+ `find_first_not_of`, and `find_last_not_of`.
 
 
 
3187
 
3188
+ - Each member function of the form
3189
  ``` cpp
3190
+ constexpr return-type F(const charT* s, size_type pos) const;
3191
  ```
3192
 
3193
+ has effects equivalent to: `return F(basic_string_view(s), pos);`
3194
+ - Each member function of the form
 
 
3195
  ``` cpp
3196
+ constexpr return-type F(const charT* s, size_type pos, size_type n) const;
3197
  ```
3198
 
3199
+ has effects equivalent to: `return F(basic_string_view(s, n), pos);`
3200
+ - Each member function of the form
 
 
3201
  ``` cpp
3202
+ constexpr return-type F(charT c, size_type pos) const noexcept;
3203
  ```
3204
 
3205
+ has effects equivalent to:
3206
+ `return F(basic_string_view(addressof(c), 1), pos);`
3207
 
3208
  ``` cpp
3209
  constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
3210
  ```
3211
 
 
3305
  *Effects:* Determines `xpos`.
3306
 
3307
  *Returns:* `xpos` if the function can determine such a value for `xpos`.
3308
  Otherwise, returns `npos`.
3309
 
3310
+ ### Deduction guide <a id="string.view.deduct">[[string.view.deduct]]</a>
3311
+
3312
+ ``` cpp
3313
+ template<class It, class End>
3314
+ basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
3315
+ ```
3316
+
3317
+ *Constraints:*
3318
+
3319
+ - `It` satisfies `contiguous_iterator`.
3320
+ - `End` satisfies `sized_sentinel_for<It>`.
3321
+
3322
  ### Non-member comparison functions <a id="string.view.comparison">[[string.view.comparison]]</a>
3323
 
3324
  Let `S` be `basic_string_view<charT, traits>`, and `sv` be an instance
3325
  of `S`. Implementations shall provide sufficient additional overloads
3326
  marked `constexpr` and `noexcept` so that an object `t` with an implicit
3327
+ conversion to `S` can be compared according to
3328
+ [[string.view.comparison.overloads]].
3329
 
3330
+ **Table: Additional `basic_string_view` comparison overloads** <a id="string.view.comparison.overloads">[string.view.comparison.overloads]</a>
3331
 
3332
  | Expression | Equivalent to |
3333
  | ---------- | ------------- |
3334
  | `t == sv` | `S(t) == sv` |
3335
  | `sv == t` | `sv == S(t)` |
 
3341
  | `sv > t` | `sv > S(t)` |
3342
  | `t <= sv` | `S(t) <= sv` |
3343
  | `sv <= t` | `sv <= S(t)` |
3344
  | `t >= sv` | `S(t) >= sv` |
3345
  | `sv >= t` | `sv >= S(t)` |
3346
+ | `t <=> sv` | `S(t) <=> sv` |
3347
+ | `sv <=> t` | `sv <=> S(t)` |
3348
 
3349
 
3350
  [*Example 1*:
3351
 
3352
  A sample conforming implementation for `operator==` would be:
3353
 
3354
  ``` cpp
 
3355
  template<class charT, class traits>
3356
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
3357
  basic_string_view<charT, traits> rhs) noexcept {
3358
  return lhs.compare(rhs) == 0;
3359
  }
3360
  template<class charT, class traits>
3361
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
3362
+ type_identity_t<basic_string_view<charT, traits>> rhs) noexcept {
 
 
 
 
 
3363
  return lhs.compare(rhs) == 0;
3364
  }
3365
  ```
3366
 
3367
  — *end example*]
 
3374
 
3375
  *Returns:* `lhs.compare(rhs) == 0`.
3376
 
3377
  ``` cpp
3378
  template<class charT, class traits>
3379
+ constexpr see below operator<=>(basic_string_view<charT, traits> lhs,
3380
+ \itcorr basic_string_view<charT, traits> rhs) noexcept;
3381
  ```
3382
 
3383
+ Let `R` denote the type `traits::comparison_category` if it exists,
3384
+ otherwise `R` is `weak_ordering`.
3385
 
3386
+ *Returns:* `static_cast<R>(lhs.compare(rhs) <=> 0)`.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3387
 
3388
  ### Inserters and extractors <a id="string.view.io">[[string.view.io]]</a>
3389
 
3390
  ``` cpp
3391
  template<class charT, class traits>
3392
  basic_ostream<charT, traits>&
3393
+ operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits> str);
 
3394
  ```
3395
 
3396
  *Effects:* Behaves as a formatted output
3397
+ function [[ostream.formatted.reqmts]] of `os`. Forms a character
3398
  sequence `seq`, initially consisting of the elements defined by the
3399
  range \[`str.begin()`, `str.end()`). Determines padding for `seq` as
3400
  described in  [[ostream.formatted.reqmts]]. Then inserts `seq` as if by
3401
  calling `os.rdbuf()->sputn(seq, n)`, where `n` is the larger of
3402
  `os.width()` and `str.size()`; then calls `os.width(0)`.
 
3405
 
3406
  ### Hash support <a id="string.view.hash">[[string.view.hash]]</a>
3407
 
3408
  ``` cpp
3409
  template<> struct hash<string_view>;
3410
+ template<> struct hash<u8string_view>;
3411
  template<> struct hash<u16string_view>;
3412
  template<> struct hash<u32string_view>;
3413
  template<> struct hash<wstring_view>;
3414
  ```
3415
 
3416
+ The specialization is enabled [[unord.hash]].
3417
 
3418
  [*Note 1*: The hash value of a string view object is equal to the hash
3419
+ value of the corresponding string
3420
+ object [[basic.string.hash]]. — *end note*]
3421
 
3422
  ### Suffix for `basic_string_view` literals <a id="string.view.literals">[[string.view.literals]]</a>
3423
 
3424
  ``` cpp
3425
  constexpr string_view operator""sv(const char* str, size_t len) noexcept;
3426
  ```
3427
 
3428
  *Returns:* `string_view{str, len}`.
3429
 
3430
+ ``` cpp
3431
+ constexpr u8string_view operator""sv(const char8_t* str, size_t len) noexcept;
3432
+ ```
3433
+
3434
+ *Returns:* `u8string_view{str, len}`.
3435
+
3436
  ``` cpp
3437
  constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
3438
  ```
3439
 
3440
  *Returns:* `u16string_view{str, len}`.
 
3475
  ```
3476
 
3477
  The contents and meaning of the header `<cctype>` are the same as the C
3478
  standard library header `<ctype.h>`.
3479
 
3480
+ See also: ISO C 7.4
3481
 
3482
  ### Header `<cwctype>` synopsis <a id="cwctype.syn">[[cwctype.syn]]</a>
3483
 
3484
  ``` cpp
3485
  namespace std {
 
3511
  ```
3512
 
3513
  The contents and meaning of the header `<cwctype>` are the same as the C
3514
  standard library header `<wctype.h>`.
3515
 
3516
+ See also: ISO C 7.30
3517
 
3518
  ### Header `<cstring>` synopsis <a id="cstring.syn">[[cstring.syn]]</a>
3519
 
3520
  ``` cpp
3521
  namespace std {
 
3531
  int strcmp(const char* s1, const char* s2);
3532
  int strcoll(const char* s1, const char* s2);
3533
  int strncmp(const char* s1, const char* s2, size_t n);
3534
  size_t strxfrm(char* s1, const char* s2, size_t n);
3535
  const void* memchr(const void* s, int c, size_t n); // see [library.c]
3536
+ void* memchr(void* s, int c, size_t n); // see [library.c]
3537
+ const char* strchr(const char* s, int c); // see [library.c]
3538
+ char* strchr(char* s, int c); // see [library.c]
3539
  size_t strcspn(const char* s1, const char* s2);
3540
+ const char* strpbrk(const char* s1, const char* s2); // see [library.c]
3541
+ char* strpbrk(char* s1, const char* s2); // see [library.c]
3542
+ const char* strrchr(const char* s, int c); // see [library.c]
3543
+ char* strrchr(char* s, int c); // see [library.c]
3544
  size_t strspn(const char* s1, const char* s2);
3545
+ const char* strstr(const char* s1, const char* s2); // see [library.c]
3546
+ char* strstr(char* s1, const char* s2); // see [library.c]
3547
  char* strtok(char* s1, const char* s2);
3548
  void* memset(void* s, int c, size_t n);
3549
  char* strerror(int errnum);
3550
  size_t strlen(const char* s);
3551
  }
 
3555
 
3556
  The contents and meaning of the header `<cstring>` are the same as the C
3557
  standard library header `<string.h>`.
3558
 
3559
  The functions `strerror` and `strtok` are not required to avoid data
3560
+ races [[res.on.data.races]].
3561
 
3562
+ The functions `memcpy` and `memmove` are signal-safe [[support.signal]].
3563
+ Both functions implicitly create objects [[intro.object]] in the
3564
+ destination region of storage immediately prior to copying the sequence
3565
+ of characters to the destination.
3566
 
3567
  [*Note 1*: The functions `strchr`, `strpbrk`, `strrchr`, `strstr`, and
3568
+ `memchr`, have different signatures in this document, but they have the
3569
+ same behavior as in the C standard library [[library.c]]. — *end note*]
 
3570
 
3571
+ See also: ISO C 7.24
3572
 
3573
  ### Header `<cwchar>` synopsis <a id="cwchar.syn">[[cwchar.syn]]</a>
3574
 
3575
  ``` cpp
3576
  namespace std {
 
3618
  int wcscmp(const wchar_t* s1, const wchar_t* s2);
3619
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
3620
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3621
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
3622
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);
3623
+ const wchar_t* wcschr(const wchar_t* s, wchar_t c); // see [library.c]
3624
+ wchar_t* wcschr(wchar_t* s, wchar_t c); // see [library.c]
3625
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);
3626
+ const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2); // see [library.c]
3627
+ wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2); // see [library.c]
3628
+ const wchar_t* wcsrchr(const wchar_t* s, wchar_t c); // see [library.c]
3629
+ wchar_t* wcsrchr(wchar_t* s, wchar_t c); // see [library.c]
3630
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);
3631
+ const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2); // see [library.c]
3632
+ wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2); // see [library.c]
3633
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr);
3634
+ const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n); // see [library.c]
3635
+ wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n); // see [library.c]
3636
  size_t wcslen(const wchar_t* s);
3637
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);
3638
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const struct tm* timeptr);
3639
  wint_t btowc(int c);
3640
  int wctob(wint_t c);
 
3657
  The contents and meaning of the header `<cwchar>` are the same as the C
3658
  standard library header `<wchar.h>`, except that it does not declare a
3659
  type `wchar_t`.
3660
 
3661
  [*Note 1*: The functions `wcschr`, `wcspbrk`, `wcsrchr`, `wcsstr`, and
3662
+ `wmemchr` have different signatures in this document, but they have the
3663
+ same behavior as in the C standard library [[library.c]]. — *end note*]
 
3664
 
3665
+ See also: ISO C 7.29
3666
 
3667
  ### Header `<cuchar>` synopsis <a id="cuchar.syn">[[cuchar.syn]]</a>
3668
 
3669
  ``` cpp
3670
  namespace std {
3671
  using mbstate_t = see below;
3672
  using size_t = see [support.types.layout];
3673
 
3674
+ size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
3675
+ size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
3676
  size_t mbrtoc16(char16_t* pc16, const char* s, size_t n, mbstate_t* ps);
3677
  size_t c16rtomb(char* s, char16_t c16, mbstate_t* ps);
3678
  size_t mbrtoc32(char32_t* pc32, const char* s, size_t n, mbstate_t* ps);
3679
  size_t c32rtomb(char* s, char32_t c32, mbstate_t* ps);
3680
  }
3681
  ```
3682
 
3683
  The contents and meaning of the header `<cuchar>` are the same as the C
3684
+ standard library header `<uchar.h>`, except that it declares the
3685
+ additional `mbrtoc8` and `c8rtomb` functions and does not declare types
3686
+ `char16_t` nor `char32_t`.
3687
 
3688
+ See also: ISO C 7.28
3689
 
3690
  ### Multibyte / wide string and character conversion functions <a id="c.mb.wcs">[[c.mb.wcs]]</a>
3691
 
3692
+ [*Note 1*: The headers `<cstdlib>`, `<cuchar>`, and `<cwchar>` declare
3693
+ the functions described in this subclause. — *end note*]
 
3694
 
3695
  ``` cpp
3696
  int mbsinit(const mbstate_t* ps);
3697
  int mblen(const char* s, size_t n);
3698
  size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n);
 
3700
  ```
3701
 
3702
  *Effects:* These functions have the semantics specified in the C
3703
  standard library.
3704
 
3705
+ See also: ISO C 7.22.7.1, 7.22.8, 7.29.6.2.1
3706
 
3707
  ``` cpp
3708
  int mbtowc(wchar_t* pwc, const char* s, size_t n);
3709
  int wctomb(char* s, wchar_t wchar);
3710
  ```
3711
 
3712
  *Effects:* These functions have the semantics specified in the C
3713
  standard library.
3714
 
3715
  *Remarks:* Calls to these functions may introduce a data
3716
+ race [[res.on.data.races]] with other calls to the same function.
3717
 
3718
+ See also: ISO C 7.22.7
3719
 
3720
  ``` cpp
3721
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
3722
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
3723
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
 
3727
 
3728
  *Effects:* These functions have the semantics specified in the C
3729
  standard library.
3730
 
3731
  *Remarks:* Calling these functions with an `mbstate_t*` argument that is
3732
+ a null pointer value may introduce a data race [[res.on.data.races]]
3733
  with other calls to the same function with an `mbstate_t*` argument that
3734
  is a null pointer value.
3735
 
3736
+ See also: ISO C 7.29.6.3
3737
+
3738
+ ``` cpp
3739
+ size_t mbrtoc8(char8_t* pc8, const char* s, size_t n, mbstate_t* ps);
3740
+ ```
3741
+
3742
+ *Effects:* If `s` is a null pointer, equivalent to
3743
+ `mbrtoc8(nullptr, "", 1, ps)`. Otherwise, the function inspects at most
3744
+ `n` bytes beginning with the byte pointed to by `s` to determine the
3745
+ number of bytes needed to complete the next multibyte character
3746
+ (including any shift sequences). If the function determines that the
3747
+ next multibyte character is complete and valid, it determines the values
3748
+ of the corresponding UTF-8 code units and then, if `pc8` is not a null
3749
+ pointer, stores the value of the first (or only) such code unit in the
3750
+ object pointed to by `pc8`. Subsequent calls will store successive UTF-8
3751
+ code units without consuming any additional input until all the code
3752
+ units have been stored. If the corresponding Unicode character is
3753
+ U+0000, the resulting state described is the initial conversion state.
3754
+
3755
+ *Returns:* The first of the following that applies (given the current
3756
+ conversion state):
3757
+
3758
+ - `0`, if the next `n` or fewer bytes complete the multibyte character
3759
+ that corresponds to the U+0000 Unicode character (which is the value
3760
+ stored).
3761
+ - between `1` and `n` (inclusive), if the next n or fewer bytes complete
3762
+ a valid multibyte character (which is the value stored); the value
3763
+ returned is the number of bytes that complete the multibyte character.
3764
+ - `(size_t)(-3)`, if the next character resulting from a previous call
3765
+ has been stored (no bytes from the input have been consumed by this
3766
+ call).
3767
+ - `(size_t)(-2)`, if the next `n` bytes contribute to an incomplete (but
3768
+ potentially valid) multibyte character, and all `n` bytes have been
3769
+ processed (no value is stored).
3770
+ - `(size_t)(-1)`, if an encoding error occurs, in which case the next
3771
+ `n` or fewer bytes do not contribute to a complete and valid multibyte
3772
+ character (no value is stored); the value of the macro `EILSEQ` is
3773
+ stored in `errno`, and the conversion state is unspecified.
3774
+
3775
+ ``` cpp
3776
+ size_t c8rtomb(char* s, char8_t c8, mbstate_t* ps);
3777
+ ```
3778
+
3779
+ *Effects:* If `s` is a null pointer, equivalent to
3780
+ `c8rtomb(buf, u8’`\`0’, ps)` where `buf` is an internal buffer.
3781
+ Otherwise, if `c8` completes a sequence of valid UTF-8 code units,
3782
+ determines the number of bytes needed to represent the multibyte
3783
+ character (including any shift sequences), and stores the multibyte
3784
+ character representation in the array whose first element is pointed to
3785
+ by `s`. At most `MB_CUR_MAX` bytes are stored. If the multibyte
3786
+ character is a null character, a null byte is stored, preceded by any
3787
+ shift sequence needed to restore the initial shift state; the resulting
3788
+ state described is the initial conversion state.
3789
+
3790
+ *Returns:* The number of bytes stored in the array object (including any
3791
+ shift sequences). If `c8` does not contribute to a sequence of `char8_t`
3792
+ corresponding to a valid multibyte character, the value of the macro
3793
+ `EILSEQ` is stored in `errno`, `(size_t) (-1)` is returned, and the
3794
+ conversion state is unspecified.
3795
+
3796
+ *Remarks:* Calls to `c8rtomb` with a null pointer argument for `s` may
3797
+ introduce a data race [[res.on.data.races]] with other calls to
3798
+ `c8rtomb` with a null pointer argument for `s`.
3799
 
3800
  <!-- Link reference definitions -->
3801
  [basic.string]: #basic.string
3802
  [basic.string.hash]: #basic.string.hash
3803
  [basic.string.literals]: #basic.string.literals
3804
  [basic.types]: basic.md#basic.types
3805
  [c.mb.wcs]: #c.mb.wcs
3806
  [c.strings]: #c.strings
3807
  [cctype.syn]: #cctype.syn
3808
  [char.traits]: #char.traits
3809
+ [char.traits.req]: #char.traits.req
3810
  [char.traits.require]: #char.traits.require
3811
  [char.traits.specializations]: #char.traits.specializations
3812
  [char.traits.specializations.char]: #char.traits.specializations.char
3813
+ [char.traits.specializations.char16.t]: #char.traits.specializations.char16.t
3814
+ [char.traits.specializations.char32.t]: #char.traits.specializations.char32.t
3815
+ [char.traits.specializations.char8.t]: #char.traits.specializations.char8.t
3816
  [char.traits.specializations.wchar.t]: #char.traits.specializations.wchar.t
3817
  [char.traits.typedefs]: #char.traits.typedefs
3818
  [container.requirements]: containers.md#container.requirements
3819
  [container.requirements.general]: containers.md#container.requirements.general
3820
+ [container.seq.req]: containers.md#container.seq.req
3821
+ [cpp17.copyassignable]: #cpp17.copyassignable
3822
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
3823
+ [cpp17.defaultconstructible]: #cpp17.defaultconstructible
3824
+ [cpp17.destructible]: #cpp17.destructible
3825
  [cstring.syn]: #cstring.syn
3826
  [cuchar.syn]: #cuchar.syn
3827
  [cwchar.syn]: #cwchar.syn
3828
  [cwctype.syn]: #cwctype.syn
3829
+ [defns.character.container]: library.md#defns.character.container
3830
  [input.output]: input.md#input.output
3831
+ [intro.object]: basic.md#intro.object
3832
  [iostate.flags]: input.md#iostate.flags
3833
  [iostream.forward]: input.md#iostream.forward
3834
  [iostreams.limits.pos]: input.md#iostreams.limits.pos
3835
  [istream.formatted.reqmts]: input.md#istream.formatted.reqmts
3836
  [istream.unformatted]: input.md#istream.unformatted
3837
+ [iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
3838
  [iterator.range]: iterators.md#iterator.range
3839
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
 
3840
  [library.c]: library.md#library.c
3841
  [ostream.formatted.reqmts]: input.md#ostream.formatted.reqmts
 
3842
  [random.access.iterators]: iterators.md#random.access.iterators
3843
  [res.on.data.races]: library.md#res.on.data.races
 
3844
  [string.access]: #string.access
3845
  [string.accessors]: #string.accessors
3846
  [string.append]: #string.append
3847
  [string.assign]: #string.assign
3848
  [string.capacity]: #string.capacity
3849
  [string.classes]: #string.classes
3850
+ [string.cmp]: #string.cmp
3851
  [string.compare]: #string.compare
3852
  [string.cons]: #string.cons
3853
  [string.conversions]: #string.conversions
3854
  [string.copy]: #string.copy
3855
+ [string.ends.with]: #string.ends.with
3856
  [string.erase]: #string.erase
3857
+ [string.erasure]: #string.erasure
3858
  [string.find]: #string.find
 
 
 
 
3859
  [string.insert]: #string.insert
3860
  [string.io]: #string.io
3861
  [string.iterators]: #string.iterators
3862
  [string.modifiers]: #string.modifiers
3863
  [string.nonmembers]: #string.nonmembers
3864
+ [string.op.append]: #string.op.append
3865
+ [string.op.plus]: #string.op.plus
 
 
 
 
 
 
3866
  [string.ops]: #string.ops
3867
  [string.replace]: #string.replace
3868
  [string.require]: #string.require
 
3869
  [string.special]: #string.special
3870
+ [string.starts.with]: #string.starts.with
3871
  [string.substr]: #string.substr
3872
  [string.swap]: #string.swap
3873
  [string.syn]: #string.syn
3874
  [string.view]: #string.view
3875
  [string.view.access]: #string.view.access
3876
  [string.view.capacity]: #string.view.capacity
3877
+ [string.view.compare]: #string.view.compare
3878
  [string.view.comparison]: #string.view.comparison
3879
+ [string.view.comparison.overloads]: #string.view.comparison.overloads
3880
  [string.view.cons]: #string.view.cons
3881
+ [string.view.deduct]: #string.view.deduct
3882
  [string.view.find]: #string.view.find
3883
  [string.view.hash]: #string.view.hash
3884
  [string.view.io]: #string.view.io
3885
  [string.view.iterators]: #string.view.iterators
3886
  [string.view.literals]: #string.view.literals
 
3888
  [string.view.ops]: #string.view.ops
3889
  [string.view.synop]: #string.view.synop
3890
  [string.view.template]: #string.view.template
3891
  [strings]: #strings
3892
  [strings.general]: #strings.general
3893
+ [strings.summary]: #strings.summary
3894
+ [support.signal]: support.md#support.signal
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3895
  [unord.hash]: utilities.md#unord.hash
3896
  [utility.swap]: utilities.md#utility.swap
3897
 
3898
  [^1]: If `eof()` can be held in `char_type` then some iostreams
3899
+ operations can give surprising results.
3900
 
3901
+ [^2]: For example, as an argument to non-member functions `swap()`
3902
+ [[string.special]], `operator>{}>()` [[string.io]], and `getline()`
3903
+ [[string.io]], or as an argument to `basic_string::swap()`.