mirror of
https://github.com/boostorg/regex.git
synced 2025-07-05 00:26:30 +02:00
433 lines
18 KiB
HTML
433 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<title>Boost.Regex: regex_iterator</title>
|
||
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<link href="../../../boost.css" type="text/css" rel="stylesheet">
|
||
</head>
|
||
<body>
|
||
<p></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" alt="C++ Boost" src="../../../boost.png" width="277" border="0"></a></h3>
|
||
</td>
|
||
<td width="353">
|
||
<h1 align="center">Boost.Regex</h1>
|
||
<h2 align="center">regex_iterator</h2>
|
||
</td>
|
||
<td width="50">
|
||
<h3><a href="index.html"><img height="45" alt="Boost.Regex Index" src="uarrow.gif" width="43" border="0"></a></h3>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<br>
|
||
<br>
|
||
<hr>
|
||
<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>
|
||
<p>The iterator type regex_iterator will enumerate all of the regular expression
|
||
matches found in some sequence: dereferencing a regex_iterator yields a
|
||
reference to a <a href="match_results.html">match_results</a> object.</p>
|
||
<pre>
|
||
template <class BidirectionalIterator,
|
||
class charT = iterator_traits<BidirectionalIterator>::value_type,
|
||
class traits = regex_traits<charT>,
|
||
class Allocator = allocator<charT> >
|
||
class regex_iterator
|
||
{
|
||
public:
|
||
typedef <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator> regex_type;
|
||
typedef <A href="match_results.html">match_results</A><BidirectionalIterator> value_type;
|
||
typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type;
|
||
typedef const value_type* pointer;
|
||
typedef const value_type& reference;
|
||
typedef std::forward_iterator_tag iterator_category;
|
||
|
||
<A href="#c1">regex_iterator</A>();
|
||
<A href="#c2">regex_iterator</A>(BidirectionalIterator a, BidirectionalIterator b,
|
||
const regex_type& re,
|
||
<A href="match_flag_type.html">match_flag_type</A> m = match_default);
|
||
<A href="#c3">regex_iterator</A>(const regex_iterator&);
|
||
regex_iterator& <A href="#o1">operator</A>=(const regex_iterator&);
|
||
bool <A href="#o2">operator</A>==(const regex_iterator&)const;
|
||
bool <A href="#o3">operator</A>!=(const regex_iterator&)const;
|
||
const value_type& <A href="#o4">operator</A>*()const;
|
||
const value_type* <A href="#o5">operator</A>->()const;
|
||
regex_iterator& <A href="#o6">operator</A>++();
|
||
regex_iterator <A href="#o7">operator</A>++(int);
|
||
};
|
||
|
||
typedef regex_iterator<const char*> cregex_iterator;
|
||
typedef regex_iterator<std::string::const_iterator> sregex_iterator;
|
||
#ifndef BOOST_NO_WREGEX
|
||
typedef regex_iterator<const wchar_t*> wcregex_iterator;
|
||
typedef regex_iterator<std::wstring::const_iterator> wsregex_iterator;
|
||
#endif
|
||
|
||
</pre>
|
||
<h3><a name="description"></a>Description</h3>
|
||
<p>A regex_iterator is constructed from a pair of iterators, and enumerates all
|
||
occurrences of a regular expression within that iterator range.</p>
|
||
<pre><A name=c1></A>
|
||
regex_iterator();
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> constructs an end of sequence regex_iterator.</p>
|
||
<pre><A name=c2></A>regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
|
||
const regex_type& re,
|
||
<A href="match_flag_type.html">match_flag_type</A> m = match_default);
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> constructs a regex_iterator that will enumerate all occurrences
|
||
of the expression <em>re</em>, within the sequence <em>[a,b)</em>, and found
|
||
using match flags <em>m</em>. The object <em>re</em> must exist for the
|
||
lifetime of the regex_iterator.</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>
|
||
<pre><A name=c3></A>
|
||
regex_iterator(const regex_iterator& that);
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> constructs a copy of <code>that</code>.</p>
|
||
<b></b>
|
||
<p><b>Postconditions:</b> <code>*this == that</code>.</p>
|
||
<pre><A name=o1></A>
|
||
regex_iterator& operator=(const regex_iterator&);
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> sets <code>*this</code> equal to those in <code>that</code>.</p>
|
||
<b></b>
|
||
<p><b>Postconditions:</b> <code>*this == that</code>.</p>
|
||
<pre><A name=o2></A>
|
||
bool operator==(const regex_iterator& that)const;
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> returns true if *this is equal to that.</p>
|
||
<pre><A name=o3></A>
|
||
bool operator!=(const regex_iterator&)const;
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> returns <code>!(*this == that)</code>.</p>
|
||
<pre><A name=o4></A>
|
||
const value_type& operator*()const;
|
||
</pre>
|
||
<p><b>Effects:</b> dereferencing a regex_iterator object <em>it</em> yields a
|
||
const reference to a <a href="match_results.html">match_results</a> object,
|
||
whose members are set as follows:</p>
|
||
<p></p>
|
||
<table id="Table2" cellspacing="1" cellpadding="7" width="624" border="1">
|
||
<tbody>
|
||
<tr>
|
||
<td valign="top" width="50%"><b></b>
|
||
<p><b>Element</b></p>
|
||
</td>
|
||
<td valign="top" width="50%"><b></b>
|
||
<p><b>Value</b></p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).size()</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>re.mark_count()</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).empty()</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>false</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).prefix().first</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The end of the last match found, or the start of the underlying sequence if
|
||
this is the first match enumerated</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).prefix().last</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The same as the start of the match found:<BR>
|
||
(*it)[0].first</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).prefix().matched</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>True if the prefix did not match an empty string:<BR>
|
||
(*it).prefix().first != (*it).prefix().second</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).suffix().first</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The same as the end of the match found:<BR>
|
||
(*it)[0].second</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).suffix().last</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The end of the underlying sequence.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it).suffix().matched</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>True if the suffix did not match an empty string:<BR>
|
||
(*it).suffix().first != (*it).suffix().second</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it)[0].first</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The start of the sequence of characters that matched the regular expression</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it)[0].second</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>The end of the sequence of characters that matched the regular expression</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">
|
||
<p>(*it)[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>(*it)[n].first</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>For all integers n < (*it).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>(*it)[n].second</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>For all integers n < (*it).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>(*it)[n].matched</p>
|
||
</td>
|
||
<td valign="top" width="50%">
|
||
<p>For all integers n < (*it).size(), true if sub-expression <i>n</i> participated
|
||
in the match, false otherwise.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td valign="top" width="50%">(*it).position(n)</td>
|
||
<td valign="top" width="50%">For all integers n < (*it).size(), then the
|
||
distance from the start of the underlying sequence to the start of
|
||
sub-expression match <em>n</em>.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<br>
|
||
<br>
|
||
<pre><A name=o5></A>
|
||
const value_type* operator->()const;
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> returns <code>&(*this)</code>.</p>
|
||
<pre><A name=o6></A>
|
||
regex_iterator& operator++();
|
||
</pre>
|
||
<p><strong>Effects:</strong> moves the iterator to the next match in the
|
||
underlying sequence, or the end of sequence iterator if none if found.
|
||
When the last match found matched a zero length string, then the
|
||
regex_iterator will find the next match as follows: if there exists a non-zero
|
||
length match that starts at the same location as the last one, then returns it,
|
||
otherwise starts looking for the next (possibly zero length) match from one
|
||
position to the right of the last match.</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>
|
||
<b></b>
|
||
<p><b>Returns:</b> <code>*this</code>.</p>
|
||
<pre><A name=o7></A>
|
||
regex_iterator operator++(int);
|
||
</pre>
|
||
<b></b>
|
||
<p><b>Effects:</b> constructs a copy <code>result</code> of <code>*this</code>,
|
||
then calls <code>++(*this)</code>.</p>
|
||
<b></b>
|
||
<p><b>Returns:</b> <code>result</code>.</p>
|
||
<h3>Examples</h3>
|
||
<p>The following <a href="../example/snippets/regex_iterator_example.cpp">example</a>
|
||
takes a C++ source file and builds up an index of class names, and the location
|
||
of that class in the file.</p>
|
||
<pre>
|
||
<font color="#008040">#include <string></font>
|
||
<font color="#008040">#include <map></font>
|
||
<font color="#008040">#include <fstream></font>
|
||
<font color="#008040">#include <iostream></font>
|
||
<font color="#008040">#include <boost/regex.hpp></font>
|
||
|
||
<b>using</b> <b>namespace</b> std;
|
||
|
||
<i><font color="#000080">// purpose:</font></i>
|
||
<i><font color=
|
||
#000080>// takes the contents of a file in the form of a string</font></i>
|
||
<i><font color=
|
||
#000080>// and searches for all the C++ class definitions, storing</font></i>
|
||
<i><font color=
|
||
#000080>// their locations in a map of strings/int's</font></i>
|
||
|
||
<b>typedef</b> std::map<std::string, std::string::difference_type, std::less<std::string> > map_type;
|
||
|
||
<b>const</b> <b>char</b>* re =
|
||
<i><font color=
|
||
#000080>// possibly leading whitespace: </font></i>
|
||
<font color="#0000ff">"^[[:space:]]*"</font>
|
||
<i><font color=
|
||
#000080>// possible template declaration:</font></i>
|
||
<font color=
|
||
#0000ff>"(template[[:space:]]*<[^;:{]+>[[:space:]]*)?"</font>
|
||
<i><font color="#000080">// class or struct:</font></i>
|
||
<font color="#0000ff">"(class|struct)[[:space:]]*"</font>
|
||
<i><font color=
|
||
#000080>// leading declspec macros etc:</font></i>
|
||
<font color="#0000ff">"("</font>
|
||
<font color="#0000ff">"\\<\\w+\\>"</font>
|
||
<font color="#0000ff">"("</font>
|
||
<font color="#0000ff">"[[:blank:]]*\\([^)]*\\)"</font>
|
||
<font color="#0000ff">")?"</font>
|
||
<font color="#0000ff">"[[:space:]]*"</font>
|
||
<font color="#0000ff">")*"</font>
|
||
<i><font color="#000080">// the class name</font></i>
|
||
<font color="#0000ff">"(\\<\\w*\\>)[[:space:]]*"</font>
|
||
<i><font color=
|
||
#000080>// template specialisation parameters</font></i>
|
||
<font color="#0000ff">"(<[^;:{]+>)?[[:space:]]*"</font>
|
||
<i><font color="#000080">// terminate in { or :</font></i>
|
||
<font color="#0000ff">"(\\{|:[^;\\{()]*\\{)"</font>;
|
||
|
||
|
||
boost::regex expression(re);
|
||
map_type class_index;
|
||
|
||
<b>bool</b> regex_callback(<b>const</b> boost::match_results<std::string::const_iterator>& what)
|
||
{
|
||
<i><font color=
|
||
#000080>// what[0] contains the whole string</font></i>
|
||
<i><font color=
|
||
#000080>// what[5] contains the class name.</font></i>
|
||
<i><font color=
|
||
#000080>// what[6] contains the template specialisation if any.</font></i>
|
||
<i><font color=
|
||
#000080>// add class name and position to map:</font></i>
|
||
class_index[what[<font color=
|
||
#0000a0>5</font>].str() + what[<font color=
|
||
#0000a0>6</font>].str()] = what.position(<font color=
|
||
#0000a0>5</font>);
|
||
<b>return</b> <b>true</b>;
|
||
}
|
||
|
||
<b>void</b> load_file(std::string& s, std::istream& is)
|
||
{
|
||
s.erase();
|
||
s.reserve(is.rdbuf()->in_avail());
|
||
<b>char</b> c;
|
||
<b>while</b>(is.get(c))
|
||
{
|
||
<b>if</b>(s.capacity() == s.size())
|
||
s.reserve(s.capacity() * <font color="#0000a0">3</font>);
|
||
s.append(<font color="#0000a0">1</font>, c);
|
||
}
|
||
}
|
||
|
||
<b>int</b> main(<b>int</b> argc, <b>const</b> <b>char</b>** argv)
|
||
{
|
||
std::string text;
|
||
<b>for</b>(<b>int</b> i = <font color=
|
||
#0000a0>1</font>; i < argc; ++i)
|
||
{
|
||
cout << <font color=
|
||
#0000ff>"Processing file "</font> << argv[i] << endl;
|
||
std::ifstream fs(argv[i]);
|
||
load_file(text, fs);
|
||
<i><font color=
|
||
#000080>// construct our iterators:</font></i>
|
||
boost::sregex_iterator m1(text.begin(), text.end(), expression);
|
||
boost::sregex_iterator m2;
|
||
std::for_each(m1, m2, &regex_callback);
|
||
<i><font color="#000080">// copy results:</font></i>
|
||
cout << class_index.size() << <font color=
|
||
#0000ff>" matches found"</font> << endl;
|
||
map_type::iterator c, d;
|
||
c = class_index.begin();
|
||
d = class_index.end();
|
||
<b>while</b>(c != d)
|
||
{
|
||
cout << <font color=
|
||
#0000ff>"class \""</font> << (*c).first << <font
|
||
color=
|
||
#0000ff>"\" found at index: "</font> << (*c).second << endl;
|
||
++c;
|
||
}
|
||
class_index.erase(class_index.begin(), class_index.end());
|
||
}
|
||
<b>return</b> <font color="#0000a0">0</font>;
|
||
}
|
||
</pre>
|
||
<hr>
|
||
<p>Revised
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||
24 Oct 2003
|
||
<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
|
||
<p><i><EFBFBD> Copyright John Maddock 1998-
|
||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan --> 2003<!--webbot bot="Timestamp" endspan i-checksum="39359" --></i></p>
|
||
<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>
|
||
</body>
|
||
</html>
|