1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Boost.Regex: class match_results</title>
<meta content="HTML Tidy, see www.w3.org" name="generator">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK href="../../../boost.css" type="text/css" rel="stylesheet"></head>
<body>
<p></p>
<table id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
<tr>
<td vAlign="top" width="300">
<h3><A href="../../../index.htm"><IMG height="86" alt="C++ Boost" src="../../../boost.png" width="277" border="0"></A></h3>
</td>
<td width="353">
<h1 align="center">Boost.Regex</h1>
<h2 align="center">class match_results</h2>
</td>
<td width="50">
<h3><A href="index.html"><IMG height="45" alt="Boost.Regex Index" src="uarrow.gif" width="43" border="0"></A></h3>
</td>
</tr>
</table>
<br>
<br>
<hr>
<h3>Contents</h3>
<dl class="index">
<dt><A href="#synopsis">Synopsis</A> <dt><A href="#description">Description</A> </dt>
</dl>
<h3><a name="synopsis"></a>Synopsis</h3>
<p>#include <<A href="../../../boost/regex.hpp">boost/regex.hpp</A>></p>
<p>Regular expressions are different from many simple pattern-matching algorithms
in that as well as finding an overall match they can also produce
sub-expression matches: each sub-expression being delimited in the pattern by a
pair of parenthesis (...). There has to be some method for reporting
sub-expression matches back to the user: this is achieved this by defining a
class <i>match_results</i> that acts as an indexed collection of sub-expression
matches, each sub-expression match being contained in an object of type <i><A href="sub_match.html">
sub_match</A></i> .</p>
<p>Template class match_results denotes a collection of character sequences
representing the result of a regular expression match. Objects of type
match_results are passed to the algorithms <A href="regex_match.html">regex_match</A>
and <A href="regex_search.html">regex_search</A>, and are returned by the
iterator <A href="regex_iterator.html">regex_iterator</A> . Storage for
the collection is allocated and freed as necessary by the member functions of
class match_results.</p>
<p>The template class match_results conforms to the requirements of a Sequence, as
specified in (lib.sequence.reqmts), except that only operations defined for
const-qualified Sequences are supported.</p>
<p>Class template match_results is most commonly used as one of the typedefs
cmatch, wcmatch, smatch, or wsmatch:</p>
<pre>template <class BidirectionalIterator,
class Allocator = allocator<sub_match<BidirectionalIterator> >
class match_results;
typedef match_results<const char*> cmatch;
typedef match_results<const wchar_t*> wcmatch;
typedef match_results<string::const_iterator> smatch;
typedef match_results<wstring::const_iterator> wsmatch;
template <class BidirectionalIterator,
class Allocator = allocator<sub_match<BidirectionalIterator> >
class match_results
{
public:
typedef sub_match<BidirectionalIterator> value_type;
typedef const value_type& const_reference;
typedef const_reference reference;
typedef implementation defined const_iterator;
typedef const_iterator iterator;
typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
typedef typename Allocator::size_type size_type;
typedef Allocator allocator_type;
typedef typename iterator_traits<BidirectionalIterator>::value_type char_type;
typedef basic_string<char_type> string_type;
// construct/copy/destroy:
explicit <A href="#c1" >match_results</A>(const Allocator& a = Allocator());
<A href="#c2" >match_results</A>(const match_results& m);
<A href="#c3" >match_results</A>& <A href="#c3" >operator</A>=(const match_results& m);
~match_results();
// size:
size_type <A href="#m1" >size</A>() const;
size_type <A href="#m2" >max_size</A>() const;
bool <A href="#m3" >empty</A>() const;
// element access:
difference_type <A href="#m4" >length</A>(int sub = 0) const;
difference_type <A href="#m5" >position</A>(unsigned int sub = 0) const;
string_type <A href="#m6" >str</A>(int sub = 0) const;
const_reference <A href="#m7" >operator</A>[](int n) const;
const_reference <A href="#m8" >prefix</A>() const;
const_reference <A href="#m9" >suffix</A>() const;
const_iterator <A href="#m10" >begin</A>() const;
const_iterator <A href="#m11" >end</A>() const;
// format:
template <class OutputIterator>
OutputIterator <A href="#m12" >format</A>(OutputIterator out,
const string_type& fmt,
match_flag_type flags = format_default) const;
string_type <A href="#m13" >format</A>(const string_type& fmt,
match_flag_type flags = format_default) const;
allocator_type <A href="#m14" >get_allocator</A>() const;
void <A href="#m15" >swap</A>(match_results& that);
#ifdef BOOST_REGEX_MATCH_EXTRA
typedef typename value_type::capture_sequence_type <A href="#m16" >capture_sequence_type</A>;
const capture_sequence_type& <A href="#m17" >captures</A>(std::size_t i)const;
#endif
};
template <class BidirectionalIterator, class Allocator>
bool <A href="#n1" >operator</A> == (const match_results<BidirectionalIterator, Allocator>& m1,
const match_results<BidirectionalIterator, Allocator>& m2);
template <class BidirectionalIterator, class Allocator>
bool <A href="#n2" >operator</A> != (const match_results<BidirectionalIterator, Allocator>& m1,
const match_results<BidirectionalIterator, Allocator>& m2);
template <class charT, class traits, class BidirectionalIterator, class Allocator>
basic_ostream<charT, traits>&
<A href="#n3" >operator</A> << (basic_ostream<charT, traits>& os,
const match_results<BidirectionalIterator, Allocator>& m);
template <class BidirectionalIterator, class Allocator>
void <A href="#n4" >swap</A>(match_results<BidirectionalIterator, Allocator>& m1,
match_results<BidirectionalIterator, Allocator>& m2);
</pre>
<h3><a name="description"></a>Description</h3>
<h4>match_results constructors</h4>
<p>In all <code>match_results</code> constructors, a copy of the Allocator
argument is used for any memory allocation performed by the constructor or
member functions during the lifetime of the object.</p>
<pre><A name=c1></A>
match_results(const Allocator& a = Allocator());
</pre>
<b></b>
<p><b>Effects:</b> Constructs an object of class match_results. The postconditions
of this function are indicated in the table:</p>
<p align="center"></p>
<center>
<table id="Table2" cellSpacing="1" cellPadding="7" width="624" border="1">
<tbody>
<tr>
<td vAlign="top" width="50%"><b></b>
<p><b>Element</b></p>
</td>
<td vAlign="top" width="50%"><b></b>
<p><b>Value</b></p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>empty()</p>
</td>
<td vAlign="top" width="50%">
<p>true</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>size()</p>
</td>
<td vAlign="top" width="50%">
<p>0</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>str()</p>
</td>
<td vAlign="top" width="50%">
<p>basic_string<charT>()</p>
</td>
</tr>
</tbody></table>
</center>
<p> </p>
<pre><A name=c2></A>
match_results(const match_results& m);
</pre>
<b></b>
<p><b>Effects:</b> Constructs an object of class match_results, as a copy of m.</p>
<pre><A name=c3></A>
match_results& operator=(const match_results& m);
</pre>
<b></b>
<p><b>Effects:</b> Assigns m to *this. The postconditions of this function are
indicated in the table:</p>
<p align="center"></p>
<center>
<table id="Table3" cellSpacing="1" cellPadding="7" width="624" border="1">
<tbody>
<tr>
<td vAlign="top" width="50%"><b></b>
<p><b>Element</b></p>
</td>
<td vAlign="top" width="50%"><b></b>
<p><b>Value</b></p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>empty()</p>
</td>
<td vAlign="top" width="50%">
<p>m.empty().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>size()</p>
</td>
<td vAlign="top" width="50%">
<p>m.size().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>str(n)</p>
</td>
<td vAlign="top" width="50%">
<p>m.str(n) for all integers n < m.size().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>prefix()</p>
</td>
<td vAlign="top" width="50%">
<p>m.prefix().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>suffix()</p>
</td>
<td vAlign="top" width="50%">
<p>m.suffix().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>(*this)[n]</p>
</td>
<td vAlign="top" width="50%">
<p>m[n] for all integers n < m.size().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>length(n)</p>
</td>
<td vAlign="top" width="50%">
<p>m.length(n) for all integers n < m.size().</p>
</td>
</tr>
<tr>
<td vAlign="top" width="50%">
<p>position(n)</p>
</td>
<td vAlign="top" width="50%">
<p>m.position(n) for all integers n < m.size().</p>
</td>
</tr>
</tbody></table>
</center>
<h4>match_results size</h4>
<pre><A name=m1></A>
size_type size()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns the number of sub_match elements stored in *this; that
is the number of marked sub-expressions in the regular expression that was
matched plus one.</p>
<pre><A name=m2></A>
size_type max_size()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns the maximum number of sub_match elements that can be
stored in *this.</p>
<pre><A name=m3></A>
bool empty()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns <code>size() == 0</code>.</p>
<h4>match_results element access</h4>
<pre><A name=m4></A>
difference_type length(int sub = 0)const;
</pre>
<b></b>
<p><b>Effects:</b> Returns the length of sub-expression <EM>sub</EM>, that is to
say: <code>(*this)[sub].length()</code>.</p>
<pre><A name=m5></A>
difference_type position(unsigned int sub = 0)const;
</pre>
<b></b>
<p><b>Effects:</b> Returns the starting location of sub-expression <EM>sub</EM>,
or -1 if <EM>sub</EM> was not matched <code>.</code></p>
<pre><A name=m6></A>
string_type str(int sub = 0)const;
</pre>
<b></b>
<p><b>Effects:</b> Returns sub-expression <EM>sub</EM> as a string: <code>string_type((*this)[sub]).</code></p>
<pre><A name=m7></A>
const_reference operator[](int n) const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a reference to the <code>sub_match</code> object
representing the character sequence that matched marked sub-expression <i>n</i>.
If <code>n == 0</code> then returns a reference to a <code>sub_match</code> object
representing the character sequence that matched the whole regular
expression. If <EM>n</EM> is out of range, or if <EM>n</EM> is an
unmatched sub-expression, then returns a sub_match object whose <EM>matched</EM>
member is <EM>false</EM>.</p>
<pre><A name=m8></A>
const_reference prefix()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a reference to the <code>sub_match</code> object
representing the character sequence from the start of the string being
matched/searched, to the start of the match found.</p>
<pre><A name=m9></A>
const_reference suffix()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a reference to the <code>sub_match</code> object
representing the character sequence from the end of the match found to the end
of the string being matched/searched.</p>
<pre><A name=m10></A>
const_iterator begin()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a starting iterator that enumerates over all the marked
sub-expression matches stored in *this.</p>
<pre><A name=m11></A>
const_iterator end()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a terminating iterator that enumerates over all the
marked sub-expression matches stored in *this.</p>
<h4><A name="format"></A>match_results reformatting</h4>
<pre><A name=m12></A>template <class OutputIterator>
OutputIterator format(OutputIterator out,
const string_type& fmt,
<A href="match_flag_type.html" >match_flag_type</A> flags = format_default);
</pre>
<b></b>
<p><b>Requires:</b> The type OutputIterator conforms to the Output Iterator
requirements (24.1.2).</p>
<b></b>
<p><b>Effects:</b> Copies the character sequence <i>[fmt.begin(), fmt.end())</i> to
OutputIterator <i>out</i>. For each format specifier or escape sequence in <i>fmt</i>,
replace that sequence with either the character(s) it represents, or the
sequence of characters within *this to which it refers. The bitmasks specified
in <i><A href="match_flag_type.html">flags</A></i> determines what <A href="format_syntax.html">
format specifiers or escape sequences are recognized</A>, by default this is
the format used by ECMA-262, ECMAScript Language Specification, Chapter 15 part
5.4.11 String.prototype.replace.</p>
<b></b>
<p><b>Returns:</b> <i>out</i>.</p>
<pre><A name=m13></A>
string_type format(const string_type& fmt,
<A href="match_flag_type.html" >match_flag_type</A> flags = format_default);
</pre>
<b></b>
<p><b>Effects:</b> Returns a copy of the string <i>fmt</i>. For each format
specifier or escape sequence in <i>fmt</i>, replace that sequence with either
the character(s) it represents, or the sequence of characters within *this to
which it refers. The bitmasks specified in <i><A href="match_flag_type.html">flags</A></i>
determines what <A href="format_syntax.html">format specifiers or escape sequences
are recognized</A>, by default this is the format used by ECMA-262,
ECMAScript Language Specification, Chapter 15 part 5.4.11
String.prototype.replace.</p>
<H4>Allocator access</H4>
<pre>allocator_type get_allocator()const;
</pre>
<b></b>
<p><b>Effects:</b> Returns a copy of the Allocator that was passed to the object's
constructor.</p>
<H4><A name="m15"></A>Swap</H4>
<PRE>void swap(match_results& that);
</PRE>
<b></b>
<p><b>Effects:</b> Swaps the contents of the two sequences.</p>
<b></b>
<p><b>Postcondition:</b> <code>*this</code> contains the sequence of matched
sub-expressions that were in <code>that</code>, <code>that</code> contains the
sequence of matched sub-expressions that were in <code>*this</code>.</p>
<b></b>
<p><b>Complexity:</b> constant time.</p>
<H4>Captures</H4>
<PRE><A name=m16></A>typedef typename value_type::capture_sequence_type capture_sequence_type;</PRE>
<P>Defines an implementation-specific type that satisfies the requirements of
a standard library Sequence (21.1.1 including the optional Table 68
operations), whose value_type is a <EM>sub_match<BidirectionalIterator></EM>. This
type happens to be <EM>std::vector<sub_match<BidirectionalIterator> ></EM>,
but you shouldn't actually rely on that.</P>
<PRE><A name=m17></A>const capture_sequence_type& <A href="#m8" >captures</A>(std::size_t i)const; </PRE>
<P><STRONG>Effects:</STRONG> returns a sequence containing all the captures
obtained for sub-expression <EM>i</EM>.</P>
<P><STRONG>Returns:</STRONG> <code>(*this)[i].captures();</code></P>
<P><STRONG>Preconditions:</STRONG> the library must be built and used with
BOOST_REGEX_MATCH_EXTRA defined, and you must pass the flag <A href="match_flag_type.html">
match_extra</A> to the regex matching functions (<A href="regex_match.html">regex_match</A>,
<A href="regex_search.html">regex_search</A>, <A href="regex_iterator.html">regex_iterator</A>
or <A href="regex_token_iterator.html">regex_token_iterator</A>) in order for
this member function to be defined and return useful information.</P>
<P><STRONG>Rationale:</STRONG> Enabling this feature has several consequences:
</P>
<UL>
<LI>
sub_match occupies more memory resulting in complex expressions running out of
memory or stack space more quickly during matching.
<LI>
The matching algorithms are less efficient at handling some features
(independent sub-expressions for example), even when match_extra is not used.
<LI>
The matching algorithms are much less efficient (i.e. slower), when match_extra
is used. Mostly this is down to the extra memory allocations that have to
take place.</LI></UL>
<h4>match_results non-members</h4>
<PRE><A name=n1></A>template <class BidirectionalIterator, class Allocator>
bool operator == (const match_results<BidirectionalIterator, Allocator>& m1,
const match_results<BidirectionalIterator, Allocator>& m2);</PRE>
<P><B>Effects:</B> Compares the two sequences for equality.</P>
<PRE><A name=n2></A>template <class BidirectionalIterator, class Allocator>
bool operator != (const match_results<BidirectionalIterator, Allocator>& m1,
const match_results<BidirectionalIterator, Allocator>& m2);</PRE>
<P><B>Effects:</B> Compares the two sequences for inequality.</P>
<PRE><A name=n3></A>template <class charT, class traits, class BidirectionalIterator, class Allocator>
basic_ostream<charT, traits>&
operator << (basic_ostream<charT, traits>& os,
const match_results<BidirectionalIterator, Allocator>& m);</PRE>
<P><B>Effects:</B> Writes the contents of <EM>m</EM> to the stream <EM>os</EM> as
if by calling <code>os << m.str();</code> Returns <EM>os</EM>..</P>
<PRE><A name=n4></A>template <class BidirectionalIterator, class Allocator>
void swap(match_results<BidirectionalIterator, Allocator>& m1,
match_results<BidirectionalIterator, Allocator>& m2);</PRE>
<P><B>Effects:</B> Swaps the contents of the two sequences.</P>
<p></p>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
24 Oct 2003
<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p><i> Copyright John Maddock 1998-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
<P><I>Use, modification and distribution are subject to the Boost Software License,
Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
</body>
</html>
|
