Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/regex/doc/regex_grep.html @ 14

Last change on this file since 14 was 12, checked in by landauf, 17 years ago

added boost
File size: 15.7 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>Boost.Regex: Algorithm regex_grep (deprecated)</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 rel="stylesheet" type="text/css" href="../../../boost.css">
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" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
15            </td>
16            <td width="353">
17               <h1 align="center">Boost.Regex</h1>
18               <h2 align="center">Algorithm regex_grep (deprecated)</h2>
19            </td>
20            <td width="50">
21               <h3><a href="index.html"><img height="45" width="43" alt="Boost.Regex Index" src="uarrow.gif" border="0"></a></h3>
22            </td>
23         </tr>
24      </table>
25      <br>
26      <br>
27      <hr>
28      <p>The algorithm regex_grep is deprecated in favor of <a href="regex_iterator.html">regex_iterator</a>
29         which provides a more convenient and standard library friendly interface.</p>
30      <p>The following documentation is taken unchanged from the previous boost release,
31         and will not be updated in future.</p>
32      <hr>
33      <pre>
34#include &lt;<a href="../../../boost/regex.hpp">boost/regex.hpp</a>&gt;
35</pre>
36      <p>regex_grep allows you to search through a bidirectional-iterator range and
37         locate all the (non-overlapping) matches with a given regular expression. The
38         function is declared as:</p>
39      <pre>
40<b>template</b> &lt;<b>class</b> Predicate, <b>class</b> iterator, <b>class</b> charT, <b>class</b> traits&gt;
41<b>unsigned</b> <b>int</b> regex_grep(Predicate foo,
42                         iterator first,
43                         iterator last,
44                         <b>const</b> basic_regex&lt;charT, traits&gt;&amp; e,
45                         boost::match_flag_type flags = match_default)
46</pre>
47      <p>The library also defines the following convenience versions, which take either
48         a const charT*, or a const std::basic_string&lt;&gt;&amp; in place of a pair of
49         iterators [note - these versions may not be available, or may be available in a
50         more limited form, depending upon your compilers capabilities]:</p>
51      <pre>
52<b>template</b> &lt;<b>class</b> Predicate, <b>class</b> charT, <b>class</b> traits&gt;
53<b>unsigned</b> <b>int</b> regex_grep(Predicate foo,
54              <b>const</b> charT* str,
55              <b>const</b> basic_regex&lt;charT, traits&gt;&amp; e,
56              boost::match_flag_type flags = match_default);
57
58<b>template</b> &lt;<b>class</b> Predicate, <b>class</b> ST, <b>class</b> SA, <b>class</b> charT, <b>class</b> traits&gt;
59<b>unsigned</b> <b>int</b> regex_grep(Predicate foo,
60              <b>const</b> std::basic_string&lt;charT, ST, SA&gt;&amp; s,
61              <b>const</b> basic_regex&lt;charT, traits&gt;&amp; e,
62              boost::match_flag_type flags = match_default);
63</pre>
64      <p>The parameters for the primary version of regex_grep have the following
65         meanings:&nbsp;</p>
66      <p></p>
67      <table id="Table2" cellspacing="0" cellpadding="7" width="624" border="0">
68         <tr>
69            <td width="5%">&nbsp;</td>
70            <td valign="top" width="50%">foo</td>
71            <td valign="top" width="50%">A predicate function object or function pointer, see
72               below for more information.</td>
73            <td width="5%">&nbsp;</td>
74         </tr>
75         <tr>
76            <td>&nbsp;</td>
77            <td valign="top" width="50%">first</td>
78            <td valign="top" width="50%">The start of the range to search.</td>
79            <td>&nbsp;</td>
80         </tr>
81         <tr>
82            <td>&nbsp;</td>
83            <td valign="top" width="50%">last</td>
84            <td valign="top" width="50%">The end of the range to search.</td>
85            <td>&nbsp;</td>
86         </tr>
87         <tr>
88            <td>&nbsp;</td>
89            <td valign="top" width="50%">e</td>
90            <td valign="top" width="50%">The regular expression to search for.</td>
91            <td>&nbsp;</td>
92         </tr>
93         <tr>
94            <td>&nbsp;</td>
95            <td valign="top" width="50%">flags</td>
96            <td valign="top" width="50%">The flags that determine how matching is carried out,
97               one of the <a href="match_flag_type.html">match_flags</a> enumerators.</td>
98            <td>&nbsp;</td>
99         </tr>
100      </table>
101      <br>
102      <br>
103      <p>The algorithm finds all of the non-overlapping matches of the expression e, for
104         each match it fills a <a href="match_results.html">match_results</a>&lt;iterator&gt; 
105         structure, which contains information on what matched, and calls the predicate
106         foo, passing the match_results&lt;iterator&gt; as a single argument. If the
107         predicate returns true, then the grep operation continues, otherwise it
108         terminates without searching for further matches. The function returns the
109         number of matches found.</p>
110      <p>The general form of the predicate is:</p>
111      <pre>
112<b>struct</b> grep_predicate
113{
114 <b>  bool</b> <b>operator</b>()(<b>const</b> match_results&lt;iterator_type&gt;&amp; m);
115};
116</pre>
117      <p>For example the regular expression "a*b" would find one match in the string
118         "aaaaab" and two in the string "aaabb".</p>
119      <p>Remember this algorithm can be used for a lot more than implementing a version
120         of grep, the predicate can be and do anything that you want, grep utilities
121         would output the results to the screen, another program could index a file
122         based on a regular expression and store a set of bookmarks in a list, or a text
123         file conversion utility would output to file. The results of one regex_grep can
124         even be chained into another regex_grep to create recursive parsers.</p>
125      <P>The algorithm may throw&nbsp;<CODE>std::runtime_error</CODE> if the complexity
126         of matching the expression against an N character string begins to exceed O(N<SUP>2</SUP>),
127         or if the program runs out of stack space while matching the expression (if
128         Boost.regex is <A href="configuration.html">configured</A> in recursive mode),
129         or if the matcher exhausts it's permitted memory allocation (if Boost.regex is <A href="configuration.html">
130            configured</A> in non-recursive mode).</P>
131      <p><a href="../example/snippets/regex_grep_example_1.cpp"> Example</a>: convert
132         the example from <i>regex_search</i> to use <i>regex_grep</i> instead:</p>
133      <pre>
134<font color="#008000">#include &lt;string&gt; 
135#include &lt;map&gt; 
136#include &lt;boost/regex.hpp&gt; 
137
138</font><font color="#000080"><i>// IndexClasses:
139// takes the contents of a file in the form of a string
140// and searches for all the C++ class definitions, storing
141// their locations in a map of strings/int's
142</i></font><b>typedef</b> std::map&lt;std::string, <b>int</b>, std::less&lt;std::string&gt; &gt; map_type;
143
144const char* re =
145   // possibly leading whitespace:   
146   "^[[:space:]]*"
147   // possible template declaration:
148   "(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?"
149   // class or struct:
150   "(class|struct)[[:space:]]*"
151   // leading declspec macros etc:
152   "("
153      "\\&lt;\\w+\\&gt;"
154      "("
155         "[[:blank:]]*\\([^)]*\\)"
156      ")?"
157      "[[:space:]]*"
158   ")*"
159   // the class name
160   "(\\&lt;\\w*\\&gt;)[[:space:]]*"
161   // template specialisation parameters
162   "(&lt;[^;:{]+&gt;)?[[:space:]]*"
163   // terminate in { or :
164   "(\\{|:[^;\\{()]*\\{)";
165
166boost::regex expression(re);
167<b>class</b> IndexClassesPred
168{
169   map_type&amp; m;
170   std::string::const_iterator base;
171<b>public</b>:
172   IndexClassesPred(map_type&amp; a, std::string::const_iterator b) : m(a), base(b) {}
173   <b>bool</b> <b>operator</b>()(<b>const</b>  smatch&amp; what)
174   {
175 <font color=
176#000080>     <i>// what[0] contains the whole string
177</i>      <i>// what[5] contains the class name.
178</i>      <i>// what[6] contains the template specialisation if any.
179</i>      <i>// add class name and position to map:
180</i></font>      m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
181                what[5].first - base;
182      <b>return</b> <b>true</b>;
183   }
184};
185<b>void</b> IndexClasses(map_type&amp; m, <b>const</b> std::string&amp; file)
186{
187   std::string::const_iterator start, end;
188   start = file.begin();
189   end = file.end();
190   regex_grep(IndexClassesPred(m, start), start, end, expression);
191}
192</pre>
193      <p><a href="../example/snippets/regex_grep_example_2.cpp"> Example</a>: Use
194         regex_grep to call a global callback function:</p>
195      <pre>
196<font color="#008000">#include &lt;string&gt; 
197#include &lt;map&gt; 
198#include &lt;boost/regex.hpp&gt; 
199
200</font><font color="#000080"><i>// purpose:
201// takes the contents of a file in the form of a string
202// and searches for all the C++ class definitions, storing
203// their locations in a map of strings/int's
204</i></font><b>typedef</b> std::map&lt;std::string, <b>int</b>, std::less&lt;std::string&gt; &gt; map_type;
205
206const char* re =
207   // possibly leading whitespace:   
208   "^[[:space:]]*"
209   // possible template declaration:
210   "(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?"
211   // class or struct:
212   "(class|struct)[[:space:]]*"
213   // leading declspec macros etc:
214   "("
215      "\\&lt;\\w+\\&gt;"
216      "("
217         "[[:blank:]]*\\([^)]*\\)"
218      ")?"
219      "[[:space:]]*"
220   ")*"
221   // the class name
222   "(\\&lt;\\w*\\&gt;)[[:space:]]*"
223   // template specialisation parameters
224   "(&lt;[^;:{]+&gt;)?[[:space:]]*"
225   // terminate in { or :
226   "(\\{|:[^;\\{()]*\\{)";
227
228boost::regex expression(re);
229map_type class_index;
230std::string::const_iterator base;
231
232<b>bool</b> grep_callback(<b>const</b>  boost::smatch&amp; what)
233{
234 <font color="#000080">  <i>// what[0] contains the whole string
235</i>   <i>// what[5] contains the class name.
236</i>   <i>// what[6] contains the template specialisation if any.
237</i>   <i>// add class name and position to map:
238</i></font>   class_index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
239                what[5].first - base;
240   <b>return</b> <b>true</b>;
241}
242<b>void</b> IndexClasses(<b>const</b> std::string&amp; file)
243{
244   std::string::const_iterator start, end;
245   start = file.begin();
246   end = file.end();
247   base = start;
248   regex_grep(grep_callback, start, end, expression, match_default);
249}
250 
251</pre>
252      <p><a href="../example/snippets/regex_grep_example_3.cpp"> Example</a>: use
253         regex_grep to call a class member function, use the standard library adapters <i>std::mem_fun</i>
254         and <i>std::bind1st</i> to convert the member function into a predicate:</p>
255      <pre>
256<font color="#008000">#include &lt;string&gt; 
257#include &lt;map&gt; 
258#include &lt;boost/regex.hpp&gt; 
259#include &lt;functional&gt; 
260</font><font color="#000080"><i>// purpose:
261// takes the contents of a file in the form of a string
262// and searches for all the C++ class definitions, storing
263// their locations in a map of strings/int's
264
265</i></font><b>typedef</b> std::map&lt;std::string, <b>int</b>, std::less&lt;std::string&gt; &gt; map_type;
266<b>class</b> class_index
267{
268   boost::regex expression;
269   map_type index;
270   std::string::const_iterator base;
271   <b>bool</b>  grep_callback(boost::smatch what);
272<b>public</b>:
273 <b>  void</b> IndexClasses(<b>const</b> std::string&amp; file);
274   class_index()
275      : index(),
276        expression(<font color=
277#000080>"^(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?"
278                   "(class|struct)[[:space:]]*(\\&lt;\\w+\\&gt;([[:blank:]]*\\([^)]*\\))?"
279                   "[[:space:]]*)*(\\&lt;\\w*\\&gt;)[[:space:]]*(&lt;[^;:{]+&gt;[[:space:]]*)?"
280                   "(\\{|:[^;\\{()]*\\{)"
281</font>                   ){}
282};
283<b>bool</b>  class_index::grep_callback(boost::smatch what)
284{
285 <font color="#000080">  <i>// what[0] contains the whole string
286</i>   <i>// what[5] contains the class name.
287</i>   <i>// what[6] contains the template specialisation if any.
288</i>   <i>// add class name and position to map:
289</i></font>   index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
290               what[5].first - base;
291   <b>return</b> <b>true</b>;
292}
293
294<b>void</b> class_index::IndexClasses(<b>const</b> std::string&amp; file)
295{
296   std::string::const_iterator start, end;
297   start = file.begin();
298   end = file.end();
299   base = start;
300   regex_grep(std::bind1st(std::mem_fun(&amp;class_index::grep_callback), <b>this</b>),
301              start,
302              end,
303              expression);
304}
305 
306</pre>
307      <p><a href="../example/snippets/regex_grep_example_4.cpp"> Finally</a>, C++
308         Builder users can use C++ Builder's closure type as a callback argument:</p>
309      <pre>
310<font color="#008000">#include &lt;string&gt; 
311#include &lt;map&gt; 
312#include &lt;boost/regex.hpp&gt; 
313#include &lt;functional&gt; 
314</font><font color="#000080"><i>// purpose:
315// takes the contents of a file in the form of a string
316// and searches for all the C++ class definitions, storing
317// their locations in a map of strings/int's
318
319</i></font><b>typedef</b> std::map&lt;std::string, <b>int</b>, std::less&lt;std::string&gt; &gt; map_type;
320<b>class</b> class_index
321{
322   boost::regex expression;
323   map_type index;
324   std::string::const_iterator base;
325   <b>typedef</b>  boost::smatch arg_type;
326   <b>bool</b> grep_callback(<b>const</b> arg_type&amp; what);
327<b>public</b>:
328   <b>typedef</b> <b>bool</b> (<b>__closure</b>* grep_callback_type)(<b>const</b> arg_type&amp;);
329   <b>void</b> IndexClasses(<b>const</b> std::string&amp; file);
330   class_index()
331      : index(),
332        expression(<font color=
333#000080>"^(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?"
334                   "(class|struct)[[:space:]]*(\\&lt;\\w+\\&gt;([[:blank:]]*\\([^)]*\\))?"
335                   "[[:space:]]*)*(\\&lt;\\w*\\&gt;)[[:space:]]*(&lt;[^;:{]+&gt;[[:space:]]*)?"
336                   "(\\{|:[^;\\{()]*\\{)"
337</font>                   ){}
338};
339
340<b>bool</b> class_index::grep_callback(<b>const</b> arg_type&amp; what)
341{
342 <font color=
343#000080>  <i>// what[0] contains the whole string</i>   
344<i>// what[5] contains the class name.</i>   
345<i>// what[6] contains the template specialisation if any.</i>   
346<i>// add class name and position to map:</i></font>   
347index[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =
348               what[5].first - base;
349   <b>return</b> <b>true</b>;
350}
351
352<b>void</b> class_index::IndexClasses(<b>const</b> std::string&amp; file)
353{
354   std::string::const_iterator start, end;
355   start = file.begin();
356   end = file.end();
357   base = start;
358   class_index::grep_callback_type cl = &amp;(<b>this</b>-&gt;grep_callback);
359   regex_grep(cl,
360            start,
361            end,
362            expression);
363}
364</pre>
365      <p></p>
366      <hr>
367      <p>Revised
368         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
369         26 June 2004
370         <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
371      <p><i>© Copyright John Maddock&nbsp;1998-
372            <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan -->  2004<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
373      <P><I>Use, modification and distribution are subject to the Boost Software License,
374            Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
375            or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
376   </body>
377</html>
Note: See TracBrowser for help on using the repository browser.