From Jason Turner

[string.cons]

C++17 → C++20 17.5 KB 273 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp8a4qfs1r/{from.md → to.md} +114 -155
tmp/tmp8a4qfs1r/{from.md → to.md} RENAMED
@@ -1,196 +1,130 @@
1
- #### `basic_string` constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
2
 
3
  ``` cpp
4
- explicit basic_string(const Allocator& a) noexcept;
5
  ```
6
 
7
- *Effects:* Constructs an object of class `basic_string`. The
8
- postconditions of this function are indicated in
9
- Table  [[tab:strings.ctr.1]].
10
-
11
- **Table: `basic_string(const Allocator&)` effects** <a id="tab:strings.ctr.1">[tab:strings.ctr.1]</a>
12
-
13
- | Element | Value |
14
- | ------------ | -------------------------------------------------------------- |
15
- | `data()` | a non-null pointer that is copyable and can have 0 added to it |
16
- | `size()` | 0 |
17
- | `capacity()` | an unspecified value |
18
 
19
  ``` cpp
20
- basic_string(const basic_string& str);
21
- basic_string(basic_string&& str) noexcept;
22
  ```
23
 
24
- *Effects:* Constructs an object of class `basic_string` as indicated in
25
- Table  [[tab:strings.ctr.cpy]]. In the second form, `str` is left in a
26
- valid state with an unspecified value.
27
-
28
- **Table: `basic_string(const basic_string&)` effects** <a id="tab:strings.ctr.cpy">[tab:strings.ctr.cpy]</a>
29
 
30
- | Element | Value |
31
- | ------------ | --------------------------------------------------------------------------------------------------------------- |
32
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
33
- | `size()` | `str.size()` |
34
- | `capacity()` | a value at least as large as `size()` |
35
 
36
  ``` cpp
37
- basic_string(const basic_string& str, size_type pos,
 
 
38
  const Allocator& a = Allocator());
39
  ```
40
 
41
- *Throws:* `out_of_range` if `pos > str.size()`.
42
-
43
- *Effects:* Constructs an object of class `basic_string` and determines
44
- the effective length `rlen` of the initial string value as
45
- `str.size() - pos`, as indicated in Table  [[tab:strings.ctr.2]].
46
 
47
  ``` cpp
48
- basic_string(const basic_string& str, size_type pos, size_type n,
49
- const Allocator& a = Allocator());
50
  ```
51
 
52
- *Throws:* `out_of_range` if `pos > str.size()`.
53
-
54
- *Effects:* Constructs an object of class `basic_string` and determines
55
- the effective length `rlen` of the initial string value as the smaller
56
- of `n` and `str.size() - pos`, as indicated in
57
- Table  [[tab:strings.ctr.2]].
58
-
59
- **Table: `basic_string(const basic_string&, size_type, const Allocator&)`\protect\mbox{ }and\protect
60
- `basic_string(const basic_string&, size_type, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.2">[tab:strings.ctr.2]</a>
61
-
62
- | Element | Value |
63
- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
64
- | `data()` | points at the first element of an allocated copy of `rlen` consecutive elements of the string controlled by `str` beginning at position `pos` |
65
- | `size()` | `rlen` |
66
- | `capacity()` | a value at least as large as `size()` |
67
-
68
  ``` cpp
69
  template<class T>
70
- basic_string(const T& t, size_type pos, size_type n,
71
- const Allocator& a = Allocator());
72
  ```
73
 
 
 
 
 
74
  *Effects:* Creates a variable, `sv`, as if by
75
  `basic_string_view<charT, traits> sv = t;` and then behaves the same as:
76
 
77
  ``` cpp
78
  basic_string(sv.substr(pos, n), a);
79
  ```
80
 
81
- *Remarks:* This constructor shall not participate in overload resolution
82
- unless `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
83
- `true`.
84
-
85
  ``` cpp
86
- explicit basic_string(basic_string_view<charT, traits> sv,
87
- const Allocator& a = Allocator());
88
  ```
89
 
90
- *Effects:* Same as `basic_string(sv.data(), sv.size(), a)`.
 
 
 
 
 
 
 
 
91
 
92
  ``` cpp
93
- basic_string(const charT* s, size_type n,
94
- const Allocator& a = Allocator());
95
  ```
96
 
97
- *Requires:* `s` points to an array of at least `n` elements of `charT`.
98
 
99
- *Effects:* Constructs an object of class `basic_string` and determines
100
- its initial string value from the array of `charT` of length `n` whose
101
- first element is designated by `s`, as indicated in
102
- Table  [[tab:strings.ctr.3]].
103
 
104
- **Table: `basic_string(const charT*, size_type, const Allocator&)` effects** <a id="tab:strings.ctr.3">[tab:strings.ctr.3]</a>
105
-
106
- | Element | Value |
107
- | ------------ | ------------------------------------------------------------------------------------------------------ |
108
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
109
- | `size()` | `n` |
110
- | `capacity()` | a value at least as large as `size()` |
111
 
112
  ``` cpp
113
- basic_string(const charT* s, const Allocator& a = Allocator());
114
  ```
115
 
116
- *Requires:* `s` points to an array of at least `traits::length(s) + 1`
117
- elements of `charT`.
118
-
119
- *Effects:* Constructs an object of class `basic_string` and determines
120
- its initial string value from the array of `charT` of length
121
- `traits::length(s)` whose first element is designated by `s`, as
122
- indicated in Table  [[tab:strings.ctr.4]].
123
 
124
- **Table: `basic_string(const charT*, const Allocator&)` effects** <a id="tab:strings.ctr.4">[tab:strings.ctr.4]</a>
 
125
 
126
- | Element | Value |
127
- | ------------ | ------------------------------------------------------------------------------------------------------ |
128
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `s` |
129
- | `size()` | `traits::length(s)` |
130
- | `capacity()` | a value at least as large as `size()` |
131
 
132
  ``` cpp
133
- basic_string(size_type n, charT c, const Allocator& a = Allocator());
134
  ```
135
 
136
- *Requires:* `n < npos`.
137
-
138
- *Effects:* Constructs an object of class `basic_string` and determines
139
- its initial string value by repeating the char-like object `c` for all
140
- `n` elements, as indicated in Table  [[tab:strings.ctr.5]].
141
 
142
- **Table: `basic_string(size_t, charT, const Allocator&)` effects** <a id="tab:strings.ctr.5">[tab:strings.ctr.5]</a>
 
143
 
144
- | Element | Value |
145
- | ------------ | ----------------------------------------------------------------------------------------------------- |
146
- | `data()` | points at the first element of an allocated array of `n` elements, each storing the initial value `c` |
147
- | `size()` | `n` |
148
- | `capacity()` | a value at least as large as `size()` |
149
 
150
  ``` cpp
151
  template<class InputIterator>
152
- basic_string(InputIterator begin, InputIterator end,
153
- const Allocator& a = Allocator());
154
  ```
155
 
156
- *Effects:* If `InputIterator` is an integral type, equivalent to:
 
157
 
158
- ``` cpp
159
- basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a);
160
- ```
161
-
162
- Otherwise constructs a string from the values in the range \[`begin`,
163
- `end`), as indicated in the Sequence Requirements table
164
- (see  [[sequence.reqmts]]).
165
 
166
  ``` cpp
167
- basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
168
  ```
169
 
170
- *Effects:* Same as `basic_string(il.begin(), il.end(), a)`.
171
 
172
  ``` cpp
173
- basic_string(const basic_string& str, const Allocator& alloc);
174
- basic_string(basic_string&& str, const Allocator& alloc);
175
  ```
176
 
177
- *Effects:* Constructs an object of class `basic_string` as indicated in
178
- Table  [[tab:strings.ctr.6]]. The stored allocator is constructed from
179
- `alloc`. In the second form, `str` is left in a valid state with an
180
- unspecified value.
181
-
182
- **Table: `basic_string(const basic_string&, const Allocator&)`\protect and
183
- `basic_string(basic_string&&, const Allocator&)` effects** <a id="tab:strings.ctr.6">[tab:strings.ctr.6]</a>
184
-
185
- | Element | Value |
186
- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
187
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by the original value of `str.data()`. |
188
- | `size()` | the original value of `str.size()` |
189
- | `capacity()` | a value at least as large as `size()` |
190
- | `get_allocator()` | `alloc` |
191
-
192
 
193
  *Throws:* The second form throws nothing if
194
  `alloc == str.get_allocator()`.
195
 
196
  ``` cpp
@@ -200,69 +134,94 @@ template<class InputIterator,
200
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
201
  char_traits<typename iterator_traits<InputIterator>::value_type>,
202
  Allocator>;
203
  ```
204
 
205
- *Remarks:* Shall not participate in overload resolution if
206
- `InputIterator` is a type that does not qualify as an input iterator, or
207
- if `Allocator` is a type that does not qualify as an
208
- allocator ([[container.requirements.general]]).
209
 
210
  ``` cpp
211
- basic_string& operator=(const basic_string& str);
 
 
 
 
 
 
 
 
 
 
 
 
212
  ```
213
 
214
- *Effects:* If `*this` and `str` are not the same object, modifies
215
- `*this` as shown in Table  [[tab:strings.op=]].
 
 
 
 
216
 
217
- If `*this` and `str` are the same object, the member has no effect.
 
218
 
219
  *Returns:* `*this`.
220
 
221
- **Table: `operator=(const basic_string&)` effects** <a id="tab:strings.op=">[tab:strings.op=]</a>
222
-
223
- | Element | Value |
224
- | ------------ | --------------------------------------------------------------------------------------------------------------- |
225
- | `data()` | points at the first element of an allocated copy of the array whose first element is pointed at by `str.data()` |
226
- | `size()` | `str.size()` |
227
- | `capacity()` | a value at least as large as `size()` |
228
-
229
  ``` cpp
230
- basic_string& operator=(basic_string&& str)
231
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
232
  allocator_traits<Allocator>::is_always_equal::value);
233
  ```
234
 
235
  *Effects:* Move assigns as a sequence
236
- container ([[container.requirements]]), except that iterators, pointers
237
  and references may be invalidated.
238
 
239
  *Returns:* `*this`.
240
 
241
  ``` cpp
242
- basic_string& operator=(basic_string_view<charT, traits> sv);
 
243
  ```
244
 
245
- *Effects:* Equivalent to: `return assign(sv);`
 
 
 
 
 
 
246
 
247
  ``` cpp
248
- basic_string& operator=(const charT* s);
 
249
  ```
250
 
251
- *Returns:* `*this = basic_string(s)`.
 
 
252
 
253
- *Remarks:* Uses `traits::length()`.
 
254
 
255
  ``` cpp
256
- basic_string& operator=(charT c);
257
  ```
258
 
259
- *Returns:* `*this = basic_string(1, c)`.
260
 
261
  ``` cpp
262
- basic_string& operator=(initializer_list<charT> il);
263
  ```
264
 
265
- *Effects:* As if by: `*this = basic_string(il);`
 
 
 
 
266
 
267
- *Returns:* `*this`.
 
 
268
 
 
1
+ #### Constructors and assignment operators <a id="string.cons">[[string.cons]]</a>
2
 
3
  ``` cpp
4
+ constexpr explicit basic_string(const Allocator& a) noexcept;
5
  ```
6
 
7
+ *Ensures:* `size()` is equal to `0`.
 
 
 
 
 
 
 
 
 
 
8
 
9
  ``` cpp
10
+ constexpr basic_string(const basic_string& str);
11
+ constexpr basic_string(basic_string&& str) noexcept;
12
  ```
13
 
