Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/libs/regex/doc/match_results.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 17 years ago
added boost
File size: 21.8 KB

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

Note: See TracBrowser for help on using the repository browser.

Download in other formats: