mirror of
https://github.com/boostorg/regex.git
synced 2025-07-04 08:06:31 +02:00
318 lines
17 KiB
HTML
318 lines
17 KiB
HTML
<!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="../../../c++boost.gif" border="0"></a></h3>
|
||
</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 <<A href="../../../boost/regex.hpp">boost/regex.hpp</A>> </PRE>
|
||
<P>The algorithm regex _match determines whether a given regular expression
|
||
matches a given sequence denoted by a pair of bidirectional-iterators, the
|
||
algorithm is defined as follows, <STRONG>note that the result is true only if the
|
||
expression matches the whole of the input sequence</STRONG>, the main use of
|
||
this function is data input validation.
|
||
<PRE>template <class BidirectionalIterator, class Allocator, class charT,
|
||
class traits, class Allocator2>
|
||
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
|
||
<A href="match_results.html">match_results</A><BidirectionalIterator, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
|
||
template <class BidirectionalIterator, class charT, class traits, class Allocator2>
|
||
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
|
||
template <class charT, class Allocator, class traits, class Allocator2>
|
||
bool regex_match(const charT* str, <A href="match_results.html">match_results</A><const charT*, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
|
||
template <class ST, class SA, class Allocator, class charT,
|
||
class traits, class Allocator2>
|
||
bool regex_match(const basic_string<charT, ST, SA>& s,
|
||
<A href="match_results.html">match_results</A><typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
|
||
template <class charT, class traits, class Allocator2>
|
||
bool regex_match(const charT* str,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
|
||
template <class ST, class SA, class charT, class traits, class Allocator2>
|
||
bool regex_match(const basic_string<charT, ST, SA>& s,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<A href="match_flag_type.html">match_flag_type</A> flags = match_default);
|
||
</PRE>
|
||
<H3><A name="description"></A>Description</H3>
|
||
<PRE>template <class BidirectionalIterator, class Allocator, class charT,
|
||
class traits, class Allocator2>
|
||
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
|
||
<A href="match_results.html">match_results</A><BidirectionalIterator, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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
|
||
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 < 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 < 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 < 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> </PRE>
|
||
<PRE>template <class BidirectionalIterator, class charT, class traits, class Allocator2>
|
||
bool regex_match(BidirectionalIterator first, BidirectionalIterator last,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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><</CODE>BidirectionalIterator<CODE>> what</CODE>,
|
||
and then returning the result of <CODE>regex_match(first, last, what, e, flags)</CODE>.</P>
|
||
<PRE>template <class charT, class Allocator, class traits, class Allocator2>
|
||
bool regex_match(const charT* str, <A href="match_results.html">match_results</A><const charT*, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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<charT>::length(str), m, e, flags)</CODE>.</P>
|
||
<PRE>template <class ST, class SA, class Allocator, class charT,
|
||
class traits, class Allocator2>
|
||
bool regex_match(const basic_string<charT, ST, SA>& s,
|
||
<A href="match_results.html">match_results</A><typename basic_string<charT, ST, SA>::const_iterator, Allocator>& m,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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>template <class charT, class traits, class Allocator2>
|
||
bool regex_match(const charT* str,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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<charT>::length(str), e, flags)</CODE>.</P>
|
||
<PRE>template <class ST, class SA, class charT, class traits, class Allocator2>
|
||
bool regex_match(const basic_string<charT, ST, SA>& s,
|
||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator2>& e,
|
||
<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 <stdlib.h>
|
||
#include <boost/regex.hpp>
|
||
#include <string>
|
||
#include <iostream>
|
||
|
||
</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)
|
||
{
|
||
cmatch what;
|
||
<B>if</B>(regex_match(response, what, expression))
|
||
{
|
||
<FONT color=#000080> <I>// what[0] contains the whole string
|
||
</I> <I>// what[1] contains the response code
|
||
</I> <I>// what[2] contains the separator character
|
||
</I> <I>// what[3] contains the text message.
|
||
</I></FONT> <B>if</B>(msg)
|
||
msg->assign(what[3].first, what[3].second);
|
||
<B>return</B> std::atoi(what[1].first);
|
||
}
|
||
<FONT color=#000080> <I>// failure did not match
|
||
</I></FONT> <B>if</B>(msg)
|
||
msg->erase();
|
||
<B>return</B> -1;
|
||
}
|
||
<P>
|
||
<HR></PRE>
|
||
<P></P>
|
||
<p>Revised
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||
17 May 2003
|
||
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
||
</p>
|
||
<P><I><EFBFBD> Copyright <a href="mailto:jm@regex.fsnet.co.uk">John Maddock</a> 1998-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></I></P>
|
||
<P align="left"><I>Permission to use, copy, modify, distribute and sell this software
|
||
and its documentation for any purpose is hereby granted without fee, provided
|
||
that the above copyright notice appear in all copies and that both that
|
||
copyright notice and this permission notice appear in supporting documentation.
|
||
Dr John Maddock makes no representations about the suitability of this software
|
||
for any purpose. It is provided "as is" without express or implied warranty.</I></P>
|
||
</body>
|
||
</html>
|