From Jason Turner

[re.results]

C++17 → C++20 12.0 KB 117 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/tmpsxo3q2b4/{from.md → to.md} +40 -63
tmp/tmpsxo3q2b4/{from.md → to.md} RENAMED
@@ -3,16 +3,17 @@
3
  Class template `match_results` denotes a collection of character
4
  sequences representing the result of a regular expression match. Storage
5
  for the collection is allocated and freed as necessary by the member
6
  functions of class template `match_results`.
7
 
8
- The class template `match_results` satisfies the requirements of an
9
  allocator-aware container and of a sequence container (
10
  [[container.requirements.general]], [[sequence.reqmts]]) except that
11
- only operations defined for const-qualified sequence containers are
12
- supported and that the semantics of comparison functions are different
13
- from those required for a container.
 
14
 
15
  A default-constructed `match_results` object has no fully established
16
  result state. A match result is *ready* when, as a consequence of a
17
  completed regular expression match modifying such an object, its result
18
  state becomes fully established. The effects of calling most member
@@ -50,11 +51,12 @@ namespace std {
50
  using char_type =
51
  typename iterator_traits<BidirectionalIterator>::value_type;
52
  using string_type = basic_string<char_type>;
53
 
54
  // [re.results.const], construct/copy/destroy
55
- explicit match_results(const Allocator& a = Allocator());
 
56
  match_results(const match_results& m);
57
  match_results(match_results&& m) noexcept;
58
  match_results& operator=(const match_results& m);
59
  match_results& operator=(match_results&& m);
60
  ~match_results();
@@ -63,11 +65,11 @@ namespace std {
63
  bool ready() const;
64
 
65
  // [re.results.size], size
66
  size_type size() const;
67
  size_type max_size() const;
68
- bool empty() const;
69
 
70
  // [re.results.acc], element access
71
  difference_type length(size_type sub = 0) const;
72
  difference_type position(size_type sub = 0) const;
73
  string_type str(size_type sub = 0) const;
@@ -106,57 +108,40 @@ namespace std {
106
  void swap(match_results& that);
107
  };
108
  }
109
  ```
110
 
111
- ### `match_results` constructors <a id="re.results.const">[[re.results.const]]</a>
112
-
113
- In all `match_results` constructors, a copy of the `Allocator` argument
114
- shall be used for any memory allocation performed by the constructor or
115
- member functions during the lifetime of the object.
116
-
117
- ``` cpp
118
- match_results(const Allocator& a = Allocator());
119
- ```
120
-
121
- *Effects:* Constructs an object of class `match_results`.
122
-
123
- *Postconditions:* `ready()` returns `false`. `size()` returns `0`.
124
 
125
  ``` cpp
126
- match_results(const match_results& m);
127
  ```
128
 
129
- *Effects:* Constructs an object of class `match_results`, as a copy of
130
- `m`.
131
 
132
  ``` cpp
133
  match_results(match_results&& m) noexcept;
134
  ```
135
 
136
- *Effects:*  Move constructs an object of class `match_results` from `m`
137
- satisfying the same postconditions as Table  [[tab:re:results:assign]].
138
- Additionally, the stored `Allocator` value is move constructed from
139
  `m.get_allocator()`.
140
 
141
- *Throws:* Nothing.
142
 
143
  ``` cpp
144
  match_results& operator=(const match_results& m);
145
  ```
146
 
147
- *Effects:* Assigns `m` to `*this`. The postconditions of this function
148
- are indicated in Table  [[tab:re:results:assign]].
149
 
150
  ``` cpp
151
  match_results& operator=(match_results&& m);
152
  ```
153
 
154
- *Effects:*  Move-assigns `m` to `*this`. The postconditions of this
155
- function are indicated in Table  [[tab:re:results:assign]].
156
 
157
- **Table: `match_results` assignment operator effects** <a id="tab:re:results:assign">[tab:re:results:assign]</a>
158
 
159
  | Element | Value |
160
  | ------------- | ----------------------------------------------- |
161
  | `ready()` | `m.ready()` |
162
  | `size()` | `m.size()` |
@@ -166,20 +151,20 @@ function are indicated in Table  [[tab:re:results:assign]].
166
  | `(*this)[n]` | `m[n]` for all integers `n < m.size()` |
167
  | `length(n)` | `m.length(n)` for all integers `n < m.size()` |
168
  | `position(n)` | `m.position(n)` for all integers `n < m.size()` |
169
 
170
 
171
- ### `match_results` state <a id="re.results.state">[[re.results.state]]</a>
172
 
173
  ``` cpp
174
  bool ready() const;
175
  ```
176
 
177
  *Returns:* `true` if `*this` has a fully established result state,
178
  otherwise `false`.
179
 
180
- ### `match_results` size <a id="re.results.size">[[re.results.size]]</a>
181
 
182
  ``` cpp
183
  size_type size() const;
184
  ```
185
 
@@ -187,58 +172,58 @@ size_type size() const;
187
  expression that was matched if `*this` represents the result of a
188
  successful match. Otherwise returns `0`.
189
 
190
  [*Note 1*: The state of a `match_results` object can be modified only
191
  by passing that object to `regex_match` or `regex_search`.
192
- Sections  [[re.alg.match]] and  [[re.alg.search]] specify the effects of
193
- those algorithms on their `match_results` arguments. — *end note*]
194
 
195
  ``` cpp
196
  size_type max_size() const;
197
  ```
198
 
199
  *Returns:* The maximum number of `sub_match` elements that can be stored
200
  in `*this`.
201
 
202
  ``` cpp
203
- bool empty() const;
204
  ```
205
 
206
  *Returns:* `size() == 0`.
207
 
208
- ### `match_results` element access <a id="re.results.acc">[[re.results.acc]]</a>
209
 
210
  ``` cpp
211
  difference_type length(size_type sub = 0) const;
212
  ```
213
 
214
- *Requires:* `ready() == true`.
215
 
216
  *Returns:* `(*this)[sub].length()`.
217
 
218
  ``` cpp
219
  difference_type position(size_type sub = 0) const;
220
  ```
221
 
222
- *Requires:* `ready() == true`.
223
 
224
  *Returns:* The distance from the start of the target sequence to
225
  `(*this)[sub].first`.
226
 
227
  ``` cpp
228
  string_type str(size_type sub = 0) const;
229
  ```
230
 
231
- *Requires:* `ready() == true`.
232
 
233
  *Returns:* `string_type((*this)[sub])`.
234
 
235
  ``` cpp
236
  const_reference operator[](size_type n) const;
237
  ```
238
 
239
- *Requires:* `ready() == true`.
240
 
241
  *Returns:* A reference to the `sub_match` object representing the
242
  character sequence that matched marked sub-expression `n`. If `n == 0`
243
  then returns a reference to a `sub_match` object representing the
244
  character sequence that matched the whole regular expression. If
@@ -247,21 +232,21 @@ unmatched sub-expression.
247
 
248
  ``` cpp
249
  const_reference prefix() const;
250
  ```
251
 
252
- *Requires:* `ready() == true`.
253
 
254
  *Returns:* A reference to the `sub_match` object representing the
255
  character sequence from the start of the string being matched/searched
256
  to the start of the match found.
257
 
258
  ``` cpp
259
  const_reference suffix() const;
260
  ```
261
 
262
- *Requires:* `ready() == true`.
263
 
264
  *Returns:* A reference to the `sub_match` object representing the
265
  character sequence from the end of the match found to the end of the
266
  string being matched/searched.
267
 
@@ -279,22 +264,22 @@ const_iterator cend() const;
279
  ```
280
 
281
  *Returns:* A terminating iterator that enumerates over all the
282
  sub-expressions stored in `*this`.
283
 
284
- ### `match_results` formatting <a id="re.results.form">[[re.results.form]]</a>
285
 
286
  ``` cpp
287
  template<class OutputIter>
288
  OutputIter format(
289
  OutputIter out,
290
  const char_type* fmt_first, const char_type* fmt_last,
291
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
292
  ```
293
 
294
- *Requires:* `ready() == true` and `OutputIter` shall satisfy the
295
- requirements for an Output Iterator ([[output.iterators]]).
296
 
297
  *Effects:* Copies the character sequence \[`fmt_first`, `fmt_last`) to
298
  OutputIter `out`. Replaces each format specifier or escape sequence in
299
  the copied range with either the character(s) it represents or the
300
  sequence of characters within `*this` to which it refers. The bitmasks
@@ -322,11 +307,11 @@ template <class ST, class SA>
322
  basic_string<char_type, ST, SA> format(
323
  const basic_string<char_type, ST, SA>& fmt,
324
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
325
  ```
326
 
327
- *Requires:* `ready() == true`.
328
 
329
  *Effects:* Constructs an empty string `result` of type
330
  `basic_string<char_type, ST, SA>` and calls:
331
 
332
  ``` cpp
@@ -339,42 +324,42 @@ format(back_inserter(result), fmt, flags);
339
  string_type format(
340
  const char_type* fmt,
341
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
342
  ```
343
 
344
- *Requires:* `ready() == true`.
345
 
346
  *Effects:* Constructs an empty string `result` of type `string_type` and
347
  calls:
348
 
349
  ``` cpp
350
  format(back_inserter(result), fmt, fmt + char_traits<char_type>::length(fmt), flags);
351
  ```
352
 
353
  *Returns:* `result`.
354
 
355
- ### `match_results` allocator <a id="re.results.all">[[re.results.all]]</a>
356
 
357
  ``` cpp
358
  allocator_type get_allocator() const;
359
  ```
360
 
361
  *Returns:* A copy of the Allocator that was passed to the object’s
362
  constructor or, if that allocator has been replaced, a copy of the most
363
  recent replacement.
364
 
365
- ### `match_results` swap <a id="re.results.swap">[[re.results.swap]]</a>
366
 
367
  ``` cpp
368
  void swap(match_results& that);
369
  ```
370
 
371
  *Effects:* Swaps the contents of the two sequences.
372
 
373
- *Postconditions:* `*this` contains the sequence of matched
374
- sub-expressions that were in `that`, `that` contains the sequence of
375
- matched sub-expressions that were in `*this`.
376
 
377
  *Complexity:* Constant time.
378
 
379
  ``` cpp
380
  template<class BidirectionalIterator, class Allocator>
@@ -382,11 +367,11 @@ template <class BidirectionalIterator, class Allocator>
382
  match_results<BidirectionalIterator, Allocator>& m2);
383
  ```
384
 
385
  *Effects:* As if by `m1.swap(m2)`.
386
 
387
- ### `match_results` non-member functions <a id="re.results.nonmember">[[re.results.nonmember]]</a>
388
 
389
  ``` cpp
390
  template<class BidirectionalIterator, class Allocator>
391
  bool operator==(const match_results<BidirectionalIterator, Allocator>& m1,
392
  const match_results<BidirectionalIterator, Allocator>& m2);
@@ -403,15 +388,7 @@ returns `true` only if:
403
  - `m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin())`,
404
  and
405
  - `m1.suffix() == m2.suffix()`.
406
 
407
  [*Note 1*: The algorithm `equal` is defined in
408
- Clause  [[algorithms]]. — *end note*]
409
-
410
- ``` cpp
411
- template <class BidirectionalIterator, class Allocator>
412
- bool operator!=(const match_results<BidirectionalIterator, Allocator>& m1,
413
- const match_results<BidirectionalIterator, Allocator>& m2);
414
- ```
415
-
416
- *Returns:* `!(m1 == m2)`.
417
 
 
3
  Class template `match_results` denotes a collection of character
4
  sequences representing the result of a regular expression match. Storage
5
  for the collection is allocated and freed as necessary by the member
6
  functions of class template `match_results`.
7
 
8
+ The class template `match_results` meets the requirements of an
9
  allocator-aware container and of a sequence container (
10
  [[container.requirements.general]], [[sequence.reqmts]]) except that
11
+ only copy assignment, move assignment, and operations defined for
12
+ const-qualified sequence containers are supported and that the semantics
13
+ of comparison functions are different from those required for a
14
+ container.
15
 
16
  A default-constructed `match_results` object has no fully established
17
  result state. A match result is *ready* when, as a consequence of a
18
  completed regular expression match modifying such an object, its result
19
  state becomes fully established. The effects of calling most member
 
51
  using char_type =
52
  typename iterator_traits<BidirectionalIterator>::value_type;
53
  using string_type = basic_string<char_type>;
54
 
55
  // [re.results.const], construct/copy/destroy
56
+ match_results() : match_results(Allocator()) {}
57
+ explicit match_results(const Allocator&);
58
  match_results(const match_results& m);
59
  match_results(match_results&& m) noexcept;
60
  match_results& operator=(const match_results& m);
61
  match_results& operator=(match_results&& m);
62
  ~match_results();
 
65
  bool ready() const;
66
 
67
  // [re.results.size], size
68
  size_type size() const;
69
  size_type max_size() const;
70
+ [[nodiscard]] bool empty() const;
71
 
72
  // [re.results.acc], element access
73
  difference_type length(size_type sub = 0) const;
74
  difference_type position(size_type sub = 0) const;
75
  string_type str(size_type sub = 0) const;
 
108
  void swap(match_results& that);
109
  };
110
  }
111
  ```
112
 
113
+ ### Constructors <a id="re.results.const">[[re.results.const]]</a>
 
 
 
 
 
 
 
 
 
 
 
 
114
 
115
  ``` cpp
116
+ explicit match_results(const Allocator& a);
117
  ```
118
 
119
+ *Ensures:* `ready()` returns `false`. `size()` returns `0`.
 
120
 
121
  ``` cpp
122
  match_results(match_results&& m) noexcept;
123
  ```
124
 
125
+ *Effects:* The stored `Allocator` value is move constructed from
 
 
126
  `m.get_allocator()`.
127
 
128
+ *Ensures:* As specified in [[re.results.const]].
129
 
130
  ``` cpp
131
  match_results& operator=(const match_results& m);
132
  ```
133
 
134
+ *Ensures:* As specified in [[re.results.const]].
 
135
 
136
  ``` cpp
137
  match_results& operator=(match_results&& m);
138
  ```
139
 
140
+ *Ensures:* As specified in [[re.results.const]].
 
141
 
142
+ **Table: `match_results` assignment operator effects** <a id="re.results.const">[re.results.const]</a>
143
 
144
  | Element | Value |
145
  | ------------- | ----------------------------------------------- |
146
  | `ready()` | `m.ready()` |
147
  | `size()` | `m.size()` |
 
151
  | `(*this)[n]` | `m[n]` for all integers `n < m.size()` |
152
  | `length(n)` | `m.length(n)` for all integers `n < m.size()` |
153
  | `position(n)` | `m.position(n)` for all integers `n < m.size()` |
154
 
155
 
156
+ ### State <a id="re.results.state">[[re.results.state]]</a>
157
 
158
  ``` cpp