14
+ *Effects:* Constructs an object whose value is that of `str` prior to
15
+ this call.
 
 
 
16
 
17
+ *Remarks:* In the second form, `str` is left in a valid but unspecified
18
+ state.
 
 
 
19
 
20
  ``` cpp
21
+ constexpr basic_string(const basic_string& str, size_type pos,
22
+ const Allocator& a = Allocator());
23
+ constexpr basic_string(const basic_string& str, size_type pos, size_type n,
24
  const Allocator& a = Allocator());
25
  ```
26
 
27
+ *Effects:* Let `n` be `npos` for the first overload. Equivalent to:
 
 
 
 
28
 
29
  ``` cpp
30
+ basic_string(basic_string_view<charT, traits>(str).substr(pos, n), a)
 
31
  ```
32
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
33
  ``` cpp
34
  template<class T>
35
+ constexpr basic_string(const T& t, size_type pos, size_type n, const Allocator& a = Allocator());
 
36
  ```
37
 
38
+ *Constraints:*
39
+ `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
40
+ `true`.
41
+
42
  *Effects:* Creates a variable, `sv`, as if by
43
  `basic_string_view<charT, traits> sv = t;` and then behaves the same as:
44
 
45
  ``` cpp
46
  basic_string(sv.substr(pos, n), a);
47
  ```
48
 
 
 
 
 
49
  ``` cpp
50
+ template<class T>
51
+ constexpr explicit basic_string(const T& t, const Allocator& a = Allocator());
52
  ```
53
 
54
+ *Constraints:*
55
+
56
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
57
+ `true` and
58
+ - `is_convertible_v<const T&, const charT*>` is `false`.
59
+
60
+ *Effects:* Creates a variable, `sv`, as if by
61
+ `basic_string_view<charT, traits> sv = t;` and then behaves the same as
62
+ `basic_string(sv.data(), sv.size(), a)`.
63
 
64
  ``` cpp
65
+ constexpr basic_string(const charT* s, size_type n, const Allocator& a = Allocator());
 
66
  ```
67
 
68
+ *Preconditions:* \[`s`, `s + n`) is a valid range.
69
 
70
+ *Effects:* Constructs an object whose initial value is the range \[`s`,
71
+ `s + n`).
 
 
72
 
73
+ *Ensures:* `size()` is equal to `n`, and `traits::compare(data(), s, n)`
74
+ is equal to `0`.
 
 
 
 
 
75
 
76
  ``` cpp
77
+ constexpr basic_string(const charT* s, const Allocator& a = Allocator());
78
  ```
79
 
80
+ *Constraints:* `Allocator` is a type that qualifies as an
81
+ allocator [[container.requirements.general]].
 
 
 
 
 
82
 
83
+ [*Note 1*: This affects class template argument
84
+ deduction. — *end note*]
85
 
86
+ *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
 
 
 
 
87
 
88
  ``` cpp
89
+ constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
90
  ```
91
 
92
+ *Constraints:* `Allocator` is a type that qualifies as an
93
+ allocator [[container.requirements.general]].
 
 
 
94
 
95
+ [*Note 2*: This affects class template argument
96
+ deduction. — *end note*]
97
 
98
+ *Effects:* Constructs an object whose value consists of `n` copies of
99
+ `c`.
 
 
 
100
 
101
  ``` cpp
102
  template<class InputIterator>
103
+ constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
 
104
  ```
105
 
106
+ *Constraints:* `InputIterator` is a type that qualifies as an input
107
+ iterator [[container.requirements.general]].
108
 
109
+ *Effects:* Constructs a string from the values in the range \[`begin`,
110
+ `end`), as indicated in [[container.seq.req]].
 
 
 
 
 
111
 
112
  ``` cpp
113
+ constexpr basic_string(initializer_list<charT> il, const Allocator& a = Allocator());
114
  ```
115
 
116
+ *Effects:* Equivalent to `basic_string(il.begin(), il.end(), a)`.
117
 
118
  ``` cpp
