From Jason Turner

[string.classes]

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

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpzp958sev/{from.md → to.md} +249 -108
tmp/tmpzp958sev/{from.md → to.md} RENAMED
@@ -1,7 +1,9 @@
1
  ## String classes <a id="string.classes">[[string.classes]]</a>
2
 
 
 
3
  The header `<string>` defines the `basic_string` class template for
4
  manipulating varying-length sequences of char-like objects and five
5
  *typedef-name*s, `string`, `u8string`, `u16string`, `u32string`, and
6
  `wstring`, that name the specializations `basic_string<char>`,
7
  `basic_string<char8_t>`, `basic_string<char16_t>`,
@@ -131,11 +133,11 @@ namespace std {
131
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
132
  template<class charT, class traits, class Allocator, class Predicate>
133
  constexpr typename basic_string<charT, traits, Allocator>::size_type
134
  erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
135
 
136
- // basic_string typedef names
137
  using string = basic_string<char>;
138
  using u8string = basic_string<char8_t>;
139
  using u16string = basic_string<char16_t>;
140
  using u32string = basic_string<char32_t>;
141
  using wstring = basic_string<wchar_t>;
@@ -188,20 +190,15 @@ namespace std {
188
  using wstring = basic_string<wchar_t>;
189
  }
190
 
191
  // [basic.string.hash], hash support
192
  template<class T> struct hash;
193
- template<> struct hash<string>;
194
- template<> struct hash<u8string>;
195
- template<> struct hash<u16string>;
196
- template<> struct hash<u32string>;
197
- template<> struct hash<wstring>;
198
- template<> struct hash<pmr::string>;
199
- template<> struct hash<pmr::u8string>;
200
- template<> struct hash<pmr::u16string>;
201
- template<> struct hash<pmr::u32string>;
202
- template<> struct hash<pmr::wstring>;
203
 
204
  inline namespace literals {
205
  inline namespace string_literals {
206
  // [basic.string.literals], suffix for basic_string literals
207
  constexpr string operator""s(const char* str, size_t len);
@@ -214,20 +211,22 @@ namespace std {
214
  }
215
  ```
216
 
217
  ### Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
218
 
 
 
219
  The class template `basic_string` describes objects that can store a
220
  sequence consisting of a varying number of arbitrary char-like objects
221
  with the first element of the sequence at position zero. Such a sequence
222
  is also called a “string” if the type of the char-like objects that it
223
- holds is clear from context. In the rest of this Clause, the type of the
224
- char-like objects held in a `basic_string` object is designated by
225
- `charT`.
226
 
227
  A specialization of `basic_string` is a contiguous container
228
- [[container.requirements.general]].
229
 
230
  In all cases, \[`data()`, `data() + size()`\] is a valid range,
231
  `data() + size()` points at an object with value `charT()` (a “null
232
  terminator”), and `size() <= capacity()` is `true`.
233
 
@@ -250,32 +249,39 @@ namespace std {
250
 
251
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
252
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
253
  using reverse_iterator = std::reverse_iterator<iterator>;
254
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
255
- static const size_type npos = -1;
256
 
257
  // [string.cons], construct/copy/destroy
258
  constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
259
  constexpr explicit basic_string(const Allocator& a) noexcept;
260
  constexpr basic_string(const basic_string& str);
261
  constexpr basic_string(basic_string&& str) noexcept;
262
  constexpr basic_string(const basic_string& str, size_type pos,
263
  const Allocator& a = Allocator());
264
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
265
  const Allocator& a = Allocator());
 
 
 
 
266
  template<class T>
267
  constexpr basic_string(const T& t, size_type pos, size_type n,
268
  const Allocator& a = Allocator());
269
  template<class T>
270
  constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
271
  constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
272
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
 
273
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
274
  template<class InputIterator>
275
  constexpr basic_string(InputIterator begin, InputIterator end,
276
  const Allocator& a = Allocator());
 
 
277
  constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());
278
  constexpr basic_string(const basic_string&, const Allocator&);
279
  constexpr basic_string(basic_string&&, const Allocator&);
280
  constexpr ~basic_string();
281
 
@@ -284,10 +290,11 @@ namespace std {
284
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
285
  allocator_traits<Allocator>::is_always_equal::value);
286
  template<class T>
287
  constexpr basic_string& operator=(const T& t);
288
  constexpr basic_string& operator=(const charT* s);
 
289
  constexpr basic_string& operator=(charT c);
290
  constexpr basic_string& operator=(initializer_list<charT>);
291
 
292
  // [string.iterators], iterators
293
  constexpr iterator begin() noexcept;
@@ -309,10 +316,11 @@ namespace std {
309
  constexpr size_type size() const noexcept;
310
  constexpr size_type length() const noexcept;
311
  constexpr size_type max_size() const noexcept;
312
  constexpr void resize(size_type n, charT c);
313
  constexpr void resize(size_type n);
 
314
  constexpr size_type capacity() const noexcept;
315
  constexpr void reserve(size_type res_arg);
316
  constexpr void shrink_to_fit();
317
  constexpr void clear() noexcept;
318
  [[nodiscard]] constexpr bool empty() const noexcept;
@@ -344,10 +352,12 @@ namespace std {
344
  constexpr basic_string& append(const charT* s, size_type n);
345
  constexpr basic_string& append(const charT* s);
346
  constexpr basic_string& append(size_type n, charT c);
347
  template<class InputIterator>
348
  constexpr basic_string& append(InputIterator first, InputIterator last);
 
 
349
  constexpr basic_string& append(initializer_list<charT>);
350
 
351
  constexpr void push_back(charT c);
352
 
353
  constexpr basic_string& assign(const basic_string& str);
@@ -362,10 +372,12 @@ namespace std {
362
  constexpr basic_string& assign(const charT* s, size_type n);
363
  constexpr basic_string& assign(const charT* s);
364
  constexpr basic_string& assign(size_type n, charT c);
365
  template<class InputIterator>
366
  constexpr basic_string& assign(InputIterator first, InputIterator last);
 
 
367
  constexpr basic_string& assign(initializer_list<charT>);
368
 
369
  constexpr basic_string& insert(size_type pos, const basic_string& str);
370
  constexpr basic_string& insert(size_type pos1, const basic_string& str,
371
  size_type pos2, size_type n = npos);
@@ -379,10 +391,12 @@ namespace std {
379
  constexpr basic_string& insert(size_type pos, size_type n, charT c);
380
  constexpr iterator insert(const_iterator p, charT c);
381
  constexpr iterator insert(const_iterator p, size_type n, charT c);
382
  template<class InputIterator>
383
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
 
 
384
  constexpr iterator insert(const_iterator p, initializer_list<charT>);
385
 
386
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
387
  constexpr iterator erase(const_iterator p);
388
  constexpr iterator erase(const_iterator first, const_iterator last);
@@ -409,10 +423,12 @@ namespace std {
409
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
410
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
411
  template<class InputIterator>
412
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
413
  InputIterator j1, InputIterator j2);
 
 
414
  constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
415
 
416
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
417
 
418
  constexpr void swap(basic_string& str)
@@ -469,11 +485,12 @@ namespace std {
469
  size_type pos = npos) const noexcept;
470
  constexpr size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
471
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
472
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
473
 
474
- constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
 
475
 
476
  template<class T>
477
  constexpr int compare(const T& t) const noexcept(see below);
478
  template<class T>
479
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -492,19 +509,29 @@ namespace std {
492
  constexpr bool starts_with(charT x) const noexcept;
493
  constexpr bool starts_with(const charT* x) const;
494
  constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
495
  constexpr bool ends_with(charT x) const noexcept;
496
  constexpr bool ends_with(const charT* x) const;
 
 
 
 
497
  };
498
 
499
  template<class InputIterator,
500
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
501
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
502
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
503
  char_traits<typename iterator_traits<InputIterator>::value_type>,
504
  Allocator>;
505
 
 
 
 
 
 
 
506
  template<class charT,
507
  class traits,
508
  class Allocator = allocator<charT>>
509
  explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
510
  -> basic_string<charT, traits, Allocator>;
@@ -521,10 +548,13 @@ namespace std {
521
 
522
  A `size_type` parameter type in a `basic_string` deduction guide refers
523
  to the `size_type` member type of the type deduced by the deduction
524
  guide.
525
 
 
 
 
526
  #### General requirements <a id="string.require">[[string.require]]</a>
527
 
528
  If any operation would cause `size()` to exceed `max_size()`, that
529
  operation throws an exception object of type `length_error`.
530
 
@@ -540,19 +570,24 @@ as `charT`. Every object of type
540
  objects as needed. The `Allocator` object used is obtained as described
541
  in [[container.requirements.general]]. In every specialization
542
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
543
  the character traits requirements [[char.traits]].
544
 
545
- [*Note 1*: The program is ill-formed if `traits::char_type` is not the
 
 
 
 
 
546
  same type as `charT`. — *end note*]
547
 
548
  References, pointers, and iterators referring to the elements of a
549
  `basic_string` sequence may be invalidated by the following uses of that
550
  `basic_string` object:
551
 
552
  - Passing as an argument to any standard library function taking a
553
- reference to non-const `basic_string` as an argument.[^2]
554
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
555
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
556
 
557
  #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
558
 
@@ -576,17 +611,33 @@ state.
576
  ``` cpp
577
  constexpr basic_string(const basic_string& str, size_type pos,
578
  const Allocator& a = Allocator());
579
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
580
  const Allocator& a = Allocator());
 
 
 
 
581
  ```
582
 
583
- *Effects:* Let `n` be `npos` for the first overload. Equivalent to:
584
 
585
- ``` cpp
586
- basic_string(basic_string_view<charT, traits>(str).substr(pos, n), a)
587
- ```
 
 
 
 
 
 
 
 
 
 
 
 
588
 
589
  ``` cpp
590
  template<class T>
591
  constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
592
  ```
@@ -661,11 +712,19 @@ template<class InputIterator>
661
 
662
  *Constraints:* `InputIterator` is a type that qualifies as an input
663
  iterator [[container.requirements.general]].
664
 
665
  *Effects:* Constructs a string from the values in the range \[`begin`,
666
- `end`), as indicated in [[container.seq.req]].
 
 
 
 
 
 
 
 
667
 
668
  ``` cpp
669
  constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
670
  ```
671
 
@@ -851,10 +910,45 @@ constexpr void resize(size_type n, charT c);
851
  constexpr void resize(size_type n);
852
  ```
853
 
854
  *Effects:* Equivalent to `resize(n, charT())`.
855
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
856
  ``` cpp
857
  constexpr size_type capacity() const noexcept;
858
  ```
859
 
860
  *Returns:* The size of the allocated storage in the string.
@@ -931,14 +1025,14 @@ undefined behavior.
931
  ``` cpp
932
  constexpr const_reference at(size_type pos) const;
933
  constexpr reference at(size_type pos);
934
  ```
935
 
936
- *Throws:* `out_of_range` if `pos >= size()`.
937
-
938
  *Returns:* `operator[](pos)`.
939
 
 
 
940
  ``` cpp
941
  constexpr const charT& front() const;
942
  constexpr charT& front();
943
  ```
944
 
@@ -1088,10 +1182,18 @@ template<class InputIterator>
1088
  iterator [[container.requirements.general]].
1089
 
1090
  *Effects:* Equivalent to:
1091
  `return append(basic_string(first, last, get_allocator()));`
1092
 
 
 
 
 
 
 
 
 
1093
  ``` cpp
1094
  constexpr basic_string& append(initializer_list<charT> il);
1095
  ```
1096
 
1097
  *Effects:* Equivalent to: `return append(il.begin(), il.size());`
@@ -1208,10 +1310,18 @@ template<class InputIterator>
1208
  iterator [[container.requirements.general]].
1209
 
1210
  *Effects:* Equivalent to:
1211
  `return assign(basic_string(first, last, get_allocator()));`
1212
 
 
 
 
 
 
 
 
 
1213
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1214
 
1215
  ``` cpp
1216
  constexpr basic_string& insert(size_type pos, const basic_string& str);
1217
  ```
@@ -1270,22 +1380,22 @@ return insert(pos1, sv.substr(pos2, n));
1270
  constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
1271
  ```
1272
 
1273
  *Preconditions:* \[`s`, `s + n`) is a valid range.
1274
 
1275
- *Throws:*
1276
-
1277
- - `out_of_range` if `pos > size()`,
1278
- - `length_error` if `n > max_size() - size()`, or
1279
- - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1280
-
1281
  *Effects:* Inserts a copy of the range \[`s`, `s + n`) immediately
1282
  before the character at position `pos` if `pos < size()`, or otherwise
1283
  at the end of the string.
1284
 
1285
  *Returns:* `*this`.
1286
 
 
 
 
 
 
 
1287
  ``` cpp
1288
  constexpr basic_string& insert(size_type pos, const charT* s);
1289
  ```
1290
 
1291
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
@@ -1340,10 +1450,23 @@ iterator [[container.requirements.general]].
1340
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1341
 
1342
  *Returns:* An iterator which refers to the first inserted character, or
1343
  `p` if `first == last`.
1344
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1345
  ``` cpp
1346
  constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1347
  ```
1348
 
1349
  *Effects:* Equivalent to: `return insert(p, il.begin(), il.end());`
@@ -1352,57 +1475,57 @@ constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1352
 
1353
  ``` cpp
1354
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1355
  ```
1356
 
1357
- *Throws:* `out_of_range` if `pos` `> size()`.
1358
-
1359
  *Effects:* Determines the effective length `xlen` of the string to be
1360
  removed as the smaller of `n` and `size() - pos`. Removes the characters
1361
  in the range \[`begin() + pos`, `begin() + pos + xlen`).
1362
 
1363
  *Returns:* `*this`.
1364
 
 
 
1365
  ``` cpp
1366
  constexpr iterator erase(const_iterator p);
1367
  ```
1368
 
1369
  *Preconditions:* `p` is a valid dereferenceable iterator on `*this`.
1370
 
1371
- *Throws:* Nothing.
1372
-
1373
  *Effects:* Removes the character referred to by `p`.
1374
 
1375
  *Returns:* An iterator which points to the element immediately following
1376
  `p` prior to the element being erased. If no such element exists,
1377
  `end()` is returned.
1378
 
 
 
1379
  ``` cpp
1380
  constexpr iterator erase(const_iterator first, const_iterator last);
1381
  ```
1382
 
1383
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
1384
  \[`first`, `last`) is a valid range.
1385
 
1386
- *Throws:* Nothing.
1387
-
1388
  *Effects:* Removes the characters in the range `[first, last)`.
1389
 
1390
  *Returns:* An iterator which points to the element pointed to by `last`
1391
  prior to the other elements being erased. If no such element exists,
1392
  `end()` is returned.
1393
 
 
 
1394
  ``` cpp
1395
  constexpr void pop_back();
1396
  ```
1397
 
1398
  *Preconditions:* `!empty()`.
1399
 
1400
- *Throws:* Nothing.
1401
-
1402
  *Effects:* Equivalent to `erase(end() - 1)`.
1403
 
 
 
1404
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1405
 
1406
  ``` cpp
1407
  constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1408
  ```
@@ -1462,25 +1585,25 @@ return replace(pos1, n1, sv.substr(pos2, n2));
1462
  constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1463
  ```
1464
 
1465
  *Preconditions:* \[`s`, `s + n2`) is a valid range.
1466
 
1467
- *Throws:*
1468
-
1469
- - `out_of_range` if `pos1 > size()`,
1470
- - `length_error` if the length of the resulting string would exceed
1471
- `max_size()` (see below), or
1472
- - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1473
-
1474
  *Effects:* Determines the effective length `xlen` of the string to be
1475
  removed as the smaller of `n1` and `size() - pos1`. If
1476
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1477
  function replaces the characters in the range \[`begin() + pos1`,
1478
  `begin() + pos1 + xlen`) with a copy of the range \[`s`, `s + n2`).
1479
 
1480
  *Returns:* `*this`.
1481
 
 
 
 
 
 
 
 
1482
  ``` cpp
1483
  constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1484
  ```
1485
 
1486
  *Effects:* Equivalent to:
@@ -1488,25 +1611,25 @@ constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1488
 
1489
  ``` cpp
1490
  constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
1491
  ```
1492
 
1493
- *Throws:*
1494
-
1495
- - `out_of_range` if `pos1 > size()`,
1496
- - `length_error` if the length of the resulting string would exceed
1497
- `max_size()` (see below), or
1498
- - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
1499
-
1500
  *Effects:* Determines the effective length `xlen` of the string to be
1501
  removed as the smaller of `n1` and `size() - pos1`. If
1502
  `size() - xlen >=` `max_size() - n2` throws `length_error`. Otherwise,
1503
  the function replaces the characters in the range \[`begin() + pos1`,
1504
  `begin() + pos1 + xlen`) with `n2` copies of `c`.
1505
 
1506
  *Returns:* `*this`.
1507
 
 
 
 
 
 
 
 
1508
  ``` cpp
1509
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1510
  ```
1511
 
1512
  *Effects:* Equivalent to:
@@ -1564,10 +1687,21 @@ template<class InputIterator>
1564
  iterator [[container.requirements.general]].
1565
 
1566
  *Effects:* Equivalent to:
1567
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
1568
 
 
 
 
 
 
 
 
 
 
 
 
1569
  ``` cpp
1570
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
1571
  ```
1572
 
1573
  *Effects:* Equivalent to:
@@ -1710,25 +1844,27 @@ template<class T>
1710
  ``` cpp
1711
  basic_string_view<charT, traits> s = *this, sv = t;
1712
  return s.G(sv, pos);
1713
  ```
1714
 
1715
- *Remarks:* The expression inside `noexcept` is equivalent to
1716
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1717
 
1718
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
1719
 
1720
  ``` cpp
1721
- constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
1722
  ```
1723
 
1724
- *Throws:* `out_of_range` if `pos > size()`.
1725
 
1726
- *Effects:* Determines the effective length `rlen` of the string to copy
1727
- as the smaller of `n` and `size() - pos`.
 
1728
 
1729
- *Returns:* `basic_string(data()+pos, rlen)`.
 
1730
 
1731
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
1732
 
1733
  ``` cpp
1734
  template<class T>
@@ -1742,11 +1878,11 @@ template<class T>
1742
  - `is_convertible_v<const T&, const charT*>` is `false`.
1743
 
1744
  *Effects:* Equivalent to:
1745
  `return basic_string_view<charT, traits>(*this).compare(t);`
1746
 
1747
- *Remarks:* The expression inside `noexcept` is equivalent to
1748
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1749
 
1750
  ``` cpp
1751
  template<class T>
1752
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -1855,10 +1991,24 @@ constexpr bool ends_with(const charT* x) const;
1855
 
1856
  ``` cpp
1857
  return basic_string_view<charT, traits>(data(), size()).ends_with(x);
1858
  ```
1859
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1860
  ### Non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
1861
 
1862
  #### `operator+` <a id="string.op.plus">[[string.op.plus]]</a>
1863
 
1864
  ``` cpp
@@ -1912,11 +2062,11 @@ return std::move(lhs);
1912
 
1913
  except that both `lhs` and `rhs` are left in valid but unspecified
1914
  states.
1915
 
1916
  [*Note 1*: If `lhs` and `rhs` have equal allocators, the implementation
1917
- may move from either. — *end note*]
1918
 
1919
  ``` cpp
1920
  template<class charT, class traits, class Allocator>
1921
  constexpr basic_string<charT, traits, Allocator>
1922
  operator+(const basic_string<charT, traits, Allocator>& lhs,
@@ -1999,11 +2149,11 @@ template<class charT, class traits, class Allocator>
1999
  ``` cpp
2000
  lhs.push_back(rhs);
2001
  return std::move(lhs);
2002
  ```
2003
 
2004
- #### Non-member comparison functions <a id="string.cmp">[[string.cmp]]</a>
2005
 
2006
  ``` cpp
2007
  template<class charT, class traits, class Allocator>
2008
  constexpr bool
2009
  operator==(const basic_string<charT, traits, Allocator>& lhs,
@@ -2046,28 +2196,27 @@ template<class charT, class traits, class Allocator>
2046
  operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);
2047
  ```
2048
 
2049
  *Effects:* Behaves as a formatted input
2050
  function [[istream.formatted.reqmts]]. After constructing a `sentry`
2051
- object, if the sentry converts to `true`, calls `str.erase()` and then
2052
- extracts characters from `is` and appends them to `str` as if by calling
2053
- `str.append(1, c)`. If `is.width()` is greater than zero, the maximum
2054
- number `n` of characters appended is `is.width()`; otherwise `n` is
2055
- `str.max_size()`. Characters are extracted and appended until any of the
2056
- following occurs:
2057
 
2058
  - *n* characters are stored;
2059
  - end-of-file occurs on the input sequence;
2060
  - `isspace(c, is.getloc())` is `true` for the next available input
2061
  character *c*.
2062
 
2063
  After the last character (if any) is extracted, `is.width(0)` is called
2064
  and the `sentry` object is destroyed.
2065
 
2066
- If the function extracts no characters, it calls
2067
- `is.setstate(ios_base::failbit)`, which may throw `ios_base::failure`
2068
- [[iostate.flags]].
2069
 
2070
  *Returns:* `is`.
2071
 
2072
  ``` cpp
2073
  template<class charT, class traits, class Allocator>
@@ -2093,28 +2242,26 @@ template<class charT, class traits, class Allocator>
2093
  ```
2094
 
2095
  *Effects:* Behaves as an unformatted input
2096
  function [[istream.unformatted]], except that it does not affect the
2097
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2098
- constructing a `sentry` object, if the sentry converts to `true`, calls
2099
- `str.erase()` and then extracts characters from `is` and appends them to
2100
- `str` as if by calling `str.append(1, c)` until any of the following
2101
- occurs:
2102
 
2103
- - end-of-file occurs on the input sequence (in which case, the `getline`
2104
- function calls `is.setstate(ios_base::eofbit)`).
2105
  - `traits::eq(c, delim)` for the next available input character *c* (in
2106
- which case, *c* is extracted but not appended) [[iostate.flags]]
2107
- - `str.max_size()` characters are stored (in which case, the function
2108
- calls `is.setstate(ios_base::failbit))` [[iostate.flags]]
2109
 
2110
  The conditions are tested in the order shown. In any case, after the
2111
  last character is extracted, the `sentry` object is destroyed.
2112
 
2113
- If the function extracts no characters, it calls
2114
- `is.setstate(ios_base::failbit)` which may throw `ios_base::failure`
2115
- [[iostate.flags]].
2116
 
2117
  *Returns:* `is`.
2118
 
2119
  ``` cpp
2120
  template<class charT, class traits, class Allocator>
@@ -2176,17 +2323,17 @@ unsigned long long stoull(const string& str, size_t* idx = nullptr, int base = 1
2176
  `strtoul(str.c_str(), ptr, base)`, `strtoll(str.c_str(), ptr, base)`,
2177
  and `strtoull(str.c_str(), ptr, base)`, respectively. Each function
2178
  returns the converted result, if any. The argument `ptr` designates a
2179
  pointer to an object internal to the function that is used to determine
2180
  what to store at `*idx`. If the function does not throw an exception and
2181
- `idx != 0`, the function stores in `*idx` the index of the first
2182
  unconverted element of `str`.
2183
 
2184
  *Returns:* The converted result.
2185
 
2186
  *Throws:* `invalid_argument` if `strtol`, `strtoul`, `strtoll`, or
2187
- `strtoull` reports that no conversion could be performed. Throws
2188
  `out_of_range` if `strtol`, `strtoul`, `strtoll` or `strtoull` sets
2189
  `errno` to `ERANGE`, or if the converted value is outside the range of
2190
  representable values for the return type.
2191
 
2192
  ``` cpp
@@ -2198,20 +2345,19 @@ long double stold(const string& str, size_t* idx = nullptr);
2198
  *Effects:* These functions call `strtof(str.c_str(), ptr)`,
2199
  `strtod(str.c_str(), ptr)`, and `strtold(str.c_str(), ptr)`,
2200
  respectively. Each function returns the converted result, if any. The
2201
  argument `ptr` designates a pointer to an object internal to the
2202
  function that is used to determine what to store at `*idx`. If the
2203
- function does not throw an exception and `idx != 0`, the function stores
2204
- in `*idx` the index of the first unconverted element of `str`.
2205
 
2206
  *Returns:* The converted result.
2207
 
2208
  *Throws:* `invalid_argument` if `strtof`, `strtod`, or `strtold` reports
2209
- that no conversion could be performed. Throws `out_of_range` if
2210
- `strtof`, `strtod`, or `strtold` sets `errno` to `ERANGE` or if the
2211
- converted value is outside the range of representable values for the
2212
- return type.
2213
 
2214
  ``` cpp
2215
  string to_string(int val);
2216
  string to_string(unsigned val);
2217
  string to_string(long val);
@@ -2243,17 +2389,17 @@ unsigned long long stoull(const wstring& str, size_t* idx = nullptr, int base =
2243
  `wcstoul(str.c_str(), ptr, base)`, `wcstoll(str.c_str(), ptr, base)`,
2244
  and `wcstoull(str.c_str(), ptr, base)`, respectively. Each function
2245
  returns the converted result, if any. The argument `ptr` designates a
2246
  pointer to an object internal to the function that is used to determine
2247
  what to store at `*idx`. If the function does not throw an exception and
2248
- `idx != 0`, the function stores in `*idx` the index of the first
2249
  unconverted element of `str`.
2250
 
2251
  *Returns:* The converted result.
2252
 
2253
  *Throws:* `invalid_argument` if `wcstol`, `wcstoul`, `wcstoll`, or
2254
- `wcstoull` reports that no conversion could be performed. Throws
2255
  `out_of_range` if the converted value is outside the range of
2256
  representable values for the return type.
2257
 
2258
  ``` cpp
2259
  float stof(const wstring& str, size_t* idx = nullptr);
@@ -2264,18 +2410,18 @@ long double stold(const wstring& str, size_t* idx = nullptr);
2264
  *Effects:* These functions call `wcstof(str.c_str(), ptr)`,
2265
  `wcstod(str.c_str(), ptr)`, and `wcstold(str.c_str(), ptr)`,
2266
  respectively. Each function returns the converted result, if any. The
2267
  argument `ptr` designates a pointer to an object internal to the
2268
  function that is used to determine what to store at `*idx`. If the
2269
- function does not throw an exception and `idx != 0`, the function stores
2270
- in `*idx` the index of the first unconverted element of `str`.
2271
 
2272
  *Returns:* The converted result.
2273
 
2274
  *Throws:* `invalid_argument` if `wcstof`, `wcstod`, or `wcstold` reports
2275
- that no conversion could be performed. Throws `out_of_range` if
2276
- `wcstof`, `wcstod`, or `wcstold` sets `errno` to `ERANGE`.
2277
 
2278
  ``` cpp
2279
  wstring to_wstring(int val);
2280
  wstring to_wstring(unsigned val);
2281
  wstring to_wstring(long val);
@@ -2295,20 +2441,15 @@ specifier of `L"%d"`, `L"%u"`, `L"%ld"`, `L"%lu"`, `L"%lld"`, `L"%llu"`,
2295
  internal character buffer of sufficient size `buffsz`.
2296
 
2297
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2298
 
2299
  ``` cpp
2300
- template<> struct hash<string>;
2301
- template<> struct hash<u8string>;
2302
- template<> struct hash<u16string>;
2303
- template<> struct hash<u32string>;
2304
- template<> struct hash<wstring>;
2305
- template<> struct hash<pmr::string>;
2306
- template<> struct hash<pmr::u8string>;
2307
- template<> struct hash<pmr::u16string>;
2308
- template<> struct hash<pmr::u32string>;
2309
- template<> struct hash<pmr::wstring>;
2310
  ```
2311
 
2312
  If `S` is one of these string types, `SV` is the corresponding string
2313
  view type, and `s` is an object of type `S`, then
2314
  `hash<S>()(s) == hash<SV>()(SV(s))`.
 
1
  ## String classes <a id="string.classes">[[string.classes]]</a>
2
 
3
+ ### General <a id="string.classes.general">[[string.classes.general]]</a>
4
+
5
  The header `<string>` defines the `basic_string` class template for
6
  manipulating varying-length sequences of char-like objects and five
7
  *typedef-name*s, `string`, `u8string`, `u16string`, `u32string`, and
8
  `wstring`, that name the specializations `basic_string<char>`,
9
  `basic_string<char8_t>`, `basic_string<char16_t>`,
 
133
  erase(basic_string<charT, traits, Allocator>& c, const U& value);
134
  template<class charT, class traits, class Allocator, class Predicate>
135
  constexpr typename basic_string<charT, traits, Allocator>::size_type
136
  erase_if(basic_string<charT, traits, Allocator>& c, Predicate pred);
137
 
138
+ // basic_string typedef-names
139
  using string = basic_string<char>;
140
  using u8string = basic_string<char8_t>;
141
  using u16string = basic_string<char16_t>;
142
  using u32string = basic_string<char32_t>;
143
  using wstring = basic_string<wchar_t>;
 
190
  using wstring = basic_string<wchar_t>;
191
  }
192
 
193
  // [basic.string.hash], hash support
194
  template<class T> struct hash;
195
+ template<class A> struct hash<basic_string<char, char_traits<char>, A>>;
196
+ template<class A> struct hash<basic_string<char8_t, char_traits<char8_t>, A>>;
197
+ template<class A> struct hash<basic_string<char16_t, char_traits<char16_t>, A>>;
198
+ template<class A> struct hash<basic_string<char32_t, char_traits<char32_t>, A>>;
199
+ template<class A> struct hash<basic_string<wchar_t, char_traits<wchar_t>, A>>;
 
 
 
 
 
200
 
201
  inline namespace literals {
202
  inline namespace string_literals {
203
  // [basic.string.literals], suffix for basic_string literals
204
  constexpr string operator""s(const char* str, size_t len);
 
211
  }
212
  ```
213
 
214
  ### Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
215
 
216
+ #### General <a id="basic.string.general">[[basic.string.general]]</a>
217
+
218
  The class template `basic_string` describes objects that can store a
219
  sequence consisting of a varying number of arbitrary char-like objects
220
  with the first element of the sequence at position zero. Such a sequence
221
  is also called a “string” if the type of the char-like objects that it
222
+ holds is clear from context. In the rest of [[basic.string]], the type
223
+ of the char-like objects held in a `basic_string` object is designated
224
+ by `charT`.
225
 
226
  A specialization of `basic_string` is a contiguous container
227
+ [[container.reqmts]].
228
 
229
  In all cases, \[`data()`, `data() + size()`\] is a valid range,
230
  `data() + size()` points at an object with value `charT()` (a “null
231
  terminator”), and `size() <= capacity()` is `true`.
232
 
 
249
 
250
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
251
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
252
  using reverse_iterator = std::reverse_iterator<iterator>;
253
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
254
+ static constexpr size_type npos = size_type(-1);
255
 
256
  // [string.cons], construct/copy/destroy
257
  constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
258
  constexpr explicit basic_string(const Allocator& a) noexcept;
259
  constexpr basic_string(const basic_string& str);
260
  constexpr basic_string(basic_string&& str) noexcept;
261
  constexpr basic_string(const basic_string& str, size_type pos,
262
  const Allocator& a = Allocator());
263
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
264
  const Allocator& a = Allocator());
265
+ constexpr basic_string(basic_string&& str, size_type pos,
266
+ const Allocator& a = Allocator());
267
+ constexpr basic_string(basic_string&& str, size_type pos, size_type n,
268
+ const Allocator& a = Allocator());
269
  template<class T>
270
  constexpr basic_string(const T& t, size_type pos, size_type n,
271
  const Allocator& a = Allocator());
272
  template<class T>
273
  constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
274
  constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
275
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
276
+ basic_string(nullptr_t) = delete;
277
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
278
  template<class InputIterator>
279
  constexpr basic_string(InputIterator begin, InputIterator end,
280
  const Allocator& a = Allocator());
281
+ template<container-compatible-range<charT> R>
282
+ constexpr basic_string(from_range_t, R&& rg, const Allocator& a = Allocator());
283
  constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());
284
  constexpr basic_string(const basic_string&, const Allocator&);
285
  constexpr basic_string(basic_string&&, const Allocator&);
286
  constexpr ~basic_string();
287
 
 
290
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
291
  allocator_traits<Allocator>::is_always_equal::value);
292
  template<class T>
293
  constexpr basic_string& operator=(const T& t);
294
  constexpr basic_string& operator=(const charT* s);
295
+ basic_string& operator=(nullptr_t) = delete;
296
  constexpr basic_string& operator=(charT c);
297
  constexpr basic_string& operator=(initializer_list<charT>);
298
 
299
  // [string.iterators], iterators
300
  constexpr iterator begin() noexcept;
 
316
  constexpr size_type size() const noexcept;
317
  constexpr size_type length() const noexcept;
318
  constexpr size_type max_size() const noexcept;
319
  constexpr void resize(size_type n, charT c);
320
  constexpr void resize(size_type n);
321
+ template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
322
  constexpr size_type capacity() const noexcept;
323
  constexpr void reserve(size_type res_arg);
324
  constexpr void shrink_to_fit();
325
  constexpr void clear() noexcept;
326
  [[nodiscard]] constexpr bool empty() const noexcept;
 
352
  constexpr basic_string& append(const charT* s, size_type n);
353
  constexpr basic_string& append(const charT* s);
354
  constexpr basic_string& append(size_type n, charT c);
355
  template<class InputIterator>
356
  constexpr basic_string& append(InputIterator first, InputIterator last);
357
+ template<container-compatible-range<charT> R>
358
+ constexpr basic_string& append_range(R&& rg);
359
  constexpr basic_string& append(initializer_list<charT>);
360
 
361
  constexpr void push_back(charT c);
362
 
363
  constexpr basic_string& assign(const basic_string& str);
 
372
  constexpr basic_string& assign(const charT* s, size_type n);
373
  constexpr basic_string& assign(const charT* s);
374
  constexpr basic_string& assign(size_type n, charT c);
375
  template<class InputIterator>
376
  constexpr basic_string& assign(InputIterator first, InputIterator last);
377
+ template<container-compatible-range<charT> R>
378
+ constexpr basic_string& assign_range(R&& rg);
379
  constexpr basic_string& assign(initializer_list<charT>);
380
 
381
  constexpr basic_string& insert(size_type pos, const basic_string& str);
382
  constexpr basic_string& insert(size_type pos1, const basic_string& str,
383
  size_type pos2, size_type n = npos);
 
391
  constexpr basic_string& insert(size_type pos, size_type n, charT c);
392
  constexpr iterator insert(const_iterator p, charT c);
393
  constexpr iterator insert(const_iterator p, size_type n, charT c);
394
  template<class InputIterator>
395
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
396
+ template<container-compatible-range<charT> R>
397
+ constexpr iterator insert_range(const_iterator p, R&& rg);
398
  constexpr iterator insert(const_iterator p, initializer_list<charT>);
399
 
400
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
401
  constexpr iterator erase(const_iterator p);
402
  constexpr iterator erase(const_iterator first, const_iterator last);
 
423
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
424
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
425
  template<class InputIterator>
426
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
427
  InputIterator j1, InputIterator j2);
428
+ template<container-compatible-range<charT> R>
429
+ constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);
430
  constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
431
 
432
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
433
 
434
  constexpr void swap(basic_string& str)
 
485
  size_type pos = npos) const noexcept;
486
  constexpr size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
487
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
488
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
489
 
490
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
491
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
492
 
493
  template<class T>
494
  constexpr int compare(const T& t) const noexcept(see below);
495
  template<class T>
496
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 
509
  constexpr bool starts_with(charT x) const noexcept;
510
  constexpr bool starts_with(const charT* x) const;
511
  constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
512
  constexpr bool ends_with(charT x) const noexcept;
513
  constexpr bool ends_with(const charT* x) const;
514
+
515
+ constexpr bool contains(basic_string_view<charT, traits> x) const noexcept;
516
+ constexpr bool contains(charT x) const noexcept;
517
+ constexpr bool contains(const charT* x) const;
518
  };
519
 
520
  template<class InputIterator,
521
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
522
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
523
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
524
  char_traits<typename iterator_traits<InputIterator>::value_type>,
525
  Allocator>;
526
 
527
+ template<ranges::input_range R,
528
+ class Allocator = allocator<ranges::range_value_t<R>>>
529
+ basic_string(from_range_t, R&&, Allocator = Allocator())
530
+ -> basic_string<ranges::range_value_t<R>, char_traits<ranges::range_value_t<R>>,
531
+ Allocator>;
532
+
533
  template<class charT,
534
  class traits,
535
  class Allocator = allocator<charT>>
536
  explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
537
  -> basic_string<charT, traits, Allocator>;
 
548
 
549
  A `size_type` parameter type in a `basic_string` deduction guide refers
550
  to the `size_type` member type of the type deduced by the deduction
551
  guide.
552
 
553
+ The types `iterator` and `const_iterator` meet the constexpr iterator
554
+ requirements [[iterator.requirements.general]].
555
+
556
  #### General requirements <a id="string.require">[[string.require]]</a>
557
 
558
  If any operation would cause `size()` to exceed `max_size()`, that
559
  operation throws an exception object of type `length_error`.
560
 
 
570
  objects as needed. The `Allocator` object used is obtained as described
571
  in [[container.requirements.general]]. In every specialization
572
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
573
  the character traits requirements [[char.traits]].
574
 
575
+ [*Note 1*: Every specialization
576
+ `basic_string<charT, traits, Allocator>` is an allocator-aware
577
+ container, but does not use the allocator’s `construct` and `destroy`
578
+ member functions [[container.requirements.general]]. — *end note*]
579
+
580
+ [*Note 2*: The program is ill-formed if `traits::char_type` is not the
581
  same type as `charT`. — *end note*]
582
 
583
  References, pointers, and iterators referring to the elements of a
