Files
regex/doc/regex_match.html

319 lines
16 KiB
HTML
Raw Normal View History

2003-05-17 11:45:48 +00:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Boost.Regex: Algorithm regex_match</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
</head>
<body>
<P>
<TABLE id="Table1" cellSpacing="1" cellPadding="1" width="100%" border="0">
<TR>
<td valign="top" width="300">
<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
2003-05-17 11:45:48 +00:00
</td>
<TD width="353">
<H1 align="center">Boost.Regex</H1>
<H2 align="center">Algorithm regex_match</H2>
</TD>
<td width="50">
<h3><a href="index.html"><img height="45" width="43" alt="Boost.Regex Index" src="uarrow.gif" border="0"></a></h3>
</td>
</TR>
</TABLE>
</P>
<HR>
<p></p>
<H3>Contents</H3>
<dl class="index">
<dt><a href="#synopsis">Synopsis</a> <dt><a href="#description">Description</a> <dt><a href="#examples">
Examples</a></dt>
</dl>
<H3><A name="synopsis"></A>Synopsis</H3>
<PRE><A name=query_match></A>#include &lt;<A href="../../../boost/regex.hpp">boost/regex.hpp</A>&gt; </PRE>
<P>
The algorithm regex _match determines whether a given regular expression
matches all of a given character sequence denoted by a pair of
bidirectional-iterators, the algorithm is defined as follows, the main use of
this function is data input validation.
<P><STRONG>Note that the result is true only if the expression matches the whole of
the input sequence.&nbsp;</STRONG> If you want to search for an expression
somewhere within the sequence then use <A href="regex_search.html">regex_search</A>.&nbsp;
If you want to match a prefix of the character string then use <A href="regex_search.html">
regex_search</A> with the flag <A href="match_flag_type.html">match_continuous</A>
set.
<PRE>
template &lt;class BidirectionalIterator, class Allocator, class charT, class traits&gt;
bool <A href="#f1">regex_match</A>(BidirectionalIterator first, BidirectionalIterator last,
2003-05-17 11:45:48 +00:00
<A href="match_results.html">match_results</A>&lt;BidirectionalIterator, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
template &lt;class BidirectionalIterator, class charT, class traits&gt;
bool <A href="#f2">regex_match</A>(BidirectionalIterator first, BidirectionalIterator last,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
template &lt;class charT, class Allocator, class traits&gt;
bool <A href="#f3">regex_match</A>(const charT* str, <A href="match_results.html">match_results</A>&lt;const charT*, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
template &lt;class ST, class SA, class Allocator, class charT, class traits&gt;
bool <A href="#f4">regex_match</A>(const basic_string&lt;charT, ST, SA&gt;&amp; s,
2003-05-17 11:45:48 +00:00
<A href="match_results.html">match_results</A>&lt;typename basic_string&lt;charT, ST, SA&gt;::const_iterator, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
template &lt;class charT, class traits&gt;
bool <A href="#f5">regex_match</A>(const charT* str,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
template &lt;class ST, class SA, class charT, class traits&gt;
bool <A href="#f6">regex_match</A>(const basic_string&lt;charT, ST, SA&gt;&amp; s,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
</PRE>
<H3><A name="description"></A>Description</H3>
<PRE><A name=f1></A>template &lt;class BidirectionalIterator, class Allocator, class charT, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
<A href="match_results.html">match_results</A>&lt;BidirectionalIterator, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Requires:</B> Type BidirectionalIterator meets the requirements of a
Bidirectional Iterator (24.1.4).</P>
<P><B> Effects: </B>Determines whether there is an exact match between the regular
expression <I>e</I>, and all of the character sequence [first, last), parameter <I>
flags</I> is used to <A href="match_flag_type.html">control how the expression
is matched</A> against the character sequence. Returns true if such a match
exists, false otherwise.</P>
<P><STRONG>Throws:</STRONG> <code>std::runtime_error</code> if the complexity of
matching the expression against an N character string begins to exceed O(N<SUP>2</SUP>),
or if the program runs out of stack space while matching the expression (if
2003-05-17 11:45:48 +00:00
Boost.regex is <A href="configuration.html">configured</A> in recursive mode),
or if the matcher exhausts it's permitted memory allocation (if Boost.regex is <A href="configuration.html">
configured</A> in non-recursive mode).</P>
<P><B> Postconditions: </B>If the function returns false, then the effect on
parameter <I>m</I> is undefined, otherwise the effects on parameter <I>m</I> are
given in the table:</P>
<P align="center">
<CENTER>
<TABLE id="Table2" cellSpacing="1" cellPadding="7" width="624" border="1">
<TBODY>
<TR>
<TD vAlign="top" width="50%">
<P><B> Element</B>
</P>
</TD>
<TD vAlign="top" width="50%">
<P><B> Value</B>
</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.size()</P>
</TD>
<TD vAlign="top" width="50%">
<P>e.mark_count()</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.empty()</P>
</TD>
<TD vAlign="top" width="50%">
<P>false</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.prefix().first</P>
</TD>
<TD vAlign="top" width="50%">
<P>first</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.prefix().last</P>
</TD>
<TD vAlign="top" width="50%">
<P>first</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.prefix().matched</P>
</TD>
<TD vAlign="top" width="50%">
<P>false</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.suffix().first</P>
</TD>
<TD vAlign="top" width="50%">
<P>last</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.suffix().last</P>
</TD>
<TD vAlign="top" width="50%">
<P>last</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m.suffix().matched</P>
</TD>
<TD vAlign="top" width="50%">
<P>false</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[0].first</P>
</TD>
<TD vAlign="top" width="50%">
<P>first</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[0].second</P>
</TD>
<TD vAlign="top" width="50%">
<P>last</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[0].matched</P>
</TD>
<TD vAlign="top" width="50%">
<P><CODE> true</CODE> if a full match was found, and <CODE>false</CODE> if it was
a partial match (found as a result of the <CODE>match_partial</CODE> flag being
set).</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[n].first</P>
</TD>
<TD vAlign="top" width="50%">
<P>For all integers n &lt; m.size(), the start of the sequence that matched
sub-expression <I>n</I>. Alternatively, if sub-expression n did not participate
in the match, then <I>last</I>.</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[n].second</P>
</TD>
<TD vAlign="top" width="50%">
<P>For all integers n &lt; m.size(), the end of the sequence that matched
sub-expression <I>n</I>. Alternatively, if sub-expression n did not participate
in the match, then <I>last</I>.</P>
</TD>
</TR>
<TR>
<TD vAlign="top" width="50%">
<P>m[n].matched</P>
</TD>
<TD vAlign="top" width="50%">
<P>For all integers n &lt; m.size(), true if sub-expression <I>n</I> participated
in the match, false otherwise.</P>
</TD>
</TR>
</TBODY></TD></TR></TABLE>
</CENTER>
<P></P>
<DIV></DIV>
<PRE>&nbsp;</PRE>
<PRE><A name=f2></A>template &lt;class BidirectionalIterator, class charT, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Effects:</B> Behaves "as if" by constructing an instance of <CODE><A href="match_results.html">
match_results</A>&lt;</CODE>BidirectionalIterator<CODE>&gt; what</CODE>,
and then returning the result of <CODE>regex_match(first, last, what, e, flags)</CODE>.</P>
<PRE><A name=f3></A>template &lt;class charT, class Allocator, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(const charT* str, <A href="match_results.html">match_results</A>&lt;const charT*, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Effects:</B> Returns the result of <CODE>regex_match(str, str +
char_traits&lt;charT&gt;::length(str), m, e, flags)</CODE>.</P>
<PRE><A name=f4></A>template &lt;class ST, class SA, class Allocator,
class charT, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(const basic_string&lt;charT, ST, SA&gt;&amp; s,
<A href="match_results.html">match_results</A>&lt;typename basic_string&lt;charT, ST, SA&gt;::const_iterator, Allocator&gt;&amp; m,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Effects:</B> Returns the result of <CODE>regex_match(s.begin(), s.end(), m, e,
flags)</CODE>.</P>
<PRE><A name=f5></A>template &lt;class charT, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(const charT* str,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Effects:</B> Returns the result of <CODE>regex_match(str, str +
char_traits&lt;charT&gt;::length(str), e, flags)</CODE>.</P>
<PRE><A name=f6></A>template &lt;class ST, class SA, class charT, class traits&gt;
2003-05-17 11:45:48 +00:00
bool regex_match(const basic_string&lt;charT, ST, SA&gt;&amp; s,
const <A href="basic_regex.html">basic_regex</A> &lt;charT, traits&gt;&amp; e,
2003-05-17 11:45:48 +00:00
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);</PRE>
<P><B> Effects:</B> Returns the result of <CODE>regex_match(s.begin(), s.end(), e,
flags)</CODE>.
<H3><A name="examples"></A>Examples</H3>
<P>The following <A href="../example/snippets/regex_match_example.cpp">example</A>
processes an ftp response:
<P></P>
<PRE><FONT color=#008000>#include &lt;stdlib.h&gt;
#include &lt;boost/regex.hpp&gt;
#include &lt;string&gt;
#include &lt;iostream&gt;
</FONT><B>using namespace</B> boost;
regex expression(<FONT color=#000080>"([0-9]+)(\\-| |$)(.*)"</FONT>);
<FONT color=#000080><I>// process_ftp:
// on success returns the ftp response code, and fills
// msg with the ftp response message.
</I></FONT><B>int</B> process_ftp(<B>const</B> <B>char</B>* response, std::string* msg)
{
&nbsp;&nbsp; cmatch what;
&nbsp;&nbsp; <B>if</B>(regex_match(response, what, expression))
&nbsp;&nbsp; {
<FONT color=#000080>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[0] contains the whole string
</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[1] contains the response code
</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[2] contains the separator character
</I>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <I>// what[3] contains the text message.
</I></FONT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <B>if</B>(msg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; msg-&gt;assign(what[3].first, what[3].second);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <B>return</B> std::atoi(what[1].first);
&nbsp;&nbsp; }
<FONT color=#000080>&nbsp;&nbsp; <I>// failure did not match
</I></FONT>&nbsp;&nbsp; <B>if</B>(msg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; msg-&gt;erase();
&nbsp;&nbsp; <B>return</B> -1;
}
<P>
<HR></PRE>
<P></P>
<p>Revised&nbsp;
2003-05-17 11:45:48 +00:00
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
26 June 2004&nbsp;
2003-10-24 10:51:38 +00:00
<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
<p><i><EFBFBD> Copyright John Maddock&nbsp;1998-
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2004<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
2003-10-24 10:51:38 +00:00
<P><I>Use, modification and distribution are subject to the Boost Software License,
Version 1.0. (See accompanying file <A href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</A>
or copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)</I></P>
2003-05-17 11:45:48 +00:00
</body>
</html>