119
+ constexpr basic_string(const basic_string& str, const Allocator& alloc);
120
+ constexpr basic_string(basic_string&& str, const Allocator& alloc);
121
  ```
122
 
123
+ *Effects:* Constructs an object whose value is that of `str` prior to
124
+ this call. The stored allocator is constructed from `alloc`. In the
125
+ second form, `str` is left in a valid but unspecified state.
 
 
 
 
 
 
 
 
 
 
 
 
126
 
127
  *Throws:* The second form throws nothing if
128
  `alloc == str.get_allocator()`.
129
 
130
  ``` cpp
 
134
  -> basic_string<typename iterator_traits<InputIterator>::value_type,
135
  char_traits<typename iterator_traits<InputIterator>::value_type>,
136
  Allocator>;
137
  ```
138
 
139
+ *Constraints:* `InputIterator` is a type that qualifies as an input
140
+ iterator, and `Allocator` is a type that qualifies as an
141
+ allocator [[container.requirements.general]].
 
142
 
143
  ``` cpp
144
+ template<class charT,
145
+ class traits,
146
+ class Allocator = allocator<charT>>
147
+ explicit basic_string(basic_string_view<charT, traits>, const Allocator& = Allocator())
148
+ -> basic_string<charT, traits, Allocator>;
149
+
150
+ template<class charT,
151
+ class traits,
152
+ class Allocator = allocator<charT>>
153
+ basic_string(basic_string_view<charT, traits>,
154
+ typename see below::size_type, typename see below::size_type,
155
+ const Allocator& = Allocator())
156
+ -> basic_string<charT, traits, Allocator>;
157
  ```
158
 
159
+ *Constraints:* `Allocator` is a type that qualifies as an
160
+ allocator [[container.requirements.general]].
161
+
162
+ ``` cpp
163
+ constexpr basic_string& operator=(const basic_string& str);
164
+ ```
165
 
166
+ *Effects:* If `*this` and `str` are the same object, has no effect.
167
+ Otherwise, replaces the value of `*this` with a copy of `str`.
168
 
169
  *Returns:* `*this`.
170
 
 
 
 
 
 
 
 
 
171
  ``` cpp
172
+ constexpr basic_string& operator=(basic_string&& str)
173
  noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
174
  allocator_traits<Allocator>::is_always_equal::value);
175
  ```
176
 
177
  *Effects:* Move assigns as a sequence
178
+ container [[container.requirements]], except that iterators, pointers
179
  and references may be invalidated.
180
 
181
  *Returns:* `*this`.
182
 
183
  ``` cpp
184
+ template<class T>
185
+ constexpr basic_string& operator=(const T& t);
186
  ```
187
 
188
+ *Constraints:*
189
+
190
+ - `is_convertible_v<const T&, basic_string_view<charT, traits>>` is
191
+ `true` and
192
+ - `is_convertible_v<const T&, const charT*>` is `false`.
193
+
194
+ *Effects:* Equivalent to:
195
 
196
  ``` cpp
197
+ basic_string_view<charT, traits> sv = t;
198
+ return assign(sv);
199
  ```
200
 
201
+ ``` cpp
202
+ constexpr basic_string& operator=(const charT* s);
203
+ ```
204
 
205
+ *Effects:* Equivalent to:
206
+ `return *this = basic_string_view<charT, traits>(s);`
207
 
208
  ``` cpp
209
+ constexpr basic_string& operator=(charT c);
210
  ```
211
 
212
+ *Effects:* Equivalent to:
213
 
214
  ``` cpp
215
+ return *this = basic_string_view<charT, traits>(addressof(c), 1);
216
  ```
217
 
218
+ ``` cpp
219
+ constexpr basic_string& operator=(initializer_list<charT> il);
220
+ ```
221
+
222
+ *Effects:* Equivalent to:
223
 
224
+ ``` cpp
225
+ return *this = basic_string_view<charT, traits>(il.begin(), il.size());
226
+ ```
227