584
  `basic_string` sequence may be invalidated by the following uses of that
585
  `basic_string` object:
586
 
587
  - Passing as an argument to any standard library function taking a
588
+ reference to non-const `basic_string` as an argument.[^3]
589
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
590
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
591
 
592
  #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
593
 
 
611
  ``` cpp
612
  constexpr basic_string(const basic_string& str, size_type pos,
613
  const Allocator& a = Allocator());
614
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
615
  const Allocator& a = Allocator());
616
+ constexpr basic_string(basic_string&& str, size_type pos,
617
+ const Allocator& a = Allocator());
618
+ constexpr basic_string(basic_string&& str, size_type pos, size_type n,
619
+ const Allocator& a = Allocator());
620
  ```
621
 
622
+ Let
623
 
624
+ - `s` be the value of `str` prior to this call and
625
+ - `rlen` be `pos + min(n, s.size() - pos)` for the overloads with
626
+ parameter `n`, and `s.size()` otherwise.
627
+
628
+ *Effects:* Constructs an object whose initial value is the range
629
+ \[`s.data() + pos`, `s.data() + rlen`).
630
+
631
+ *Throws:* `out_of_range` if `pos > s.size()`.
632
+
633
+ *Remarks:* For the overloads with a `basic_string&&` parameter, `str` is
634
+ left in a valid but unspecified state.
635
+
636
+ *Recommended practice:* For the overloads with a `basic_string&&`
637
+ parameter, implementations should avoid allocation if
638
+ `s.get_allocator() == a` is `true`.
639
 
