From Jason Turner

[re.results]

C++14 → C++17 13.3 KB 166 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp8a1w88fs/{from.md → to.md} +83 -74
tmp/tmp8a1w88fs/{from.md → to.md} RENAMED
@@ -3,69 +3,73 @@
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` shall satisfy the requirements of an
9
- allocator-aware container and of a sequence container, as specified in 
10
- [[sequence.reqmts]], except that only operations defined for
11
- const-qualified sequence containers are supported.
 
 
12
 
13
  A default-constructed `match_results` object has no fully established
14
  result state. A match result is *ready* when, as a consequence of a
15
  completed regular expression match modifying such an object, its result
16
  state becomes fully established. The effects of calling most member
17
  functions from a `match_results` object that is not ready are undefined.
18
 
19
  The `sub_match` object stored at index 0 represents sub-expression 0,
20
  i.e., the whole match. In this case the `sub_match` member `matched` is
21
- always true. The `sub_match` object stored at index `n` denotes what
22
  matched the marked sub-expression `n` within the matched expression. If
23
  the sub-expression `n` participated in a regular expression match then
24
- the `sub_match` member `matched` evaluates to true, and members `first`
25
- and `second` denote the range of characters \[`first`, `second`) which
26
- formed that match. Otherwise `matched` is false, and members `first` and
27
- `second` point to the end of the sequence that was searched. The
28
- `sub_match` objects representing different sub-expressions that did not
29
- participate in a regular expression match need not be distinct.
 
 
30
 
31
  ``` cpp
32
  namespace std {
33
  template <class BidirectionalIterator,
34
  class Allocator = allocator<sub_match<BidirectionalIterator>>>
35
  class match_results {
36
  public:
37
- typedef sub_match<BidirectionalIterator> value_type;
38
- typedef const value_type& const_reference;
39
- typedef value_type& reference;
40
- typedef {implementation-defined} const_iterator;
41
- typedef const_iterator iterator;
42
- typedef typename
43
- iterator_traits<BidirectionalIterator>::difference_type difference_type;
44
- typedef typename allocator_traits<Allocator>::size_type size_type;
45
- typedef Allocator allocator_type;
46
- typedef typename iterator_traits<BidirectionalIterator>::
47
- value_type char_type;
48
- typedef basic_string<char_type> string_type;
49
 
50
- // [re.results.const], construct/copy/destroy:
51
  explicit match_results(const Allocator& a = Allocator());
52
  match_results(const match_results& m);
53
  match_results(match_results&& m) noexcept;
54
  match_results& operator=(const match_results& m);
55
  match_results& operator=(match_results&& m);
56
  ~match_results();
57
 
58
- // [re.results.state], state:
59
  bool ready() const;
60
 
61
- // [re.results.size], size:
62
  size_type size() const;
63
  size_type max_size() const;
64
  bool empty() const;
65
 
66
- // [re.results.acc], element access:
67
  difference_type length(size_type sub = 0) const;
68
  difference_type position(size_type sub = 0) const;
69
  string_type str(size_type sub = 0) const;
70
  const_reference operator[](size_type n) const;
71
 
@@ -74,37 +78,33 @@ namespace std {
74
  const_iterator begin() const;
75
  const_iterator end() const;
76
  const_iterator cbegin() const;
77
  const_iterator cend() const;
78
 
79
- // [re.results.form], format:
80
  template <class OutputIter>
81
  OutputIter
82
  format(OutputIter out,
83
  const char_type* fmt_first, const char_type* fmt_last,
84
- regex_constants::match_flag_type flags =
85
- regex_constants::format_default) const;
86
  template <class OutputIter, class ST, class SA>
87
  OutputIter
88
  format(OutputIter out,
89
  const basic_string<char_type, ST, SA>& fmt,
90
- regex_constants::match_flag_type flags =
91
- regex_constants::format_default) const;
92
  template <class ST, class SA>
93
  basic_string<char_type, ST, SA>
94
  format(const basic_string<char_type, ST, SA>& fmt,
95
- regex_constants::match_flag_type flags =
96
- regex_constants::format_default) const;
97
  string_type
98
  format(const char_type* fmt,
99
- regex_constants::match_flag_type flags =
100
- regex_constants::format_default) const;
101
 
102
- // [re.results.all], allocator:
103
  allocator_type get_allocator() const;
104
 
105
- // [re.results.swap], swap:
106
  void swap(match_results& that);
107
  };
108
  }
109
  ```
110
 
@@ -131,11 +131,11 @@ match_results(const match_results& 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.
@@ -183,15 +183,16 @@ otherwise `false`.
183
  size_type size() const;
184
  ```
185
 
186
  *Returns:* One plus the number of marked sub-expressions in the regular
187
  expression that was matched if `*this` represents the result of a
188
- successful match. Otherwise returns `0`. The state of a `match_results`
189
- object can be modified only by passing that object to `regex_match` or
190
- `regex_search`. Sections  [[re.alg.match]] and  [[re.alg.search]]
191
- specify the effects of those algorithms on their `match_results`
192
- arguments.
 
193
 
194
  ``` cpp
195
  size_type max_size() const;
196
  ```
197
 
@@ -282,69 +283,76 @@ sub-expressions stored in `*this`.
282
 
283
  ### `match_results` formatting <a id="re.results.form">[[re.results.form]]</a>
284
 
285
  ``` cpp
286
  template <class OutputIter>
287
- OutputIter format(OutputIter out,
 
288
  const char_type* fmt_first, const char_type* fmt_last,
289
- regex_constants::match_flag_type flags =
290
- regex_constants::format_default) const;
291
  ```
292
 
293
- *Requires:*  ready() == true and `OutputIter` shall satisfy the
294
  requirements for an Output Iterator ([[output.iterators]]).
295
 
296
  *Effects:* Copies the character sequence \[`fmt_first`, `fmt_last`) to
297
  OutputIter `out`. Replaces each format specifier or escape sequence in
298
  the copied range with either the character(s) it represents or the
299
  sequence of characters within `*this` to which it refers. The bitmasks
300
  specified in `flags` determine which format specifiers and escape
301
  sequences are recognized.
302
 
303
- *Returns:*  `out`.
304
 
305
  ``` cpp
306
  template <class OutputIter, class ST, class SA>
307
- OutputIter format(OutputIter out,
 
308
  const basic_string<char_type, ST, SA>& fmt,
309
- regex_constants::match_flag_type flags =
310
- regex_constants::format_default) const;
311
  ```
312
 
313
- *Effects:* Equivalent to `return format(out, fmt.data(),`
314
- `fmt.data() + fmt.size(), flags)`.
 
 
 
315
 
316
  ``` cpp
317
  template <class ST, class SA>
318
- basic_string<char_type, ST, SA>
319
- format(const basic_string<char_type, ST, SA>& fmt,
320
- regex_constants::match_flag_type flags =
321
- regex_constants::format_default) const;
322
  ```
323
 
324
  *Requires:* `ready() == true`.
325
 
326
  *Effects:* Constructs an empty string `result` of type
327
- `basic_string<char_type, ST, SA>` and calls
328
- `format(back_inserter(result), fmt, flags)`.
329
 
330
- *Returns:*  `result`.
 
 
 
 
331
 
332
  ``` cpp
333
- string_type
334
- format(const char_type* fmt,
335
- regex_constants::match_flag_type flags =
336
- regex_constants::format_default) const;
337
  ```
338
 
339
  *Requires:* `ready() == true`.
340
 
341
- *Effects:*  Constructs an empty string `result` of type `string_type`
342
- and
343
- calls`format(back_inserter(result), fmt, fmt + char_traits<char_type>::length(fmt), flags)`.
344
 
345
- *Returns:*  `result`.
 
 
 
 
346
 
347
  ### `match_results` allocator <a id="re.results.all">[[re.results.all]]</a>
348
 
349
  ``` cpp
350
  allocator_type get_allocator() const;
@@ -360,23 +368,23 @@ recent replacement.
360
  void swap(match_results& that);
361
  ```
362
 
363
  *Effects:* Swaps the contents of the two sequences.
364
 
365
- `*this` contains the sequence of matched sub-expressions that were in
366
- `that`, `that` contains the sequence of matched sub-expressions that
367
- were in `*this`.
368
 
369
  *Complexity:* Constant time.
370
 
371
  ``` cpp
372
  template <class BidirectionalIterator, class Allocator>
373
  void swap(match_results<BidirectionalIterator, Allocator>& m1,
374
  match_results<BidirectionalIterator, Allocator>& m2);
375
  ```
376
 
377
- *Effects:* `m1.swap(m2)`.
378
 
379
  ### `match_results` non-member functions <a id="re.results.nonmember">[[re.results.nonmember]]</a>
380
 
381
  ``` cpp
382
  template <class BidirectionalIterator, class Allocator>
@@ -394,11 +402,12 @@ returns `true` only if:
394
  - `m1.prefix() == m2.prefix()`,
395
  - `m1.size() == m2.size() && equal(m1.begin(), m1.end(), m2.begin())`,
396
  and
397
  - `m1.suffix() == m2.suffix()`.
398
 
399
- The algorithm `equal` is defined in Clause  [[algorithms]].
 
400
 
401
  ``` cpp
402
  template <class BidirectionalIterator, class Allocator>
403
  bool operator!=(const match_results<BidirectionalIterator, Allocator>& m1,
404
  const match_results<BidirectionalIterator, Allocator>& m2);
 
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
19
  functions from a `match_results` object that is not ready are undefined.
20
 
21
  The `sub_match` object stored at index 0 represents sub-expression 0,
22
  i.e., the whole match. In this case the `sub_match` member `matched` is
23
+ always `true`. The `sub_match` object stored at index `n` denotes what
24
  matched the marked sub-expression `n` within the matched expression. If
25
  the sub-expression `n` participated in a regular expression match then
26
+ the `sub_match` member `matched` evaluates to `true`, and members
27
+ `first` and `second` denote the range of characters \[`first`, `second`)
28
+ which formed that match. Otherwise `matched` is `false`, and members
29
+ `first` and `second` point to the end of the sequence that was searched.
30
+
31
+ [*Note 1*: The `sub_match` objects representing different
32
+ sub-expressions that did not participate in a regular expression match
33
+ need not be distinct. — *end note*]
34
 
35
  ``` cpp
36
  namespace std {
37
  template <class BidirectionalIterator,
38
  class Allocator = allocator<sub_match<BidirectionalIterator>>>
39
  class match_results {
40
  public:
41
+ using value_type = sub_match<BidirectionalIterator>;
42
+ using const_reference = const value_type&;
43
+ using reference = value_type&;
44
+ using const_iterator = {implementation-defined};
45
+ using iterator = const_iterator;
46
+ using difference_type =
47
+ typename iterator_traits<BidirectionalIterator>::difference_type;
48
+ using size_type = typename allocator_traits<Allocator>::size_type;
49
+ using allocator_type = Allocator;
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();
61
 
62
+ // [re.results.state], state
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;
74
  const_reference operator[](size_type n) const;
75
 
 
78
  const_iterator begin() const;
79
  const_iterator end() const;
80
  const_iterator cbegin() const;
81
  const_iterator cend() const;
82
 
83
+ // [re.results.form], format
84
  template <class OutputIter>
85
  OutputIter
86
  format(OutputIter out,
87
  const char_type* fmt_first, const char_type* fmt_last,
88
+ regex_constants::match_flag_type flags = regex_constants::format_default) const;
 
89
  template <class OutputIter, class ST, class SA>
90
  OutputIter
91
  format(OutputIter out,
92
  const basic_string<char_type, ST, SA>& fmt,
93
+ regex_constants::match_flag_type flags = regex_constants::format_default) const;
 
94
  template <class ST, class SA>
95
  basic_string<char_type, ST, SA>
96
  format(const basic_string<char_type, ST, SA>& fmt,
97
+ regex_constants::match_flag_type flags = regex_constants::format_default) const;
 
98
  string_type
99
  format(const char_type* fmt,
100
+ regex_constants::match_flag_type flags = regex_constants::format_default) const;
 
101
 
102
+ // [re.results.all], allocator
103
  allocator_type get_allocator() const;
104
 
105
+ // [re.results.swap], swap
106
  void swap(match_results& that);
107
  };
108
  }
109
  ```
110
 
 
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.
 
183
  size_type size() const;
184
  ```
185
 
186
  *Returns:* One plus the number of marked sub-expressions in the regular
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
 
 
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
301
  specified in `flags` determine which format specifiers and escape
302
  sequences are recognized.
303
 
304
+ *Returns:* `out`.
305
 
306
  ``` cpp
307
  template <class OutputIter, class ST, class SA>
308
+ OutputIter format(
309
+ OutputIter out,
310
  const basic_string<char_type, ST, SA>& fmt,
311
+ regex_constants::match_flag_type flags = regex_constants::format_default) const;
 
312
  ```
313
 
314
+ *Effects:* Equivalent to:
315
+
316
+ ``` cpp
317
+ return format(out, fmt.data(), fmt.data() + fmt.size(), flags);
318
+ ```
319
 
320
  ``` cpp
321
  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
333
+ format(back_inserter(result), fmt, flags);
334
+ ```
335
+
336
+ *Returns:* `result`.
337
 
338
  ``` cpp
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;
 
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>
381
  void swap(match_results<BidirectionalIterator, Allocator>& m1,
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>
 
402
  - `m1.prefix() == m2.prefix()`,
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);