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