640
  ``` cpp
641
  template<class T>
642
  constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
643
  ```
 
712
 
713
  *Constraints:* `InputIterator` is a type that qualifies as an input
714
  iterator [[container.requirements.general]].
715
 
716
  *Effects:* Constructs a string from the values in the range \[`begin`,
717
+ `end`), as specified in [[sequence.reqmts]].
718
+
719
+ ``` cpp
720
+ template<container-compatible-range<charT> R>
721
+ constexpr basic_string(from_range_t, R&& rg, const Allocator& = Allocator());
722
+ ```
723
+
724
+ *Effects:* Constructs a string from the values in the range `rg`, as
725
+ specified in [[sequence.reqmts]].
726
 
727
  ``` cpp
728
  constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
729
  ```
730
 
 
910
  constexpr void resize(size_type n);
911
  ```
912
 
913
  *Effects:* Equivalent to `resize(n, charT())`.
914
 
915
+ ``` cpp
916
+ template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
917
+ ```
918
+
919
+ Let
920
+
921
+ - `o = size()` before the call to `resize_and_overwrite`.
922
+ - `k` be `min(o, n)`.
923
+ - `p` be a value of type `charT*` or `charT* const`, such that the range
924
+ \[`p`, `p + n`\] is valid and `this->compare(0, k, p, k) == 0` is
925
+ `true` before the call. The values in the range \[`p + k`, `p + n`\]
926
+ may be indeterminate [[basic.indet]].
927
+ - `m` be a value of type `size_type` or `const size_type` equal to `n`.
928
+ - *`OP`* be the expression `std::move(op)(p, m)`.
929
+ - `r` = *`OP`*.
930
+
931
+ *Mandates:* *`OP`* has an integer-like type [[iterator.concept.winc]].
932
+
933
+ *Preconditions:*
934
+
935
+ - *`OP`* does not throw an exception or modify `p` or `m`.
936
+ - `r` ≥ 0.
937
+ - `r` ≤ `m`.
938
+ - After evaluating *`OP`* there are no indeterminate values in the range
939
+ \[`p`, `p + r`).
940
+
941
+ *Effects:* Evaluates *`OP`*, replaces the contents of `*this` with
942
+ \[`p`, `p + r`), and invalidates all pointers and references to the
943
+ range \[`p`, `p + n`\].
944
+
945
+ *Recommended practice:* Implementations should avoid unnecessary copies
946
+ and allocations by, for example, making `p` a pointer into internal
947
+ storage and by restoring `*(p + r)` to `charT()` after evaluating
948
+ *`OP`*.
949
+
950
  ``` cpp
