Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/regex/doc/regex_search.html @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost
File size: 17.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3   <head>
4      <title>Boost.Regex: Algorithm regex_search</title>
5      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6      <LINK href="../../../boost.css" type="text/css" rel="stylesheet"></head>
7   <body>
8      <P>
9         <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
10            <TR>
11               <td vAlign="top" width="300">
12                  <h3><A href="../../../index.htm"><IMG height="86" alt="C++ Boost" src="../../../boost.png" width="277" border="0"></A></h3>
13               </td>
14               <TD width="353">
15                  <H1 align="center">Boost.Regex</H1>
16                  <H2 align="center">Algorithm regex_search</H2>
17               </TD>
18               <td width="50">
19                  <h3><A href="index.html"><IMG height="45" alt="Boost.Regex Index" src="uarrow.gif" width="43" border="0"></A></h3>
20               </td>
21            </TR>
22         </TABLE>
23      </P>
24      <HR>
25      <H3>Contents</H3>
26      <dl class="index">
27         <dt><A href="#synopsis">Synopsis</A> <dt><a href="#description">Description</a> <dt><A href="#examples">
28                     Examples</A></dt></dl>
29      <H3><A name="synopsis"></A>Synopsis</H3>
30      <PRE>#include &lt;<A href="../../../boost/regex.hpp">boost/regex.hpp</A>&gt; </PRE>
31      <P></P>
32      <P>The algorithm regex_search will search a range denoted by a pair of
33         bidirectional-iterators for a given regular expression. The algorithm uses
34         various heuristics to reduce the search time by only checking for a match if a
35         match could conceivably start at that position. The algorithm is defined as
36         follows:
37         <PRE>template &lt;class BidirectionalIterator,
38          class Allocator, class charT, class traits&gt;
39bool <A href="#f1">regex_search</A>(BidirectionalIterator first, BidirectionalIterator last,
40                  <a href="match_results.html">match_results</a>&lt;BidirectionalIterator, Allocator&gt;&amp; m,
41                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
42                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
43                 
44template &lt;class ST, class SA,
45          class Allocator, class charT, class traits&gt; 
46bool <A href="#f2">regex_search</A>(const basic_string&lt;charT, ST, SA&gt;&amp; s,
47                  <a href="match_results.html">match_results</a>&lt;
48                      typename basic_string&lt;charT, ST,SA&gt;::const_iterator,
49                      Allocator&gt;&amp; m,
50                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
51                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
52         
53template&lt;class charT, class Allocator, class traits&gt; 
54bool <A href="#f3">regex_search</A>(const charT* str,
55                  <a href="match_results.html">match_results</a>&lt;const charT*, Allocator&gt;&amp; m,
56                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
57                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
58                 
59template &lt;class BidirectionalIterator, class charT, class traits&gt;               
60bool <A href="#f4">regex_search</A>(BidirectionalIterator first, BidirectionalIterator last,
61                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
62                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
63                 
64template &lt;class charT, class traits&gt; 
65bool <A href="#f5">regex_search</A>(const charT* str,
66                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
67                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
68                 
69template&lt;class ST, class SA, class charT, class traits&gt;
70bool <A href="#f6">regex_search</A>(const basic_string&lt;charT, ST, SA&gt;&amp; s,
71                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
72                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);
73</PRE>
74         <H3><A name="description"></A>Description</H3>
75         <PRE><A name=f1></A>template &lt;class BidirectionalIterator, class Allocator, class charT, class traits&gt;
76bool regex_search(BidirectionalIterator first, BidirectionalIterator last,
77                  <a href="match_results.html">match_results</a>&lt;BidirectionalIterator, Allocator&gt;&amp; m,
78                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
79                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
80      <P><B> Requires:</B> Type BidirectionalIterator meets the requirements of a
81         Bidirectional Iterator (24.1.4).</P>
82      <P><B> Effects: </B>Determines whether there is some sub-sequence within
83         [first,last) that matches the regular expression <I>e</I>, parameter <I>flags</I>
84         is used to control how the expression is matched against the character
85         sequence. Returns true if such a sequence exists, false otherwise.</P>
86      <P><STRONG>Throws:</STRONG> <CODE>std::runtime_error</CODE> if the complexity of
87         matching the expression against an N character string begins to exceed O(N<SUP>2</SUP>),
88         or if the program runs out of stack space while matching the expression (if
89         Boost.regex is <A href="configuration.html">configured</A> in recursive mode),
90         or if the matcher exhausts it's permitted memory allocation (if Boost.regex is <A href="configuration.html">
91            configured</A> in non-recursive mode).</P>
92      <P><B> Postconditions: </B>If the function returns false, then the effect on
93         parameter <I>m</I> is undefined, otherwise the effects on parameter <I>m</I> are
94         given in the table:</P>
95      <DIV align="center">
96         <CENTER>
97            <TABLE id="Table2" cellSpacing="1" cellPadding="7" width="624" border="1">
98               <TR>
99                  <TD vAlign="top" width="50%">
100                     <P><B> Element</B></P>
101                  </TD>
102                  <TD vAlign="top" width="50%">
103                     <P><B> Value</B>
104                     </P>
105                  </TD>
106               </TR>
107               <TR>
108                  <TD vAlign="top" width="50%">
109                     <P>m.size()</P>
110                  </TD>
111                  <TD vAlign="top" width="50%">
112                     <P>e.mark_count()</P>
113                  </TD>
114               </TR>
115               <TR>
116                  <TD vAlign="top" width="50%">
117                     <P>m.empty()</P>
118                  </TD>
119                  <TD vAlign="top" width="50%">
120                     <P>false</P>
121                  </TD>
122               </TR>
123               <TR>
124                  <TD vAlign="top" width="50%">
125                     <P>m.prefix().first</P>
126                  </TD>
127                  <TD vAlign="top" width="50%">
128                     <P>first</P>
129                  </TD>
130               </TR>
131               <TR>
132                  <TD vAlign="top" width="50%">
133                     <P>m.prefix().last</P>
134                  </TD>
135                  <TD vAlign="top" width="50%">
136                     <P>m[0].first</P>
137                  </TD>
138               </TR>
139               <TR>
140                  <TD vAlign="top" width="50%">
141                     <P>m.prefix().matched</P>
142                  </TD>
143                  <TD vAlign="top" width="50%">
144                     <P>m.prefix().first != m.prefix().second</P>
145                  </TD>
146               </TR>
147               <TR>
148                  <TD vAlign="top" width="50%">
149                     <P>m.suffix().first</P>
150                  </TD>
151                  <TD vAlign="top" width="50%">
152                     <P>m[0].second</P>
153                  </TD>
154               </TR>
155               <TR>
156                  <TD vAlign="top" width="50%">
157                     <P>m.suffix().last</P>
158                  </TD>
159                  <TD vAlign="top" width="50%">
160                     <P>last</P>
161                  </TD>
162               </TR>
163               <TR>
164                  <TD vAlign="top" width="50%">
165                     <P>m.suffix().matched</P>
166                  </TD>
167                  <TD vAlign="top" width="50%">
168                     <P>m.suffix().first != m.suffix().second</P>
169                  </TD>
170               </TR>
171               <TR>
172                  <TD vAlign="top" width="50%">
173                     <P>m[0].first</P>
174                  </TD>
175                  <TD vAlign="top" width="50%">
176                     <P>The start of the sequence of characters that matched the regular expression</P>
177                  </TD>
178               </TR>
179               <TR>
180                  <TD vAlign="top" width="50%">
181                     <P>m[0].second</P>
182                  </TD>
183                  <TD vAlign="top" width="50%">
184                     <P>The end of the sequence of characters that matched the regular expression</P>
185                  </TD>
186               </TR>
187               <TR>
188                  <TD vAlign="top" width="50%">
189                     <P>m[0].matched</P>
190                  </TD>
191                  <TD vAlign="top" width="50%">
192                     <P><CODE> true</CODE> if a full match was found, and <CODE>false</CODE> if it was
193                        a partial match (found as a result of the <CODE>match_partial</CODE> flag being
194                        set).</P>
195                  </TD>
196               </TR>
197               <TR>
198                  <TD vAlign="top" width="50%">
199                     <P>m[n].first</P>
200                  </TD>
201                  <TD vAlign="top" width="50%">
202                     <P>For all integers n &lt; m.size(), the start of the sequence that matched
203                        sub-expression <I>n</I>. Alternatively, if sub-expression n did not participate
204                        in the match, then <I>last</I>.</P>
205                  </TD>
206               </TR>
207               <TR>
208                  <TD vAlign="top" width="50%">
209                     <P>m[n].second</P>
210                  </TD>
211                  <TD vAlign="top" width="50%">
212                     <P>For all integers n &lt; m.size(), the end of the sequence that matched
213                        sub-expression <I>n</I>. Alternatively, if sub-expression n did not participate
214                        in the match, then <I>last</I>.</P>
215                  </TD>
216               </TR>
217               <TR>
218                  <TD vAlign="top" width="50%">
219                     <P>m[n].matched</P>
220                  </TD>
221                  <TD vAlign="top" width="50%">
222                     <P>For all integers n &lt; m.size(), true if sub-expression <I>n</I> participated
223                        in the match, false otherwise.</P>
224                  </TD>
225               </TR>
226               </TD></TR></TABLE>
227         </CENTER>
228      </DIV>
229      <PRE><A name=f2></A>template &lt;class charT, class Allocator, class traits&gt;
230bool regex_search(const charT* str, <a href="match_results.html">match_results</a>&lt;const charT*, Allocator&gt;&amp; m,
231                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
232                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
233      <P><B> Effects:</B> Returns the result of <CODE>regex_search(str, str +
234            char_traits&lt;charT&gt;::length(str), m, e, flags)</CODE>.</P>
235      <PRE><A name=f3></A>template &lt;class ST, class SA, class Allocator, class charT,
236          class traits&gt;
237bool regex_search(const basic_string&lt;charT, ST, SA&gt;&amp; s,
238                  <a href="match_results.html">match_results</a>&lt;typename basic_string&lt;charT, ST, SA&gt;::const_iterator, Allocator&gt;&amp; m,
239                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
240                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
241      <P><B> Effects:</B> Returns the result of <CODE>regex_search(s.begin(), s.end(), m,
242            e, flags)</CODE>.</P>
243      <PRE><A name=f4></A>template &lt;class iterator, class charT, class traits&gt;
244bool regex_search(iterator first, iterator last,
245                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
246                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
247      <P><B> Effects:</B> Behaves "as if" by constructing an instance of <CODE><a href="match_results.html">
248               match_results</a>&lt;</CODE>BidirectionalIterator<CODE>&gt; what</CODE>,
249         and then returning the result of <CODE>regex_search(first, last, what, e, flags)</CODE>.</P>
250      <PRE><A name=f5></A>template &lt;class charT, class traits&gt;
251bool regex_search(const charT* str
252                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
253                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
254      <P><B> Effects:</B> Returns the result of <CODE>regex_search(str, str +
255            char_traits&lt;charT&gt;::length(str), e, flags)</CODE>.</P>
256      <PRE><A name=f6></A>template &lt;class ST, class SA, class charT, class traits&gt;
257bool regex_search(const basic_string&lt;charT, ST, SA&gt;&amp; s,
258                  const <a href="basic_regex.html">basic_regex</a>&lt;charT, traits&gt;&amp; e,
259                  <a href="match_flag_type.html">match_flag_type</a> flags = match_default);</PRE>
260      <P><B> Effects:</B> Returns the result of <CODE>regex_search(s.begin(), s.end(), e,
261            flags)</CODE>.
262         <H3><A name="examples"></A>Examples</H3>
263      <P>The following <A href="../example/snippets/regex_search_example.cpp">example</A>,
264         takes the contents of a file in the form of a string, and searches for all the
265         C++ class declarations in the file. The code will work regardless of the way
266         that std::string is implemented, for example it could easily be modified to
267         work with the SGI rope class, which uses a non-contiguous storage strategy.</P>
268      <P></P>
269      <PRE><FONT color=#008000>#include &lt;string&gt; 
270#include &lt;map&gt; 
271#include &lt;boost/regex.hpp&gt; 
272</FONT><FONT color=#000080><I>
273// purpose:
274// takes the contents of a file in the form of a string
275// and searches for all the C++ class definitions, storing
276// their locations in a map of strings/int's
277</I></FONT><B>typedef</B> std::map&lt;std::string, <B>int</B>, std::less&lt;std::string&gt; &gt; map_type;
278
279boost::regex expression("^(template[[:space:]]*&lt;[^;:{]+&gt;[[:space:]]*)?(class|struct)[[:space:]]*(\\&lt;\\w+\\&gt;([[:blank:]]*\\([^)]*\\))?[[:space:]]*)*(\\&lt;\\w*\\&gt;)[[:space:]]*(&lt;[^;:{]+&gt;[[:space:]]*)?(\\{|:[^;\\{()]*\\{)");
280<B>
281void</B> IndexClasses(map_type&amp; m, <B>const</B> std::string&amp; file)
282{
283&nbsp;&nbsp; std::string::const_iterator start, end;
284&nbsp;&nbsp; start = file.begin();
285&nbsp;&nbsp; end = file.end();&nbsp;
286&nbsp;&nbsp; &nbsp;&nbsp; boost::<a href="match_results.html">match_results</a>&lt;std::string::const_iterator&gt; what;
287&nbsp;&nbsp; boost::match_flag_type flags = boost::match_default;
288&nbsp;&nbsp; <B>while</B>(regex_search(start, end, what, expression, flags))&nbsp;
289&nbsp;&nbsp; {
290<FONT color=#000080>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[0] contains the whole string
291</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[5] contains the class name.
292</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[6] contains the template specialisation if any.
293</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// add class name and position to map:
294</I></FONT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; m[std::string(what[5].first, what[5].second) + std::string(what[6].first, what[6].second)] =&nbsp;
295 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; what[5].first - file.begin();&nbsp;
296&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <FONT color=#000080><I>// update search position:
297</I></FONT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; start = what[0].second;&nbsp;
298&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <FONT color=#000080><I>// update flags:
299</I></FONT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; flags |= boost::match_prev_avail;&nbsp;
300&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; flags |= boost::match_not_bob;&nbsp;
301&nbsp;&nbsp; }
302}
303     </PRE>
304      <HR>
305      <p>Revised
306         <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 
307         23 June 2004
308         <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
309      <p><i>© Copyright John Maddock&nbsp;1998-
310            <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan -->  2004<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
311      <P><I>Use, modification and distribution are subject to the Boost Software License,
312            Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
313            or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
314   </body>
315</html>
Note: See TracBrowser for help on using the repository browser.