159
  bool ready() const;
160
  ```
161
 
162
  *Returns:* `true` if `*this` has a fully established result state,
163
  otherwise `false`.
164
 
165
+ ### Size <a id="re.results.size">[[re.results.size]]</a>
166
 
167
  ``` cpp
168
  size_type size() const;
169
  ```
170
 
 
172
  expression that was matched if `*this` represents the result of a
173
  successful match. Otherwise returns `0`.
174
 
175
  [*Note 1*: The state of a `match_results` object can be modified only
176
  by passing that object to `regex_match` or `regex_search`.
177
+ Subclauses  [[re.alg.match]] and  [[re.alg.search]] specify the effects
178
+ of those algorithms on their `match_results` arguments. — *end note*]
179
 
180
  ``` cpp
181
  size_type max_size() const;
182
  ```
183
 
184
  *Returns:* The maximum number of `sub_match` elements that can be stored
185
  in `*this`.
186
 
187
  ``` cpp
188
+ [[nodiscard]] bool empty() const;
189
  ```
190
 
191
  *Returns:* `size() == 0`.
192
 
193
+ ### Element access <a id="re.results.acc">[[re.results.acc]]</a>
194
 
195
  ``` cpp
196
  difference_type length(size_type sub = 0) const;
197
  ```
198
 
199
+ *Preconditions:* `ready() == true`.
200
 
201
  *Returns:* `(*this)[sub].length()`.
202
 
203
  ``` cpp
204
  difference_type position(size_type sub = 0) const;
205
  ```
206
 
207
+ *Preconditions:* `ready() == true`.
208
 
209
  *Returns:* The distance from the start of the target sequence to
210
  `(*this)[sub].first`.
211
 
212
  ``` cpp
213
  string_type str(size_type sub = 0) const;
214
  ```
215
 
216
+ *Preconditions:* `ready() == true`.
217
 
218
  *Returns:* `string_type((*this)[sub])`.
219
 
220
  ``` cpp
221
  const_reference operator[](size_type n) const;
222
  ```
223
 
224
+ *Preconditions:* `ready() == true`.
225
 
226
  *Returns:* A reference to the `sub_match` object representing the
227
  character sequence that matched marked sub-expression `n`. If `n == 0`
228
  then returns a reference to a `sub_match` object representing the
229
  character sequence that matched the whole regular expression. If
 
232
 
233
  ``` cpp
234
  const_reference prefix() const;
235
  ```
236
 
237
+ *Preconditions:* `ready() == true`.
238
 
239
  *Returns:* A reference to the `sub_match` object representing the
240
  character sequence from the start of the string being matched/searched
241
  to the start of the match found.
242
 
243
  ``` cpp
244
  const_reference suffix() const;
245
  ```
246
 
247
+ *Preconditions:* `ready() == true`.
248
 
249
  *Returns:* A reference to the `sub_match` object representing the
250
  character sequence from the end of the match found to the end of the
251
  string being matched/searched.
252
 
 
264
  ```