951
  constexpr size_type capacity() const noexcept;
952
  ```
953
 
954
  *Returns:* The size of the allocated storage in the string.
 
1025
  ``` cpp
1026
  constexpr const_reference at(size_type pos) const;
1027
  constexpr reference at(size_type pos);
1028
  ```
1029
 
 
 
1030
  *Returns:* `operator[](pos)`.
1031
 
1032
+ *Throws:* `out_of_range` if `pos >= size()`.
1033
+
1034
  ``` cpp
1035
  constexpr const charT& front() const;
1036
  constexpr charT& front();
1037
  ```
1038
 
 
1182
  iterator [[container.requirements.general]].
1183
 
1184
  *Effects:* Equivalent to:
1185
  `return append(basic_string(first, last, get_allocator()));`
1186
 
1187
+ ``` cpp
1188
+ template<container-compatible-range<charT> R>
1189
+ constexpr basic_string& append_range(R&& rg);
1190
+ ```
1191
+
1192
+ *Effects:* Equivalent to:
1193
+ `return append(basic_string(from_range, std::forward<R>(rg), get_allocator()));`
1194
+
1195
  ``` cpp
1196
  constexpr basic_string& append(initializer_list<charT> il);
1197
  ```
1198
 
1199
  *Effects:* Equivalent to: `return append(il.begin(), il.size());`
 
1310
  iterator [[container.requirements.general]].
1311
 
1312
  *Effects:* Equivalent to:
1313
  `return assign(basic_string(first, last, get_allocator()));`
1314
 
1315
+ ``` cpp
1316
+ template<container-compatible-range<charT> R>
1317
+ constexpr basic_string& assign_range(R&& rg);
1318
+ ```
1319
+
1320
+ *Effects:* Equivalent to:
1321
+ `return assign(basic_string(from_range, std::forward<R>(rg), get_allocator()));`
1322
+
1323
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1324
 
1325
  ``` cpp
1326
  constexpr basic_string& insert(size_type pos, const basic_string& str);
1327
  ```
 
1380
  constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
1381
  ```
1382
 
1383
  *Preconditions:* \[`s`, `s + n`) is a valid range.
1384
 
 
 
 
 
 
 
1385
  *Effects:* Inserts a copy of the range \[`s`, `s + n`) immediately
1386
  before the character at position `pos` if `pos < size()`, or otherwise
1387
  at the end of the string.
1388
 
1389
  *Returns:* `*this`.
1390
 
1391
+ *Throws:*
1392
+
1393
+ - `out_of_range` if `pos > size()`,
1394
+ - `length_error` if `n > max_size() - size()`, or
1395
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1396
+
1397
  ``` cpp
1398
  constexpr basic_string& insert(size_type pos, const charT* s);
1399
  ```
1400
 
1401
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
 
1450
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1451
 
1452
  *Returns:* An iterator which refers to the first inserted character, or
1453
  `p` if `first == last`.
1454
 
