From Jason Turner

[basic.string]

C++20 → C++23 25.1 KB 282 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/tmpe90dbd4a/{from.md → to.md} +203 -50
tmp/tmpe90dbd4a/{from.md → to.md} RENAMED
@@ -1,17 +1,19 @@
1
  ### Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
2
 
 
 
3
  The class template `basic_string` describes objects that can store a
4
  sequence consisting of a varying number of arbitrary char-like objects
5
  with the first element of the sequence at position zero. Such a sequence
6
  is also called a “string” if the type of the char-like objects that it
7
- holds is clear from context. In the rest of this Clause, the type of the
8
- char-like objects held in a `basic_string` object is designated by
9
- `charT`.
10
 
11
  A specialization of `basic_string` is a contiguous container
12
- [[container.requirements.general]].
13
 
14
  In all cases, \[`data()`, `data() + size()`\] is a valid range,
15
  `data() + size()` points at an object with value `charT()` (a “null
16
  terminator”), and `size() <= capacity()` is `true`.
17
 
@@ -34,32 +36,39 @@ namespace std {
34
 
35
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
36
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
37
  using reverse_iterator = std::reverse_iterator<iterator>;
38
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
39
- static const size_type npos = -1;
40
 
41
  // [string.cons], construct/copy/destroy
42
  constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
43
  constexpr explicit basic_string(const Allocator& a) noexcept;
44
  constexpr basic_string(const basic_string& str);
45
  constexpr basic_string(basic_string&& str) noexcept;
46
  constexpr basic_string(const basic_string& str, size_type pos,
47
  const Allocator& a = Allocator());
48
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
49
  const Allocator& a = Allocator());
 
 
 
 
50
  template<class T>
51
  constexpr basic_string(const T& t, size_type pos, size_type n,
52
  const Allocator& a = Allocator());
53
  template<class T>
54
  constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
55
  constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
56
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
 
57
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
58
  template<class InputIterator>
59
  constexpr basic_string(InputIterator begin, InputIterator end,
60
  const Allocator& a = Allocator());
 
 
61
  constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());
62
  constexpr basic_string(const basic_string&, const Allocator&);
63
  constexpr basic_string(basic_string&&, const Allocator&);
64
  constexpr ~basic_string();
65
 
@@ -68,10 +77,11 @@ namespace std {
68
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
69
  allocator_traits<Allocator>::is_always_equal::value);
70
  template<class T>
71
  constexpr basic_string& operator=(const T& t);
72
  constexpr basic_string& operator=(const charT* s);
 
73
  constexpr basic_string& operator=(charT c);
74
  constexpr basic_string& operator=(initializer_list<charT>);
75
 
76
  // [string.iterators], iterators
77
  constexpr iterator begin() noexcept;
@@ -93,10 +103,11 @@ namespace std {
93
  constexpr size_type size() const noexcept;
94
  constexpr size_type length() const noexcept;
95
  constexpr size_type max_size() const noexcept;
96
  constexpr void resize(size_type n, charT c);
97
  constexpr void resize(size_type n);
 
98
  constexpr size_type capacity() const noexcept;
99
  constexpr void reserve(size_type res_arg);
100
  constexpr void shrink_to_fit();
101
  constexpr void clear() noexcept;
102
  [[nodiscard]] constexpr bool empty() const noexcept;
@@ -128,10 +139,12 @@ namespace std {
128
  constexpr basic_string& append(const charT* s, size_type n);
129
  constexpr basic_string& append(const charT* s);
130
  constexpr basic_string& append(size_type n, charT c);
131
  template<class InputIterator>
132
  constexpr basic_string& append(InputIterator first, InputIterator last);
 
 
133
  constexpr basic_string& append(initializer_list<charT>);
134
 
135
  constexpr void push_back(charT c);
136
 
137
  constexpr basic_string& assign(const basic_string& str);
@@ -146,10 +159,12 @@ namespace std {
146
  constexpr basic_string& assign(const charT* s, size_type n);
147
  constexpr basic_string& assign(const charT* s);
148
  constexpr basic_string& assign(size_type n, charT c);
149
  template<class InputIterator>
150
  constexpr basic_string& assign(InputIterator first, InputIterator last);
 
 
151
  constexpr basic_string& assign(initializer_list<charT>);
152
 
153
  constexpr basic_string& insert(size_type pos, const basic_string& str);
154
  constexpr basic_string& insert(size_type pos1, const basic_string& str,
155
  size_type pos2, size_type n = npos);
@@ -163,10 +178,12 @@ namespace std {
163
  constexpr basic_string& insert(size_type pos, size_type n, charT c);
164
  constexpr iterator insert(const_iterator p, charT c);
165
  constexpr iterator insert(const_iterator p, size_type n, charT c);
166
  template<class InputIterator>
167
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
 
 
168
  constexpr iterator insert(const_iterator p, initializer_list<charT>);
169
 
170
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
171
  constexpr iterator erase(const_iterator p);
172
  constexpr iterator erase(const_iterator first, const_iterator last);
@@ -193,10 +210,12 @@ namespace std {
193
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
194
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
195
  template<class InputIterator>
196
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
197
  InputIterator j1, InputIterator j2);
 
 
198
  constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
199
 
200
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
201
 
202
  constexpr void swap(basic_string& str)
@@ -253,11 +272,12 @@ namespace std {
253
  size_type pos = npos) const noexcept;
254
  constexpr size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
255
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
256
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
257
 
258
- constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
 
259
 
260
  template<class T>
261
  constexpr int compare(const T& t) const noexcept(see below);
262
  template<class T>
263
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -276,19 +296,29 @@ namespace std {
276
  constexpr bool starts_with(charT x) const noexcept;
277
  constexpr bool starts_with(const charT* x) const;
278
  constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
279
  constexpr bool ends_with(charT x) const noexcept;
280
  constexpr bool ends_with(const charT* x) const;
 
 
 
 
281
  };
282
 
283
  template<class InputIterator,
284
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
285
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
286
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
287
  char_traits<typename iterator_traits<InputIterator>::value_type>,
288
  Allocator>;
289
 
 
 
 
 
 
 
290
  template<class charT,
291
  class traits,
292
  class Allocator = allocator<charT>>
293
  explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
294
  -> basic_string<charT, traits, Allocator>;
@@ -305,10 +335,13 @@ namespace std {
305
 
306
  A `size_type` parameter type in a `basic_string` deduction guide refers
307
  to the `size_type` member type of the type deduced by the deduction
308
  guide.
309
 
 
 
 
310
  #### General requirements <a id="string.require">[[string.require]]</a>
311
 
312
  If any operation would cause `size()` to exceed `max_size()`, that
313
  operation throws an exception object of type `length_error`.
314
 
@@ -324,19 +357,24 @@ as `charT`. Every object of type
324
  objects as needed. The `Allocator` object used is obtained as described
325
  in [[container.requirements.general]]. In every specialization
326
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
327
  the character traits requirements [[char.traits]].
328
 
329
- [*Note 1*: The program is ill-formed if `traits::char_type` is not the
 
 
 
 
 
330
  same type as `charT`. — *end note*]
331
 
332
  References, pointers, and iterators referring to the elements of a
333
  `basic_string` sequence may be invalidated by the following uses of that
334
  `basic_string` object:
335
 
336
  - Passing as an argument to any standard library function taking a
337
- reference to non-const `basic_string` as an argument.[^2]
338
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
339
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
340
 
341
  #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
342
 
@@ -360,17 +398,33 @@ state.
360
  ``` cpp
361
  constexpr basic_string(const basic_string& str, size_type pos,
362
  const Allocator& a = Allocator());
363
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
364
  const Allocator& a = Allocator());
 
 
 
 
365
  ```
366
 
367
- *Effects:* Let `n` be `npos` for the first overload. Equivalent to:
368
 
369
- ``` cpp
370
- basic_string(basic_string_view<charT, traits>(str).substr(pos, n), a)
371
- ```
 
 
 
 
 
 
 
 
 
 
 
 
372
 
373
  ``` cpp
374
  template<class T>
375
  constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
376
  ```
@@ -445,11 +499,19 @@ template<class InputIterator>
445
 
446
  *Constraints:* `InputIterator` is a type that qualifies as an input
447
  iterator [[container.requirements.general]].
448
 
449
  *Effects:* Constructs a string from the values in the range \[`begin`,
450
- `end`), as indicated in [[container.seq.req]].
 
 
 
 
 
 
 
 
451
 
452
  ``` cpp
453
  constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
454
  ```
455
 
@@ -635,10 +697,45 @@ constexpr void resize(size_type n, charT c);
635
  constexpr void resize(size_type n);
636
  ```
637
 
638
  *Effects:* Equivalent to `resize(n, charT())`.
639
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
640
  ``` cpp
641
  constexpr size_type capacity() const noexcept;
642
  ```
643
 
644
  *Returns:* The size of the allocated storage in the string.
@@ -715,14 +812,14 @@ undefined behavior.
715
  ``` cpp
716
  constexpr const_reference at(size_type pos) const;
717
  constexpr reference at(size_type pos);
718
  ```
719
 
720
- *Throws:* `out_of_range` if `pos >= size()`.
721
-
722
  *Returns:* `operator[](pos)`.
723
 
 
 
724
  ``` cpp
725
  constexpr const charT& front() const;
726
  constexpr charT& front();
727
  ```
728
 
@@ -872,10 +969,18 @@ template<class InputIterator>
872
  iterator [[container.requirements.general]].
873
 
874
  *Effects:* Equivalent to:
875
  `return append(basic_string(first, last, get_allocator()));`
876
 
 
 
 
 
 
 
 
 
877
  ``` cpp
878
  constexpr basic_string& append(initializer_list<charT> il);
879
  ```
880
 
881
  *Effects:* Equivalent to: `return append(il.begin(), il.size());`
@@ -992,10 +1097,18 @@ template<class InputIterator>
992
  iterator [[container.requirements.general]].
993
 
994
  *Effects:* Equivalent to:
995
  `return assign(basic_string(first, last, get_allocator()));`
996
 
 
 
 
 
 
 
 
 
997
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
998
 
999
  ``` cpp
1000
  constexpr basic_string& insert(size_type pos, const basic_string& str);
1001
  ```
@@ -1054,22 +1167,22 @@ return insert(pos1, sv.substr(pos2, n));
1054
  constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
1055
  ```
1056
 
1057
  *Preconditions:* \[`s`, `s + n`) is a valid range.
1058
 
1059
- *Throws:*
1060
-
1061
- - `out_of_range` if `pos > size()`,
1062
- - `length_error` if `n > max_size() - size()`, or
1063
- - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1064
-
1065
  *Effects:* Inserts a copy of the range \[`s`, `s + n`) immediately
1066
  before the character at position `pos` if `pos < size()`, or otherwise
1067
  at the end of the string.
1068
 
1069
  *Returns:* `*this`.
1070
 
 
 
 
 
 
 
1071
  ``` cpp
1072
  constexpr basic_string& insert(size_type pos, const charT* s);
1073
  ```
1074
 
1075
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
@@ -1124,10 +1237,23 @@ iterator [[container.requirements.general]].
1124
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1125
 
1126
  *Returns:* An iterator which refers to the first inserted character, or
1127
  `p` if `first == last`.
1128
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1129
  ``` cpp
1130
  constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1131
  ```
1132
 
1133
  *Effects:* Equivalent to: `return insert(p, il.begin(), il.end());`
@@ -1136,57 +1262,57 @@ constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1136
 
1137
  ``` cpp
1138
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1139
  ```
1140
 
1141
- *Throws:* `out_of_range` if `pos` `> size()`.
1142
-
1143
  *Effects:* Determines the effective length `xlen` of the string to be
1144
  removed as the smaller of `n` and `size() - pos`. Removes the characters
1145
  in the range \[`begin() + pos`, `begin() + pos + xlen`).
1146
 
1147
  *Returns:* `*this`.
1148
 
 
 
1149
  ``` cpp
1150
  constexpr iterator erase(const_iterator p);
1151
  ```
1152
 
1153
  *Preconditions:* `p` is a valid dereferenceable iterator on `*this`.
1154
 
1155
- *Throws:* Nothing.
1156
-
1157
  *Effects:* Removes the character referred to by `p`.
1158
 
1159
  *Returns:* An iterator which points to the element immediately following
1160
  `p` prior to the element being erased. If no such element exists,
1161
  `end()` is returned.
1162
 
 
 
1163
  ``` cpp
1164
  constexpr iterator erase(const_iterator first, const_iterator last);
1165
  ```
1166
 
1167
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
1168
  \[`first`, `last`) is a valid range.
1169
 
1170
- *Throws:* Nothing.
1171
-
1172
  *Effects:* Removes the characters in the range `[first, last)`.
1173
 
1174
  *Returns:* An iterator which points to the element pointed to by `last`
1175
  prior to the other elements being erased. If no such element exists,
1176
  `end()` is returned.
1177
 
 
 
1178
  ``` cpp
1179
  constexpr void pop_back();
1180
  ```
1181
 
1182
  *Preconditions:* `!empty()`.
1183
 
1184
- *Throws:* Nothing.
1185
-
1186
  *Effects:* Equivalent to `erase(end() - 1)`.
1187
 
 
 
1188
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1189
 
1190
  ``` cpp
1191
  constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1192
  ```
@@ -1246,25 +1372,25 @@ return replace(pos1, n1, sv.substr(pos2, n2));
1246
  constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1247
  ```
1248
 
1249
  *Preconditions:* \[`s`, `s + n2`) is a valid range.
1250
 
1251
- *Throws:*
1252
-
1253
- - `out_of_range` if `pos1 > size()`,
1254
- - `length_error` if the length of the resulting string would exceed
1255
- `max_size()` (see below), or
1256
- - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1257
-
1258
  *Effects:* Determines the effective length `xlen` of the string to be
1259
  removed as the smaller of `n1` and `size() - pos1`. If
1260
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1261
  function replaces the characters in the range \[`begin() + pos1`,
1262
  `begin() + pos1 + xlen`) with a copy of the range \[`s`, `s + n2`).
1263
 
1264
  *Returns:* `*this`.
1265
 
 
 
 
 
 
 
 
1266
  ``` cpp
1267
  constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1268
  ```
1269
 
1270
  *Effects:* Equivalent to:
@@ -1272,25 +1398,25 @@ constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1272
 
1273
  ``` cpp
1274
  constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
1275
  ```
1276
 
1277
- *Throws:*
1278
-
1279
- - `out_of_range` if `pos1 > size()`,
1280
- - `length_error` if the length of the resulting string would exceed
1281
- `max_size()` (see below), or
1282
- - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
1283
-
1284
  *Effects:* Determines the effective length `xlen` of the string to be
1285
  removed as the smaller of `n1` and `size() - pos1`. If
1286
  `size() - xlen >=` `max_size() - n2` throws `length_error`. Otherwise,
1287
  the function replaces the characters in the range \[`begin() + pos1`,
1288
  `begin() + pos1 + xlen`) with `n2` copies of `c`.
1289
 
1290
  *Returns:* `*this`.
1291
 
 
 
 
 
 
 
 
1292
  ``` cpp
1293
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1294
  ```
1295
 
1296
  *Effects:* Equivalent to:
@@ -1348,10 +1474,21 @@ template<class InputIterator>
1348
  iterator [[container.requirements.general]].
1349
 
1350
  *Effects:* Equivalent to:
1351
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
1352
 
 
 
 
 
 
 
 
 
 
 
 
1353
  ``` cpp
1354
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
1355
  ```
1356
 
1357
  *Effects:* Equivalent to:
@@ -1494,25 +1631,27 @@ template<class T>
1494
  ``` cpp
1495
  basic_string_view<charT, traits> s = *this, sv = t;
1496
  return s.G(sv, pos);
1497
  ```
1498
 
1499
- *Remarks:* The expression inside `noexcept` is equivalent to
1500
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1501
 
1502
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
1503
 
1504
  ``` cpp
1505
- constexpr basic_string substr(size_type pos = 0, size_type n = npos) const;
1506
  ```
1507
 
1508
- *Throws:* `out_of_range` if `pos > size()`.
1509
 
1510
- *Effects:* Determines the effective length `rlen` of the string to copy
1511
- as the smaller of `n` and `size() - pos`.
 
1512
 
1513
- *Returns:* `basic_string(data()+pos, rlen)`.
 
1514
 
1515
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
1516
 
1517
  ``` cpp
1518
  template<class T>
@@ -1526,11 +1665,11 @@ template<class T>
1526
  - `is_convertible_v<const T&, const charT*>` is `false`.
1527
 
1528
  *Effects:* Equivalent to:
1529
  `return basic_string_view<charT, traits>(*this).compare(t);`
1530
 
1531
- *Remarks:* The expression inside `noexcept` is equivalent to
1532
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1533
 
1534
  ``` cpp
1535
  template<class T>
1536
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -1639,5 +1778,19 @@ constexpr bool ends_with(const charT* x) const;
1639
 
1640
  ``` cpp
1641
  return basic_string_view<charT, traits>(data(), size()).ends_with(x);
1642
  ```
1643
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ### Class template `basic_string` <a id="basic.string">[[basic.string]]</a>
2
 
3
+ #### General <a id="basic.string.general">[[basic.string.general]]</a>
4
+
5
  The class template `basic_string` describes objects that can store a
6
  sequence consisting of a varying number of arbitrary char-like objects
7
  with the first element of the sequence at position zero. Such a sequence
8
  is also called a “string” if the type of the char-like objects that it
9
+ holds is clear from context. In the rest of [[basic.string]], the type
10
+ of the char-like objects held in a `basic_string` object is designated
11
+ by `charT`.
12
 
13
  A specialization of `basic_string` is a contiguous container
14
+ [[container.reqmts]].
15
 
16
  In all cases, \[`data()`, `data() + size()`\] is a valid range,
17
  `data() + size()` points at an object with value `charT()` (a “null
18
  terminator”), and `size() <= capacity()` is `true`.
19
 
 
36
 
37
  using iterator = implementation-defined // type of basic_string::iterator; // see [container.requirements]
38
  using const_iterator = implementation-defined // type of basic_string::const_iterator; // see [container.requirements]
39
  using reverse_iterator = std::reverse_iterator<iterator>;
40
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
41
+ static constexpr size_type npos = size_type(-1);
42
 
43
  // [string.cons], construct/copy/destroy
44
  constexpr basic_string() noexcept(noexcept(Allocator())) : basic_string(Allocator()) { }
45
  constexpr explicit basic_string(const Allocator& a) noexcept;
46
  constexpr basic_string(const basic_string& str);
47
  constexpr basic_string(basic_string&& str) noexcept;
48
  constexpr basic_string(const basic_string& str, size_type pos,
49
  const Allocator& a = Allocator());
50
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
51
  const Allocator& a = Allocator());
52
+ constexpr basic_string(basic_string&& str, size_type pos,
53
+ const Allocator& a = Allocator());
54
+ constexpr basic_string(basic_string&& str, size_type pos, size_type n,
55
+ const Allocator& a = Allocator());
56
  template<class T>
57
  constexpr basic_string(const T& t, size_type pos, size_type n,
58
  const Allocator& a = Allocator());
59
  template<class T>
60
  constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
61
  constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
62
  constexpr basic_string(const charT* s, const Allocator& a = Allocator());
63
+ basic_string(nullptr_t) = delete;
64
  constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
65
  template<class InputIterator>
66
  constexpr basic_string(InputIterator begin, InputIterator end,
67
  const Allocator& a = Allocator());
68
+ template<container-compatible-range<charT> R>
69
+ constexpr basic_string(from_range_t, R&& rg, const Allocator& a = Allocator());
70
  constexpr basic_string(initializer_list<charT>, const Allocator& = Allocator());
71
  constexpr basic_string(const basic_string&, const Allocator&);
72
  constexpr basic_string(basic_string&&, const Allocator&);
73
  constexpr ~basic_string();
74
 
 
77
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
78
  allocator_traits<Allocator>::is_always_equal::value);
79
  template<class T>
80
  constexpr basic_string& operator=(const T& t);
81
  constexpr basic_string& operator=(const charT* s);
82
+ basic_string& operator=(nullptr_t) = delete;
83
  constexpr basic_string& operator=(charT c);
84
  constexpr basic_string& operator=(initializer_list<charT>);
85
 
86
  // [string.iterators], iterators
87
  constexpr iterator begin() noexcept;
 
103
  constexpr size_type size() const noexcept;
104
  constexpr size_type length() const noexcept;
105
  constexpr size_type max_size() const noexcept;
106
  constexpr void resize(size_type n, charT c);
107
  constexpr void resize(size_type n);
108
+ template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
109
  constexpr size_type capacity() const noexcept;
110
  constexpr void reserve(size_type res_arg);
111
  constexpr void shrink_to_fit();
112
  constexpr void clear() noexcept;
113
  [[nodiscard]] constexpr bool empty() const noexcept;
 
139
  constexpr basic_string& append(const charT* s, size_type n);
140
  constexpr basic_string& append(const charT* s);
141
  constexpr basic_string& append(size_type n, charT c);
142
  template<class InputIterator>
143
  constexpr basic_string& append(InputIterator first, InputIterator last);
144
+ template<container-compatible-range<charT> R>
145
+ constexpr basic_string& append_range(R&& rg);
146
  constexpr basic_string& append(initializer_list<charT>);
147
 
148
  constexpr void push_back(charT c);
149
 
150
  constexpr basic_string& assign(const basic_string& str);
 
159
  constexpr basic_string& assign(const charT* s, size_type n);
160
  constexpr basic_string& assign(const charT* s);
161
  constexpr basic_string& assign(size_type n, charT c);
162
  template<class InputIterator>
163
  constexpr basic_string& assign(InputIterator first, InputIterator last);
164
+ template<container-compatible-range<charT> R>
165
+ constexpr basic_string& assign_range(R&& rg);
166
  constexpr basic_string& assign(initializer_list<charT>);
167
 
168
  constexpr basic_string& insert(size_type pos, const basic_string& str);
169
  constexpr basic_string& insert(size_type pos1, const basic_string& str,
170
  size_type pos2, size_type n = npos);
 
178
  constexpr basic_string& insert(size_type pos, size_type n, charT c);
179
  constexpr iterator insert(const_iterator p, charT c);
180
  constexpr iterator insert(const_iterator p, size_type n, charT c);
181
  template<class InputIterator>
182
  constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
183
+ template<container-compatible-range<charT> R>
184
+ constexpr iterator insert_range(const_iterator p, R&& rg);
185
  constexpr iterator insert(const_iterator p, initializer_list<charT>);
186
 
187
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
188
  constexpr iterator erase(const_iterator p);
189
  constexpr iterator erase(const_iterator first, const_iterator last);
 
210
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const charT* s);
211
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, size_type n, charT c);
212
  template<class InputIterator>
213
  constexpr basic_string& replace(const_iterator i1, const_iterator i2,
214
  InputIterator j1, InputIterator j2);
215
+ template<container-compatible-range<charT> R>
216
+ constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);
217
  constexpr basic_string& replace(const_iterator, const_iterator, initializer_list<charT>);
218
 
219
  constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
220
 
221
  constexpr void swap(basic_string& str)
 
272
  size_type pos = npos) const noexcept;
273
  constexpr size_type find_last_not_of(const charT* s, size_type pos, size_type n) const;
274
  constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
275
  constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
276
 
277
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
278
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
279
 
280
  template<class T>
281
  constexpr int compare(const T& t) const noexcept(see below);
282
  template<class T>
283
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 
296
  constexpr bool starts_with(charT x) const noexcept;
297
  constexpr bool starts_with(const charT* x) const;
298
  constexpr bool ends_with(basic_string_view<charT, traits> x) const noexcept;
299
  constexpr bool ends_with(charT x) const noexcept;
300
  constexpr bool ends_with(const charT* x) const;
301
+
302
+ constexpr bool contains(basic_string_view<charT, traits> x) const noexcept;
303
+ constexpr bool contains(charT x) const noexcept;
304
+ constexpr bool contains(const charT* x) const;
305
  };
306
 
307
  template<class InputIterator,
308
  class Allocator = allocator<typename iterator_traits<InputIterator>::value_type>>
309
  basic_string(InputIterator, InputIterator, Allocator = Allocator())
310
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
311
  char_traits<typename iterator_traits<InputIterator>::value_type>,
312
  Allocator>;
313
 
314
+ template<ranges::input_range R,
315
+ class Allocator = allocator<ranges::range_value_t<R>>>
316
+ basic_string(from_range_t, R&&, Allocator = Allocator())
317
+ -> basic_string<ranges::range_value_t<R>, char_traits<ranges::range_value_t<R>>,
318
+ Allocator>;
319
+
320
  template<class charT,
321
  class traits,
322
  class Allocator = allocator<charT>>
323
  explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
324
  -> basic_string<charT, traits, Allocator>;
 
335
 
336
  A `size_type` parameter type in a `basic_string` deduction guide refers
337
  to the `size_type` member type of the type deduced by the deduction
338
  guide.
339
 
340
+ The types `iterator` and `const_iterator` meet the constexpr iterator
341
+ requirements [[iterator.requirements.general]].
342
+
343
  #### General requirements <a id="string.require">[[string.require]]</a>
344
 
345
  If any operation would cause `size()` to exceed `max_size()`, that
346
  operation throws an exception object of type `length_error`.
347
 
 
357
  objects as needed. The `Allocator` object used is obtained as described
358
  in [[container.requirements.general]]. In every specialization
359
  `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
360
  the character traits requirements [[char.traits]].
361
 
362
+ [*Note 1*: Every specialization
363
+ `basic_string<charT, traits, Allocator>` is an allocator-aware
364
+ container, but does not use the allocator’s `construct` and `destroy`
365
+ member functions [[container.requirements.general]]. — *end note*]
366
+
367
+ [*Note 2*: The program is ill-formed if `traits::char_type` is not the
368
  same type as `charT`. — *end note*]
369
 
370
  References, pointers, and iterators referring to the elements of a
371
  `basic_string` sequence may be invalidated by the following uses of that
372
  `basic_string` object:
373
 
374
  - Passing as an argument to any standard library function taking a
375
+ reference to non-const `basic_string` as an argument.[^3]
376
  - Calling non-const member functions, except `operator[]`, `at`, `data`,
377
  `front`, `back`, `begin`, `rbegin`, `end`, and `rend`.
378
 
379
  #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
380
 
 
398
  ``` cpp
399
  constexpr basic_string(const basic_string& str, size_type pos,
400
  const Allocator& a = Allocator());
401
  constexpr basic_string(const basic_string& str, size_type pos, size_type n,
402
  const Allocator& a = Allocator());
403
+ constexpr basic_string(basic_string&& str, size_type pos,
404
+ const Allocator& a = Allocator());
405
+ constexpr basic_string(basic_string&& str, size_type pos, size_type n,
406
+ const Allocator& a = Allocator());
407
  ```
408
 
409
+ Let
410
 
411
+ - `s` be the value of `str` prior to this call and
412
+ - `rlen` be `pos + min(n, s.size() - pos)` for the overloads with
413
+ parameter `n`, and `s.size()` otherwise.
414
+
415
+ *Effects:* Constructs an object whose initial value is the range
416
+ \[`s.data() + pos`, `s.data() + rlen`).
417
+
418
+ *Throws:* `out_of_range` if `pos > s.size()`.
419
+
420
+ *Remarks:* For the overloads with a `basic_string&&` parameter, `str` is
421
+ left in a valid but unspecified state.
422
+
423
+ *Recommended practice:* For the overloads with a `basic_string&&`
424
+ parameter, implementations should avoid allocation if
425
+ `s.get_allocator() == a` is `true`.
426
 
427
  ``` cpp
428
  template<class T>
429
  constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
430
  ```
 
499
 
500
  *Constraints:* `InputIterator` is a type that qualifies as an input
501
  iterator [[container.requirements.general]].
502
 
503
  *Effects:* Constructs a string from the values in the range \[`begin`,
504
+ `end`), as specified in [[sequence.reqmts]].
505
+
506
+ ``` cpp
507
+ template<container-compatible-range<charT> R>
508
+ constexpr basic_string(from_range_t, R&& rg, const Allocator& = Allocator());
509
+ ```
510
+
511
+ *Effects:* Constructs a string from the values in the range `rg`, as
512
+ specified in [[sequence.reqmts]].
513
 
514
  ``` cpp
515
  constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
516
  ```
517
 
 
697
  constexpr void resize(size_type n);
698
  ```
699
 
700
  *Effects:* Equivalent to `resize(n, charT())`.
701
 
702
+ ``` cpp
703
+ template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
704
+ ```
705
+
706
+ Let
707
+
708
+ - `o = size()` before the call to `resize_and_overwrite`.
709
+ - `k` be `min(o, n)`.
710
+ - `p` be a value of type `charT*` or `charT* const`, such that the range
711
+ \[`p`, `p + n`\] is valid and `this->compare(0, k, p, k) == 0` is
712
+ `true` before the call. The values in the range \[`p + k`, `p + n`\]
713
+ may be indeterminate [[basic.indet]].
714
+ - `m` be a value of type `size_type` or `const size_type` equal to `n`.
715
+ - *`OP`* be the expression `std::move(op)(p, m)`.
716
+ - `r` = *`OP`*.
717
+
718
+ *Mandates:* *`OP`* has an integer-like type [[iterator.concept.winc]].
719
+
720
+ *Preconditions:*
721
+
722
+ - *`OP`* does not throw an exception or modify `p` or `m`.
723
+ - `r` ≥ 0.
724
+ - `r` ≤ `m`.
725
+ - After evaluating *`OP`* there are no indeterminate values in the range
726
+ \[`p`, `p + r`).
727
+
728
+ *Effects:* Evaluates *`OP`*, replaces the contents of `*this` with
729
+ \[`p`, `p + r`), and invalidates all pointers and references to the
730
+ range \[`p`, `p + n`\].
731
+
732
+ *Recommended practice:* Implementations should avoid unnecessary copies
733
+ and allocations by, for example, making `p` a pointer into internal
734
+ storage and by restoring `*(p + r)` to `charT()` after evaluating
735
+ *`OP`*.
736
+
737
  ``` cpp
738
  constexpr size_type capacity() const noexcept;
739
  ```
740
 
741
  *Returns:* The size of the allocated storage in the string.
 
812
  ``` cpp
813
  constexpr const_reference at(size_type pos) const;
814
  constexpr reference at(size_type pos);
815
  ```
816
 
 
 
817
  *Returns:* `operator[](pos)`.
818
 
819
+ *Throws:* `out_of_range` if `pos >= size()`.
820
+
821
  ``` cpp
822
  constexpr const charT& front() const;
823
  constexpr charT& front();
824
  ```
825
 
 
969
  iterator [[container.requirements.general]].
970
 
971
  *Effects:* Equivalent to:
972
  `return append(basic_string(first, last, get_allocator()));`
973
 
974
+ ``` cpp
975
+ template<container-compatible-range<charT> R>
976
+ constexpr basic_string& append_range(R&& rg);
977
+ ```
978
+
979
+ *Effects:* Equivalent to:
980
+ `return append(basic_string(from_range, std::forward<R>(rg), get_allocator()));`
981
+
982
  ``` cpp
983
  constexpr basic_string& append(initializer_list<charT> il);
984
  ```
985
 
986
  *Effects:* Equivalent to: `return append(il.begin(), il.size());`
 
1097
  iterator [[container.requirements.general]].
1098
 
1099
  *Effects:* Equivalent to:
1100
  `return assign(basic_string(first, last, get_allocator()));`
1101
 
1102
+ ``` cpp
1103
+ template<container-compatible-range<charT> R>
1104
+ constexpr basic_string& assign_range(R&& rg);
1105
+ ```
1106
+
1107
+ *Effects:* Equivalent to:
1108
+ `return assign(basic_string(from_range, std::forward<R>(rg), get_allocator()));`
1109
+
1110
  ##### `basic_string::insert` <a id="string.insert">[[string.insert]]</a>
1111
 
1112
  ``` cpp
1113
  constexpr basic_string& insert(size_type pos, const basic_string& str);
1114
  ```
 
1167
  constexpr basic_string& insert(size_type pos, const charT* s, size_type n);
1168
  ```
1169
 
1170
  *Preconditions:* \[`s`, `s + n`) is a valid range.
1171
 
 
 
 
 
 
 
1172
  *Effects:* Inserts a copy of the range \[`s`, `s + n`) immediately
1173
  before the character at position `pos` if `pos < size()`, or otherwise
1174
  at the end of the string.
1175
 
1176
  *Returns:* `*this`.
1177
 
1178
+ *Throws:*
1179
+
1180
+ - `out_of_range` if `pos > size()`,
1181
+ - `length_error` if `n > max_size() - size()`, or
1182
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1183
+
1184
  ``` cpp
1185
  constexpr basic_string& insert(size_type pos, const charT* s);
1186
  ```
1187
 
1188
  *Effects:* Equivalent to: `return insert(pos, s, traits::length(s));`
 
1237
  `insert(p - begin(), basic_string(first, last, get_allocator()))`.
1238
 
1239
  *Returns:* An iterator which refers to the first inserted character, or
1240
  `p` if `first == last`.
1241
 
1242
+ ``` cpp
1243
+ template<container-compatible-range<charT> R>
1244
+ constexpr iterator insert_range(const_iterator p, R&& rg);
1245
+ ```
1246
+
1247
+ *Preconditions:* `p` is a valid iterator on `*this`.
1248
+
1249
+ *Effects:* Equivalent to
1250
+ `insert(p - begin(), basic_string(from_range, std::forward<R>(rg), get_allocator()))`.
1251
+
1252
+ *Returns:* An iterator which refers to the first inserted character, or
1253
+ `p` if `rg` is empty.
1254
+
1255
  ``` cpp
1256
  constexpr iterator insert(const_iterator p, initializer_list<charT> il);
1257
  ```
1258
 
1259
  *Effects:* Equivalent to: `return insert(p, il.begin(), il.end());`
 
1262
 
1263
  ``` cpp
1264
  constexpr basic_string& erase(size_type pos = 0, size_type n = npos);
1265
  ```
1266
 
 
 
1267
  *Effects:* Determines the effective length `xlen` of the string to be
1268
  removed as the smaller of `n` and `size() - pos`. Removes the characters
1269
  in the range \[`begin() + pos`, `begin() + pos + xlen`).
1270
 
1271
  *Returns:* `*this`.
1272
 
1273
+ *Throws:* `out_of_range` if `pos` `> size()`.
1274
+
1275
  ``` cpp
1276
  constexpr iterator erase(const_iterator p);
1277
  ```
1278
 
1279
  *Preconditions:* `p` is a valid dereferenceable iterator on `*this`.
1280
 
 
 
1281
  *Effects:* Removes the character referred to by `p`.
1282
 
1283
  *Returns:* An iterator which points to the element immediately following
1284
  `p` prior to the element being erased. If no such element exists,
1285
  `end()` is returned.
1286
 
1287
+ *Throws:* Nothing.
1288
+
1289
  ``` cpp
1290
  constexpr iterator erase(const_iterator first, const_iterator last);
1291
  ```
1292
 
1293
  *Preconditions:* `first` and `last` are valid iterators on `*this`.
1294
  \[`first`, `last`) is a valid range.
1295
 
 
 
1296
  *Effects:* Removes the characters in the range `[first, last)`.
1297
 
1298
  *Returns:* An iterator which points to the element pointed to by `last`
1299
  prior to the other elements being erased. If no such element exists,
1300
  `end()` is returned.
1301
 
1302
+ *Throws:* Nothing.
1303
+
1304
  ``` cpp
1305
  constexpr void pop_back();
1306
  ```
1307
 
1308
  *Preconditions:* `!empty()`.
1309
 
 
 
1310
  *Effects:* Equivalent to `erase(end() - 1)`.
1311
 
1312
+ *Throws:* Nothing.
1313
+
1314
  ##### `basic_string::replace` <a id="string.replace">[[string.replace]]</a>
1315
 
1316
  ``` cpp
1317
  constexpr basic_string& replace(size_type pos1, size_type n1, const basic_string& str);
1318
  ```
 
1372
  constexpr basic_string& replace(size_type pos1, size_type n1, const charT* s, size_type n2);
1373
  ```
1374
 
1375
  *Preconditions:* \[`s`, `s + n2`) is a valid range.
1376
 
 
 
 
 
 
 
 
1377
  *Effects:* Determines the effective length `xlen` of the string to be
1378
  removed as the smaller of `n1` and `size() - pos1`. If
1379
  `size() - xlen >= max_size() - n2` throws `length_error`. Otherwise, the
1380
  function replaces the characters in the range \[`begin() + pos1`,
1381
  `begin() + pos1 + xlen`) with a copy of the range \[`s`, `s + n2`).
1382
 
1383
  *Returns:* `*this`.
1384
 
1385
+ *Throws:*
1386
+
1387
+ - `out_of_range` if `pos1 > size()`,
1388
+ - `length_error` if the length of the resulting string would exceed
1389
+ `max_size()`, or
1390
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate`.
1391
+
1392
  ``` cpp
1393
  constexpr basic_string& replace(size_type pos, size_type n, const charT* s);
1394
  ```
1395
 
1396
  *Effects:* Equivalent to:
 
1398
 
1399
  ``` cpp
1400
  constexpr basic_string& replace(size_type pos1, size_type n1, size_type n2, charT c);
1401
  ```
1402
 
 
 
 
 
 
 
 
1403
  *Effects:* Determines the effective length `xlen` of the string to be
1404
  removed as the smaller of `n1` and `size() - pos1`. If
1405
  `size() - xlen >=` `max_size() - n2` throws `length_error`. Otherwise,
1406
  the function replaces the characters in the range \[`begin() + pos1`,
1407
  `begin() + pos1 + xlen`) with `n2` copies of `c`.
1408
 
1409
  *Returns:* `*this`.
1410
 
1411
+ *Throws:*
1412
+
1413
+ - `out_of_range` if `pos1 > size()`,
1414
+ - `length_error` if the length of the resulting string would
1415
+ exceed`max_size()`, or
1416
+ - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
1417
+
1418
  ``` cpp
1419
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
1420
  ```
1421
 
1422
  *Effects:* Equivalent to:
 
1474
  iterator [[container.requirements.general]].
1475
 
1476
  *Effects:* Equivalent to:
1477
  `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
1478
 
1479
+ ``` cpp
1480
+ template<container-compatible-range<charT> R>
1481
+ constexpr basic_string& replace_with_range(const_iterator i1, const_iterator i2, R&& rg);
1482
+ ```
1483
+
1484
+ *Effects:* Equivalent to:
1485
+
1486
+ ``` cpp
1487
+ return replace(i1, i2, basic_string(from_range, std::forward<R>(rg), get_allocator()));
1488
+ ```
1489
+
1490
  ``` cpp
1491
  constexpr basic_string& replace(const_iterator i1, const_iterator i2, initializer_list<charT> il);
1492
  ```
1493
 
1494
  *Effects:* Equivalent to:
 
1631
  ``` cpp
1632
  basic_string_view<charT, traits> s = *this, sv = t;
1633
  return s.G(sv, pos);
1634
  ```
1635
 
1636
+ *Remarks:* The exception specification is equivalent to
1637
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1638
 
1639
  ##### `basic_string::substr` <a id="string.substr">[[string.substr]]</a>
1640
 
1641
  ``` cpp
1642
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
1643
  ```
1644
 
1645
+ *Effects:* Equivalent to: `return basic_string(*this, pos, n);`
1646
 
1647
+ ``` cpp
1648
+ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
1649
+ ```
1650
 
1651
+ *Effects:* Equivalent to:
1652
+ `return basic_string(std::move(*this), pos, n);`
1653
 
1654
  ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
1655
 
1656
  ``` cpp
1657
  template<class T>
 
1665
  - `is_convertible_v<const T&, const charT*>` is `false`.
1666
 
1667
  *Effects:* Equivalent to:
1668
  `return basic_string_view<charT, traits>(*this).compare(t);`
1669
 
1670
+ *Remarks:* The exception specification is equivalent to
1671
  `is_nothrow_convertible_v<const T&, basic_string_view<charT, traits>>`.
1672
 
1673
  ``` cpp
1674
  template<class T>
1675
  constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 
1778
 
1779
  ``` cpp
1780
  return basic_string_view<charT, traits>(data(), size()).ends_with(x);
1781
  ```
1782
 
1783
+ ##### `basic_string::contains` <a id="string.contains">[[string.contains]]</a>
1784
+
1785
+ ``` cpp
1786
+ constexpr bool contains(basic_string_view<charT, traits> x) const noexcept;
1787
+ constexpr bool contains(charT x) const noexcept;
1788
+ constexpr bool contains(const charT* x) const;
1789
+ ```
1790
+
1791
+ *Effects:* Equivalent to:
1792
+
1793
+ ``` cpp
1794
+ return basic_string_view<charT, traits>(data(), size()).contains(x);
1795
+ ```
1796
+