265
 
266
  *Returns:* A terminating iterator that enumerates over all the
267
  sub-expressions stored in `*this`.
268
 
269
+ ### Formatting <a id="re.results.form">[[re.results.form]]</a>
270
 
271
  ``` cpp
272
  template<class OutputIter>
273
  OutputIter format(
274
  OutputIter out,
275
  const char_type* fmt_first, const char_type* fmt_last,
276
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
277
  ```
278
 
279
+ *Preconditions:* `ready() == true` and `OutputIter` meets the
280
+ requirements for a *Cpp17OutputIterator*[[output.iterators]].
281
 
282
  *Effects:* Copies the character sequence \[`fmt_first`, `fmt_last`) to
283
  OutputIter `out`. Replaces each format specifier or escape sequence in
284
  the copied range with either the character(s) it represents or the
285
  sequence of characters within `*this` to which it refers. The bitmasks
 
307
  basic_string<char_type, ST, SA> format(
308
  const basic_string<char_type, ST, SA>& fmt,
309
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
310
  ```
311
 
312
+ *Preconditions:* `ready() == true`.
313
 
314
  *Effects:* Constructs an empty string `result` of type
315
  `basic_string<char_type, ST, SA>` and calls:
316
 
317
  ``` cpp
 
324
  string_type format(
325
  const char_type* fmt,
326
  regex_constants::match_flag_type flags = regex_constants::format_default) const;
327
  ```
328
 
329
+ *Preconditions:* `ready() == true`.
330
 
331
  *Effects:* Constructs an empty string `result` of type `string_type` and
332
  calls:
333
 
334
  ``` cpp
335
  format(back_inserter(result), fmt, fmt + char_traits<char_type>::length(fmt), flags);
336
  ```
337
 
338
  *Returns:* `result`.
339
 
340
+ ### Allocator <a id="re.results.all">[[re.results.all]]</a>
341
 
342
  ``` cpp
343
  allocator_type get_allocator() const;
344
  ```
345
 
346
  *Returns:* A copy of the Allocator that was passed to the object’s
347
  constructor or, if that allocator has been replaced, a copy of the most
348
  recent replacement.
349
 
350
+ ### Swap <a id="re.results.swap">[[re.results.swap]]</a>
351
 
352
  ``` cpp
353
  void swap(match_results& that);
354
  ```
355
 
356
  *Effects:* Swaps the contents of the two sequences.
357
 
358
+ *Ensures:* `*this` contains the sequence of matched sub-expressions that
359
+ were in `that`, `that` contains the sequence of matched sub-expressions
360
+ that were in `*this`.
361
 
362
  *Complexity:* Constant time.
363
 
364
  ``` cpp
365
  template<class BidirectionalIterator, class Allocator>
 
367
  match_results<BidirectionalIterator, Allocator>& m2);
368
  ```
369
 
370
  *Effects:* As if by `m1.swap(m2)`.
371
 
372
+ ### Non-member functions <a id="re.results.nonmember">[[re.results.nonmember]]</a>
373
 
374
  ``` cpp
375
  template<class BidirectionalIterator, class Allocator>
376
  bool operator==(const match_results<BidirectionalIterator, Allocator>& m1,
377
  const match_results<BidirectionalIterator, Allocator>& m2);
 
388
  - `m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin())`,
389
  and
390
  - `m1.suffix() == m2.suffix()`.
391
 
392
  [*Note 1*: The algorithm `equal` is defined in
393
+ [[algorithms]]. — *end note*]
 
 
 
 
 
 
 
 
394