1455
+ ``` cpp
1456
+ template<container-compatible-range<charT> R>
1457
+ constexpr iterator insert_range(const_iterator p, R&& rg);
1458
+ ```
1459
+
1460
+ *Preconditions:* `p` is a valid iterator on `*this`.
1461
+
1462
+ *Effects:* Equivalent to
1463
+ `insert(p - begin(), basic_string(from_range, std::forward<R>(rg), get_allocator()))`.
1464
+
1465
+ *Returns:* An iterator which refers to the first inserted character, or
1466
+ `p` if `rg` is empty.
1467
+
1468
  ``` cpp
1469
  constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1470
  ```
1471
 
1472
  *Effects:* Equivalent to: `return insert(p, il.begin(), il.end());`
 
1475
 
1476
  ``` cpp
1477
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1478
  ```
1479
 
 
 
1480
  *Effects:* Determines the effective length `xlen` of the string to be
1481
  removed as the smaller of `n` and `size() - pos`. Removes the characters
1482
  in the range \[`begin() + pos`, `begin() + pos + xlen`).
1483
 
1484
  *Returns:* `*this`.
1485
 
1486
+ *Throws:* `out_of_range` if `pos` `> size()`.
1487
+
1488
  ``` cpp
1489
  constexpr iterator erase(const_iterator p);
1490
  ```
1491
 
1492
  *Preconditions:* `p` is a valid dereferenceable iterator on `*this`.
1493
 
 
 
1494
  *Effects:* Removes the character referred to by `p`.
1495
 
1496
  *Returns:* An iterator which points to the element immediately following
1497
  `p` prior to the element being erased. If no such element exists,
1498
  `end()` is returned.
1499
 
1500
+ *Throws:* Nothing.
1501
+
1502
  ``` cpp
1503
  constexpr iterator erase(const_iterator first, const_iterator last);
1504
  ```
1505
 
1506
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
1507
  \[`first`, `last`) is a valid range.
1508
 
 
 
1509
  *Effects:* Removes the characters in the range `[first, last)`.
1510
 
1511
  *Returns:* An iterator which points to the element pointed to by `last`
1512
  prior to the other elements being erased. If no such element exists,
1513
  `end()` is returned.
1514
 
1515
+ *Throws:* Nothing.
1516
+
1517
  ``` cpp
1518
  constexpr void pop_back();
1519
  ```
1520
 
1521
  *Preconditions:* `!empty()`.
1522
 
 
 
1523
  *Effects:* Equivalent to `erase(end() - 1)`.
1524
 
1525
+ *Throws:* Nothing.
1526
+
1527
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1528
 
1529
  ``` cpp
1530
  constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1531
  ```
 
1585
  constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1586
  ```
1587
 
1588
  *Preconditions:* \[`s`, `s + n2`) is a valid range.
1589
 
 
 
 
 
 
 
 
1590
  *Effects:* Determines the effective length `xlen` of the string to be
1591
  removed as the smaller of `n1` and `size() - pos1`. If
1592
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1593
  function replaces the characters in the range \[`begin() + pos1`,
1594
  `begin() + pos1 + xlen`) with a copy of the range \[`s`, `s + n2`).
1595
 
1596
  *Returns:* `*this`.
1597
 
1598
+ *Throws:*
1599
+
1600
+ - `out_of_range` if `pos1 > size()`,
1601
+ - `length_error` if the length of the resulting string would exceed
1602
+ `max_size()`, or
1603
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1604
+
1605
  ``` cpp
1606
  constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1607
  ```
1608
 
1609
  *Effects:* Equivalent to:
 
1611
 
1612
  ``` cpp
1613
  constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
1614
  ```
1615
 
 
 
 
 
 
 
 
1616
  *Effects:* Determines the effective length `xlen` of the string to be
1617
  removed as the smaller of `n1` and `size() - pos1`. If
1618
  `size() - xlen >=` `max_size() - n2` throws `length_error`. Otherwise,
1619
  the function replaces the characters in the range \[`begin() + pos1`,
1620
  `begin() + pos1 + xlen`) with `n2` copies of `c`.
1621
 
1622
  *Returns:* `*this`.
1623
 
1624
+ *Throws:*
1625
+
1626
+ - `out_of_range` if `pos1 > size()`,
1627
+ - `length_error` if the length of the resulting string would
1628
+ exceed`max_size()`, or
1629
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
1630
+
1631
  ``` cpp
1632
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1633
  ```
1634
 
1635
  *Effects:* Equivalent to:
 
1687
  iterator [[container.requirements.general]].
1688
 
1689
  *Effects:* Equivalent to:
1690
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
1691
 
1692
+ ``` cpp
1693
+ template<container-compatible-range<charT> R>
1694
+ constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);
1695
+ ```
1696
+
1697
+ *Effects:* Equivalent to:
1698
+
1699
+ ``` cpp
1700
+ return replace(i1, i2, basic_string(from_range, std::forward<R>(rg), get_allocator()));
1701
+ ```
1702
+
1703
  ``` cpp
1704
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
1705
  ```
1706
 
1707
  *Effects:* Equivalent to:
 
1844
  ``` cpp
1845
  basic_string_view<charT, traits> s = *this, sv = t;
1846
  return s.G(sv, pos);
1847
  ```
1848
 
1849
+ *Remarks:* The exception specification is equivalent to
1850
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1851
 
1852
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
1853
 
1854
  ``` cpp
1855
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
1856
  ```
1857
 
1858
+ *Effects:* Equivalent to: `return basic_string(*this, pos, n);`
1859
 
1860
+ ``` cpp
1861
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
1862
+ ```
1863
 
1864
+ *Effects:* Equivalent to:
1865
+ `return basic_string(std::move(*this), pos, n);`
1866
 
1867
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
1868
 
1869
  ``` cpp
1870
  template<class T>
 
1878
  - `is_convertible_v<const T&, const charT*>` is `false`.
1879
 
1880
  *Effects:* Equivalent to:
1881
  `return basic_string_view<charT, traits>(*this).compare(t);`
1882
 
1883
+ *Remarks:* The exception specification is equivalent to
1884
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1885
 
1886
  ``` cpp
1887
  template<class T>
1888
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 
1991
 
1992
  ``` cpp
1993
  return basic_string_view<charT, traits>(data(), size()).ends_with(x);
1994
  ```
1995
 
1996
+ ##### `basic_string::contains` <a id="string.contains">[[string.contains]]</a>
1997
+
1998
+ ``` cpp
1999
+ constexpr bool contains(basic_string_view<charT, traits> x) const noexcept;
2000
+ constexpr bool contains(charT x) const noexcept;
2001
+ constexpr bool contains(const charT* x) const;
2002
+ ```
2003
+
2004
+ *Effects:* Equivalent to:
2005
+
2006
+ ``` cpp
2007
+ return basic_string_view<charT, traits>(data(), size()).contains(x);
2008
+ ```
2009
+
2010
  ### Non-member functions <a id="string.nonmembers">[[string.nonmembers]]</a>
2011
 
2012
  #### `operator+` <a id="string.op.plus">[[string.op.plus]]</a>
2013
 
2014
  ``` cpp
 
2062
 
2063
  except that both `lhs` and `rhs` are left in valid but unspecified
2064
  states.
2065
 
2066
  [*Note 1*: If `lhs` and `rhs` have equal allocators, the implementation
2067
+ can move from either. — *end note*]
2068
 
2069
  ``` cpp
2070
  template<class charT, class traits, class Allocator>
2071
  constexpr basic_string<charT, traits, Allocator>
2072
  operator+(const basic_string<charT, traits, Allocator>& lhs,
 
2149
  ``` cpp
2150
  lhs.push_back(rhs);
2151
  return std::move(lhs);
2152
  ```
2153
 
2154
+ #### Non-member comparison operator functions <a id="string.cmp">[[string.cmp]]</a>
2155
 
2156
  ``` cpp
2157
  template<class charT, class traits, class Allocator>
2158
  constexpr bool
2159
  operator==(const basic_string<charT, traits, Allocator>& lhs,
 
2196
  operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Allocator>& str);
2197
  ```
2198
 
2199
  *Effects:* Behaves as a formatted input
2200
  function [[istream.formatted.reqmts]]. After constructing a `sentry`
2201
+ object, if the `sentry` object returns `true` when converted to a value
2202
+ of type `bool`, calls `str.erase()` and then extracts characters from
2203
+ `is` and appends them to `str` as if by calling `str.append(1, c)`. If
2204
+ `is.width()` is greater than zero, the maximum number `n` of characters
2205
+ appended is `is.width()`; otherwise `n` is `str.max_size()`. Characters
2206
+ are extracted and appended until any of the following occurs:
2207
 
2208
  - *n* characters are stored;
2209
  - end-of-file occurs on the input sequence;
2210
  - `isspace(c, is.getloc())` is `true` for the next available input
2211
  character *c*.
2212
 
2213
  After the last character (if any) is extracted, `is.width(0)` is called
2214
  and the `sentry` object is destroyed.
2215
 
2216
+ If the function extracts no characters, `ios_base::failbit` is set in
2217
+ the input function’s local error state before `setstate` is called.
 
2218
 
2219
  *Returns:* `is`.
2220
 
2221
  ``` cpp
2222
  template<class charT, class traits, class Allocator>
 
2242
  ```
2243
 
2244
  *Effects:* Behaves as an unformatted input
2245
  function [[istream.unformatted]], except that it does not affect the
2246
  value returned by subsequent calls to `basic_istream<>::gcount()`. After
2247
+ constructing a `sentry` object, if the `sentry` object returns `true`
2248
+ when converted to a value of type `bool`, calls `str.erase()` and then
2249
+ extracts characters from `is` and appends them to `str` as if by calling
2250
+ `str.append(1, c)` until any of the following occurs:
2251
 
2252
+ - end-of-file occurs on the input sequence;
 
2253
  - `traits::eq(c, delim)` for the next available input character *c* (in
2254
+ which case, *c* is extracted but not appended);
2255
+ - `str.max_size()` characters are stored (in which case,
2256
+ `ios_base::failbit` is set in the input function’s local error state).
2257
 
2258
  The conditions are tested in the order shown. In any case, after the
2259
  last character is extracted, the `sentry` object is destroyed.
2260
 
2261
+ If the function extracts no characters, `ios_base::failbit` is set in
2262
+ the input function’s local error state before `setstate` is called.
 
2263
 
2264
  *Returns:* `is`.
2265
 
2266
  ``` cpp
2267
  template<class charT, class traits, class Allocator>
 
2323
  `strtoul(str.c_str(), ptr, base)`, `strtoll(str.c_str(), ptr, base)`,
2324
  and `strtoull(str.c_str(), ptr, base)`, respectively. Each function
2325
  returns the converted result, if any. The argument `ptr` designates a
2326
  pointer to an object internal to the function that is used to determine
2327
  what to store at `*idx`. If the function does not throw an exception and
2328
+ `idx != nullptr`, the function stores in `*idx` the index of the first
2329
  unconverted element of `str`.
2330
 
2331
  *Returns:* The converted result.
2332
 
2333
  *Throws:* `invalid_argument` if `strtol`, `strtoul`, `strtoll`, or
2334
+ `strtoull` reports that no conversion can be performed. Throws
2335
  `out_of_range` if `strtol`, `strtoul`, `strtoll` or `strtoull` sets
2336
  `errno` to `ERANGE`, or if the converted value is outside the range of
2337
  representable values for the return type.
2338
 
2339
  ``` cpp
 
2345
  *Effects:* These functions call `strtof(str.c_str(), ptr)`,
2346
  `strtod(str.c_str(), ptr)`, and `strtold(str.c_str(), ptr)`,
2347
  respectively. Each function returns the converted result, if any. The
2348
  argument `ptr` designates a pointer to an object internal to the
2349
  function that is used to determine what to store at `*idx`. If the
2350
+ function does not throw an exception and `idx != nullptr`, the function
2351
+ stores in `*idx` the index of the first unconverted element of `str`.
2352
 
2353
  *Returns:* The converted result.
2354
 
2355
  *Throws:* `invalid_argument` if `strtof`, `strtod`, or `strtold` reports
2356
+ that no conversion can be performed. Throws `out_of_range` if `strtof`,
2357
+ `strtod`, or `strtold` sets `errno` to `ERANGE` or if the converted
2358
+ value is outside the range of representable values for the return type.
 
2359
 
2360
  ``` cpp
2361
  string to_string(int val);
2362
  string to_string(unsigned val);
2363
  string to_string(long val);
 
2389
  `wcstoul(str.c_str(), ptr, base)`, `wcstoll(str.c_str(), ptr, base)`,
2390
  and `wcstoull(str.c_str(), ptr, base)`, respectively. Each function
2391
  returns the converted result, if any. The argument `ptr` designates a
2392
  pointer to an object internal to the function that is used to determine
2393
  what to store at `*idx`. If the function does not throw an exception and
2394
+ `idx != nullptr`, the function stores in `*idx` the index of the first
2395
  unconverted element of `str`.
2396
 
2397
  *Returns:* The converted result.
2398
 
2399
  *Throws:* `invalid_argument` if `wcstol`, `wcstoul`, `wcstoll`, or
2400
+ `wcstoull` reports that no conversion can be performed. Throws
2401
  `out_of_range` if the converted value is outside the range of
2402
  representable values for the return type.
2403
 
2404
  ``` cpp
2405
  float stof(const wstring& str, size_t* idx = nullptr);
 
2410
  *Effects:* These functions call `wcstof(str.c_str(), ptr)`,
2411
  `wcstod(str.c_str(), ptr)`, and `wcstold(str.c_str(), ptr)`,
2412
  respectively. Each function returns the converted result, if any. The
2413
  argument `ptr` designates a pointer to an object internal to the
2414
  function that is used to determine what to store at `*idx`. If the
2415
+ function does not throw an exception and `idx != nullptr`, the function
2416
+ stores in `*idx` the index of the first unconverted element of `str`.
2417
 
2418
  *Returns:* The converted result.
2419
 
2420
  *Throws:* `invalid_argument` if `wcstof`, `wcstod`, or `wcstold` reports
2421
+ that no conversion can be performed. Throws `out_of_range` if `wcstof`,
2422
+ `wcstod`, or `wcstold` sets `errno` to `ERANGE`.
2423
 
2424
  ``` cpp
2425
  wstring to_wstring(int val);
2426
  wstring to_wstring(unsigned val);
2427
  wstring to_wstring(long val);
 
2441
  internal character buffer of sufficient size `buffsz`.
2442
 
2443
  ### Hash support <a id="basic.string.hash">[[basic.string.hash]]</a>
2444
 
2445
  ``` cpp
2446
+ template<class A> struct hash<basic_string<char, char_traits<char>, A>>;
2447
+ template<class A> struct hash<basic_string<char8_t, char_traits<char8_t>, A>>;
2448
+ template<class A> struct hash<basic_string<char16_t, char_traits<char16_t>, A>>;
2449
+ template<class A> struct hash<basic_string<char32_t, char_traits<char32_t>, A>>;
2450
+ template<class A> struct hash<basic_string<wchar_t, char_traits<wchar_t>, A>>;
 
 
 
 
 
2451
  ```
2452
 
2453
  If `S` is one of these string types, `SV` is the corresponding string
2454
  view type, and `s` is an object of type `S`, then
2455
  `hash<S>()(s) == hash<SV>()(SV(s))`.