Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/libs/regex/doc/regex_iterator.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago
updated boost from 1_33_1 to 1_34_1
File size: 19.7 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2	<html>
3	<head>
4	<title>Boost.Regex: regex_iterator</title>
5	<meta name="generator" content="HTML Tidy, see www.w3.org">
6	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7	<link href="../../../boost.css" type="text/css" rel="stylesheet">
8	</head>
9	<body>
10	<p></p>
11	<table id="Table1" cellspacing="1" cellpadding="1" width="100%" border="0">
12	<tr>
13	<td valign="top" width="300">
14	<h3><a href="../../../index.htm"><img height="86" alt="C++ Boost" src="../../../boost.png" width="277" border="0"></a></h3>
15	</td>
16	<td width="353">
17	<h1 align="center">Boost.Regex</h1>
18	<h2 align="center">regex_iterator</h2>
19	</td>
20	<td width="50">
21	<h3><a href="index.html"><img height="45" alt="Boost.Regex Index" src="uarrow.gif" width="43" border="0"></a></h3>
22	</td>
23	</tr>
24	</table>
25	<br>
26	<br>
27	<hr>
28	<h3>Contents</h3>
29	<dl class="index">
30	<dt><a href="#synopsis">Synopsis</a> <dt><a href="#description">Description</a> <dt><a href="#examples">
31	Examples</a></dt>
32	</dl>
33	<h3><a name="synopsis"></a>Synopsis</h3>
34	<p>The iterator type regex_iterator will enumerate all of the regular expression
35	matches found in some sequence: dereferencing a regex_iterator yields a
36	reference to a <a href="match_results.html">match_results</a> object.</p>
37	<pre>
38	template <class BidirectionalIterator,
39	class charT = iterator_traits<BidirectionalIterator>::value_type,
40	class traits = regex_traits<charT> >
41	class regex_iterator
42	{
43	public:
44	typedef <A href="basic_regex.html">basic_regex</A><charT, traits> regex_type;
45	typedef <A href="match_results.html">match_results</A><BidirectionalIterator> value_type;
46	typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
47	typedef const value_type* pointer;
48	typedef const value_type& reference;
49	typedef std::forward_iterator_tag iterator_category;
50
51	<A href="#c1">regex_iterator</A>();
52	<A href="#c2">regex_iterator</A>(BidirectionalIterator a, BidirectionalIterator b,
53	const regex_type& re,
54	<A href="match_flag_type.html">match_flag_type</A> m = match_default);
55	<A href="#c3">regex_iterator</A>(const regex_iterator&);
56	regex_iterator& <A href="#o1">operator</A>=(const regex_iterator&);
57	bool <A href="#o2">operator</A>==(const regex_iterator&)const;
58	bool <A href="#o3">operator</A>!=(const regex_iterator&)const;
59	const value_type& <A href="#o4">operator</A>*()const;
60	const value_type* <A href="#o5">operator</A>->()const;
61	regex_iterator& <A href="#o6">operator</A>++();
62	regex_iterator <A href="#o7">operator</A>++(int);
63	};
64
65	typedef
66	regex_iterator<const
67
68	char*> cregex_iterator; typedef regex_iterator<std::string::const_iterator>
69	sregex_iterator; #ifndef BOOST_NO_WREGEX
70	typedef regex_iterator<const
71	wchar_t*> wcregex_iterator; typedef regex_iterator<std::wstring::const_iterator>
72	wsregex_iterator; #endif template
73	<class
74
75	charT, class traits> regex_iterator<const charT*,
76	charT, traits>
77	<A href="#make_regex_iterator">make_regex_iterator</A>(const charT* p, const basic_regex<charT, traits>& e, regex_constants::match_flag_type m = regex_constants::match_default); template <class
78
79	charT, class traits, class ST, class SA> regex_iterator<typename std::basic_string<charT,
80	ST, SA>::const_iterator, charT, traits>
81	<A href="#make_regex_iterator">make_regex_iterator</A>(const std::basic_string<charT, ST, SA>& p, const basic_regex<charT, traits>& e, regex_constants::match_flag_type m = regex_constants::match_default);
82
83	</pre>
84	<h3><a name="description"></a>Description</h3>
85	<p>A regex_iterator is constructed from a pair of iterators, and enumerates all
86	occurrences of a regular expression within that iterator range.</p>
87	<pre><A name=c1></A>
88	regex_iterator();
89	</pre>
90	<b></b>
91	<p><b>Effects:</b> constructs an end of sequence regex_iterator.</p>
92	<pre><A name=c2></A>regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
93	const regex_type& re,
94	<A href="match_flag_type.html">match_flag_type</A> m = match_default);
95	</pre>
96	<b></b>
97	<p><b>Effects:</b> constructs a regex_iterator that will enumerate all occurrences
98	of the expression <em>re</em>, within the sequence <em>[a,b)</em>, and found
99	using match flags <em>m</em>.  The object <em>re</em> must exist for the
100	lifetime of the regex_iterator.</p>
101	<P><STRONG>Throws:</STRONG> <CODE>std::runtime_error</CODE> if the complexity of
102	matching the expression against an N character string begins to exceed O(N<SUP>2</SUP>),
103	or if the program runs out of stack space while matching the expression (if
104	Boost.regex is <A href="configuration.html">configured</A> in recursive mode),
105	or if the matcher exhausts it's permitted memory allocation (if Boost.regex is <A href="configuration.html">
106	configured</A> in non-recursive mode).</P>
107	<pre><A name=c3></A>
108	regex_iterator(const regex_iterator& that);
109	</pre>
110	<b></b>
111	<p><b>Effects:</b> constructs a copy of <code>that</code>.</p>
112	<b></b>
113	<p><b>Postconditions:</b> <code>*this == that</code>.</p>
114	<pre><A name=o1></A>
115	regex_iterator& operator=(const regex_iterator&);
116	</pre>
117	<b></b>
118	<p><b>Effects:</b> sets <code>*this</code> equal to those in <code>that</code>.</p>
119	<b></b>
120	<p><b>Postconditions:</b> <code>*this == that</code>.</p>
121	<pre><A name=o2></A>
122	bool operator==(const regex_iterator& that)const;
123	</pre>
124	<b></b>
125	<p><b>Effects:</b> returns true if *this is equal to that.</p>
126	<pre><A name=o3></A>
127	bool operator!=(const regex_iterator&)const;
128	</pre>
129	<b></b>
130	<p><b>Effects:</b> returns <code>!(*this == that)</code>.</p>
131	<pre><A name=o4></A>
132	const value_type& operator*()const;
133	</pre>
134	<p><b>Effects:</b> dereferencing a regex_iterator object <em>it</em> yields a
135	const reference to a <a href="match_results.html">match_results</a> object,
136	whose members are set as follows:</p>
137	<p></p>
138	<table id="Table2" cellspacing="1" cellpadding="7" width="624" border="1">
139	<tbody>
140	<tr>
141	<td valign="top" width="50%"><b></b>
142	<p><b>Element</b></p>
143	</td>
144	<td valign="top" width="50%"><b></b>
145	<p><b>Value</b></p>
146	</td>
147	</tr>
148	<tr>
149	<td valign="top" width="50%">
150	<p>(*it).size()</p>
151	</td>
152	<td valign="top" width="50%">
153	<p>re.mark_count()</p>
154	</td>
155	</tr>
156	<tr>
157	<td valign="top" width="50%">
158	<p>(*it).empty()</p>
159	</td>
160	<td valign="top" width="50%">
161	<p>false</p>
162	</td>
163	</tr>
164	<tr>
165	<td valign="top" width="50%">
166	<p>(*it).prefix().first</p>
167	</td>
168	<td valign="top" width="50%">
169	<p>The end of the last match found, or the start of the underlying sequence if
170	this is the first match enumerated</p>
171	</td>
172	</tr>
173	<tr>
174	<td valign="top" width="50%">
175	<p>(*it).prefix().last</p>
176	</td>
177	<td valign="top" width="50%">
178	<p>The same as the start of the match found:<BR>
179	(*it)[0].first</p>
180	</td>
181	</tr>
182	<tr>
183	<td valign="top" width="50%">
184	<p>(*it).prefix().matched</p>
185	</td>
186	<td valign="top" width="50%">
187	<p>True if the prefix did not match an empty string:<BR>
188	(it).prefix().first != (it).prefix().second</p>
189	</td>
190	</tr>
191	<tr>
192	<td valign="top" width="50%">
193	<p>(*it).suffix().first</p>
194	</td>
195	<td valign="top" width="50%">
196	<p>The same as the end of the match found:<BR>
197	(*it)[0].second</p>
198	</td>
199	</tr>
200	<tr>
201	<td valign="top" width="50%">
202	<p>(*it).suffix().last</p>
203	</td>
204	<td valign="top" width="50%">
205	<p>The end of the underlying sequence.</p>
206	</td>
207	</tr>
208	<tr>
209	<td valign="top" width="50%">
210	<p>(*it).suffix().matched</p>
211	</td>
212	<td valign="top" width="50%">
213	<p>True if the suffix did not match an empty string:<BR>
214	(it).suffix().first != (it).suffix().second</p>
215	</td>
216	</tr>
217	<tr>
218	<td valign="top" width="50%">
219	<p>(*it)[0].first</p>
220	</td>
221	<td valign="top" width="50%">
222	<p>The start of the sequence of characters that matched the regular expression</p>
223	</td>
224	</tr>
225	<tr>
226	<td valign="top" width="50%">
227	<p>(*it)[0].second</p>
228	</td>
229	<td valign="top" width="50%">
230	<p>The end of the sequence of characters that matched the regular expression</p>
231	</td>
232	</tr>
233	<tr>
234	<td valign="top" width="50%">
235	<p>(*it)[0].matched</p>
236	</td>
237	<td valign="top" width="50%">
238	<p><code>true</code> if a full match was found, and <code>false</code> if it was a
239	partial match (found as a result of the <code>match_partial</code> flag being
240	set).</p>
241	</td>
242	</tr>
243	<tr>
244	<td valign="top" width="50%">
245	<p>(*it)[n].first</p>
246	</td>
247	<td valign="top" width="50%">
248	<p>For all integers n < (*it).size(), the start of the sequence that matched
249	sub-expression <i>n</i>. Alternatively, if sub-expression n did not participate
250	in the match, then <i>last</i>.</p>
251	</td>
252	</tr>
253	<tr>
254	<td valign="top" width="50%">
255	<p>(*it)[n].second</p>
256	</td>
257	<td valign="top" width="50%">
258	<p>For all integers n < (*it).size(), the end of the sequence that matched
259	sub-expression <i>n</i>. Alternatively, if sub-expression n did not participate
260	in the match, then <i>last</i>.</p>
261	</td>
262	</tr>
263	<tr>
264	<td valign="top" width="50%">
265	<p>(*it)[n].matched</p>
266	</td>
267	<td valign="top" width="50%">
268	<p>For all integers n < (*it).size(), true if sub-expression <i>n</i> participated
269	in the match, false otherwise.</p>
270	</td>
271	</tr>
272	<tr>
273	<td valign="top" width="50%">(*it).position(n)</td>
274	<td valign="top" width="50%">For all integers n < (*it).size(), then the
275	distance from the start of the underlying sequence to the start of
276	sub-expression match <em>n</em>.</td>
277	</tr>
278	</tbody>
279	</table>
280	<br>
281	<br>
282	<pre><A name=o5></A>
283	const value_type* operator->()const;
284	</pre>
285	<b></b>
286	<p><b>Effects:</b> returns <code>&(*this)</code>.</p>
287	<pre><A name=o6></A>
288	regex_iterator& operator++();
289	</pre>
290	<p><strong>Effects:</strong> moves the iterator to the next match in the
291	underlying sequence, or the end of sequence iterator if none if found.
292	When the last match found matched a zero length string, then the
293	regex_iterator will find the next match as follows: if there exists a non-zero
294	length match that starts at the same location as the last one, then returns it,
295	otherwise starts looking for the next (possibly zero length) match from one
296	position to the right of the last match.</p>
297	<P><STRONG>Throws:</STRONG> <CODE>std::runtime_error</CODE> if the complexity of
298	matching the expression against an N character string begins to exceed O(N<SUP>2</SUP>),
299	or if the program runs out of stack space while matching the expression (if
300	Boost.regex is <A href="configuration.html">configured</A> in recursive mode),
301	or if the matcher exhausts it's permitted memory allocation (if Boost.regex is <A href="configuration.html">
302	configured</A> in non-recursive mode).</P>
303	<b></b>
304	<p><b>Returns:</b> <code>*this</code>.</p>
305	<pre><A name=o7></A>
306	regex_iterator operator++(int);
307	</pre>
308	<b></b>
309	<p><b>Effects:</b> constructs a copy <code>result</code> of <code>*this</code>,
310	then calls <code>++(*this)</code>.</p>
311	<b></b>
312	<p><b>Returns:</b> <code>result</code>.</p>
313	<PRE><A name=make_regex_iterator></A>template <class charT, class traits> regex_iterator<const charT*, charT, traits>
314	make_regex_iterator(const charT*
315	p, const basic_regex<charT,
316	traits>& e, regex_constants::match_flag_type m
317	= regex_constants::match_default); template <class
318
319	charT, class traits, class ST, class SA> regex_iterator<typename std::basic_string<charT,
320	ST, SA>::const_iterator, charT, traits>
321	make_regex_iterator(const std::basic_string<charT, ST, SA>& p,
322	const basic_regex<charT, traits>& e,
323	regex_constants::match_flag_type m = regex_constants::match_default);
324	</PRE>
325	<P><STRONG>Effects:</STRONG> returns an iterator that enumerates all occurences of
326	expression <EM>e</EM> in text <EM>p</EM> using match_flags <EM>m</EM>.</P>
327	<h3><a name=examples></a>Examples</h3>
328	<p>The following <a href="../example/snippets/regex_iterator_example.cpp">example</a>
329	takes a C++ source file and builds up an index of class names, and the location
330	of that class in the file.</p>
331	<pre>
332	<font color="#008040">#include <string></font>
333	<font color="#008040">#include <map></font>
334	<font color="#008040">#include <fstream></font>
335	<font color="#008040">#include <iostream></font>
336	<font color="#008040">#include <boost/regex.hpp></font>
337
338	<b>using</b> <b>namespace</b> std;
339
340	<i><font color="#000080">// purpose:</font></i>
341	<i><font color=
342	#000080>// takes the contents of a file in the form of a string</font></i>
343	<i><font color=
344	#000080>// and searches for all the C++ class definitions, storing</font></i>
345	<i><font color=
346	#000080>// their locations in a map of strings/int's</font></i>
347
348	<b>typedef</b> std::map<std::string, std::string::difference_type, std::less<std::string> > map_type;
349
350	<b>const</b> <b>char</b>* re =
351	<i><font color=
352	#000080>// possibly leading whitespace: </font></i>
353	<font color="#0000ff">"^[[:space:]]*"</font>
354	<i><font color=
355	#000080>// possible template declaration:</font></i>
356	<font color=
357	#0000ff>"(template[[:space:]]<[^;:{]+>[[:space:]])?"</font>
358	<i><font color="#000080">// class or struct:</font></i>
359	<font color="#0000ff">"(class\|struct)[[:space:]]*"</font>
360	<i><font color=
361	#000080>// leading declspec macros etc:</font></i>
362	<font color="#0000ff">"("</font>
363	<font color="#0000ff">"\\<\\w+\\>"</font>
364	<font color="#0000ff">"("</font>
365	<font color="#0000ff">"[[:blank:]]\\([^)]\\)"</font>
366	<font color="#0000ff">")?"</font>
367	<font color="#0000ff">"[[:space:]]*"</font>
368	<font color="#0000ff">")*"</font>
369	<i><font color="#000080">// the class name</font></i>
370	<font color="#0000ff">"(\\<\\w\\>)[[:space:]]"</font>
371	<i><font color=
372	#000080>// template specialisation parameters</font></i>
373	<font color="#0000ff">"(<[^;:{]+>)?[[:space:]]*"</font>
374	<i><font color="#000080">// terminate in { or :</font></i>
375	<font color="#0000ff">"(\\{\|:[^;\\{()]*\\{)"</font>;
376
377
378	boost::regex expression(re);
379	map_type class_index;
380
381	<b>bool</b> regex_callback(<b>const</b> boost::match_results<std::string::const_iterator>& what)
382	{
383	<i><font color=
384	#000080>// what[0] contains the whole string</font></i>
385	<i><font color=
386	#000080>// what[5] contains the class name.</font></i>
387	<i><font color=
388	#000080>// what[6] contains the template specialisation if any.</font></i>
389	<i><font color=
390	#000080>// add class name and position to map:</font></i>
391	class_index[what[<font color=
392	#0000a0>5</font>].str() + what[<font color=
393	#0000a0>6</font>].str()] = what.position(<font color=
394	#0000a0>5</font>);
395	<b>return</b> <b>true</b>;
396	}
397
398	<b>void</b> load_file(std::string& s, std::istream& is)
399	{
400	s.erase();
401	s.reserve(is.rdbuf()->in_avail());
402	<b>char</b> c;
403	<b>while</b>(is.get(c))
404	{
405	<b>if</b>(s.capacity() == s.size())
406	s.reserve(s.capacity() * <font color="#0000a0">3</font>);
407	s.append(<font color="#0000a0">1</font>, c);
408	}
409	}
410
411	<b>int</b> main(<b>int</b> argc, <b>const</b> <b>char</b>** argv)
412	{
413	std::string text;
414	<b>for</b>(<b>int</b> i = <font color=
415	#0000a0>1</font>; i < argc; ++i)
416	{
417	cout << <font color=
418	#0000ff>"Processing file "</font> << argv[i] << endl;
419	std::ifstream fs(argv[i]);
420	load_file(text, fs);
421	<i><font color=
422	#000080>// construct our iterators:</font></i>
423	boost::sregex_iterator m1(text.begin(), text.end(), expression);
424	boost::sregex_iterator m2;
425	std::for_each(m1, m2, &regex_callback);
426	<i><font color="#000080">// copy results:</font></i>
427	cout << class_index.size() << <font color=
428	#0000ff>" matches found"</font> << endl;
429	map_type::iterator c, d;
430	c = class_index.begin();
431	d = class_index.end();
432	<b>while</b>(c != d)
433	{
434	cout << <font color=
435	#0000ff>"class \""</font> << (*c).first << <font
436	color=
437	#0000ff>"\" found at index: "</font> << (*c).second << endl;
438	++c;
439	}
440	class_index.erase(class_index.begin(), class_index.end());
441	}
442	<b>return</b> <font color="#0000a0">0</font>;
443	}
444	</pre>
445	<hr>
446	<p>Revised
447	<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
448	06 Jan 05
449	<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
450	<p><i>© Copyright John Maddock 1998-
451	<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2005<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
452	<P><I>Use, modification and distribution are subject to the Boost Software License,
453	Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
454	or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
455	</body>
456	</html>

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

Download in other formats: