boostorg/regex
1
0
Fork 1
mirror of https://github.com/boostorg/regex.git synced 2025-07-04 08:06:31 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
f6b9c3d809f4b64e2ebdbf6e0b1db1c8d5216fd6
regex/doc/regex_iterator.html

434 lines
18 KiB
HTML
Raw Normal View History

Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
<!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="../../../c++boost.gif" 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&nbsp;<a href="match_results.html">match_results</a> object.</p>
<pre>
template &lt;class BidirectionalIterator,
class charT = iterator_traits&lt;BidirectionalIterator&gt;::value_type,
class traits = regex_traits&lt;charT&gt;,
class Allocator = allocator&lt;charT&gt; &gt;
class regex_iterator
{
public:
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
typedef <A href="basic_regex.html">basic_regex</A>&lt;charT, traits, Allocator&gt; regex_type;
typedef <A href="match_results.html">match_results</A>&lt;BidirectionalIterator&gt; value_type;
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
typedef typename iterator_traits&lt;BidirectionalIterator&gt;::difference_type difference_type;
typedef const value_type* pointer;
typedef const value_type&amp; reference;
typedef std::forward_iterator_tag iterator_category;
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<A href="#c1">regex_iterator</A>();
<A href="#c2">regex_iterator</A>(BidirectionalIterator a, BidirectionalIterator b,
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
const regex_type&amp; re,
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<A href="match_flag_type.html">match_flag_type</A> m = match_default);
<A href="#c3">regex_iterator</A>(const regex_iterator&amp;);
regex_iterator&amp; <A href="#o1">operator</A>=(const regex_iterator&amp;);
bool <A href="#o2">operator</A>==(const regex_iterator&amp;)const;
bool <A href="#o3">operator</A>!=(const regex_iterator&amp;)const;
const value_type&amp; <A href="#o4">operator</A>*()const;
const value_type* <A href="#o5">operator</A>-&gt;()const;
regex_iterator&amp; <A href="#o6">operator</A>++();
regex_iterator <A href="#o7">operator</A>++(int);
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
};
Added new iterator typedefs [SVN r21148]
2003-12-05 13:01:54 +00:00
typedef regex_iterator&lt;const char*&gt; cregex_iterator;
typedef regex_iterator&lt;std::string::const_iterator&gt; sregex_iterator;
#ifndef BOOST_NO_WREGEX
typedef regex_iterator&lt;const wchar_t*&gt; wcregex_iterator;
typedef regex_iterator&lt;std::wstring::const_iterator&gt; wsregex_iterator;
#endif
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</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>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=c1></A>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
regex_iterator();
</pre>
<b></b>
<p><b>Effects:</b> constructs an end of sequence regex_iterator.</p>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=c2></A>regex_iterator(BidirectionalIterator a, BidirectionalIterator b,
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
const regex_type&amp; re,
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<A href="match_flag_type.html">match_flag_type</A> m = match_default);
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</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>.&nbsp; 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>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=c3></A>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
regex_iterator(const regex_iterator&amp; 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>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o1></A>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
regex_iterator&amp; operator=(const regex_iterator&amp;);
</pre>
<b></b>
<p><b>Effects:</b> sets&nbsp;<code>*this</code> equal to those in <code>that</code>.</p>
<b></b>
<p><b>Postconditions:</b> <code>*this == that</code>.</p>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o2></A>
bool operator==(const regex_iterator&amp; that)const;
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</pre>
<b></b>
<p><b>Effects:</b> returns true if *this is equal to that.</p>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o3></A>
bool operator!=(const regex_iterator&amp;)const;
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</pre>
<b></b>
<p><b>Effects:</b> returns <code>!(*this == that)</code>.</p>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o4></A>
const value_type&amp; operator*()const;
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</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%">
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<p>The same as the start of the match found:<BR>
(*it)[0].first</p>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</td>
</tr>
<tr>
<td valign="top" width="50%">
<p>(*it).prefix().matched</p>
</td>
<td valign="top" width="50%">
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<p>True if the prefix did not match an empty string:<BR>
(*it).prefix().first != (*it).prefix().second</p>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</td>
</tr>
<tr>
<td valign="top" width="50%">
<p>(*it).suffix().first</p>
</td>
<td valign="top" width="50%">
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<p>The same as the end of the match found:<BR>
(*it)[0].second</p>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</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%">
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<p>True if the suffix did not match an empty string:<BR>
(*it).suffix().first != (*it).suffix().second</p>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</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 &lt; (*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 &lt; (*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 &lt; (*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 &lt; (*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>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o5></A>
const value_type* operator-&gt;()const;
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</pre>
<b></b>
<p><b>Effects:</b> returns <code>&amp;(*this)</code>.</p>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o6></A>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
regex_iterator&amp; 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.
&nbsp;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>
Updated docs to include recent changes, and improve general quality. [SVN r20443]
2003-10-21 11:18:40 +00:00
<pre><A name=o7></A>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
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 &lt;string&gt;</font>
<font color="#008040">#include &lt;map&gt;</font>
<font color="#008040">#include &lt;fstream&gt;</font>
<font color="#008040">#include &lt;iostream&gt;</font>
<font color="#008040">#include &lt;boost/regex.hpp&gt;</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&lt;std::string, std::string::difference_type, std::less&lt;std::string&gt; &gt; 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:]]*&lt;[^;:{]+&gt;[[: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">"\\&lt;\\w+\\&gt;"</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">"(\\&lt;\\w*\\&gt;)[[:space:]]*"</font>
<i><font color=
#000080>// template specialisation parameters</font></i>
<font color="#0000ff">"(&lt;[^;:{]+&gt;)?[[: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&lt;std::string::const_iterator&gt;&amp; 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&amp; s, std::istream&amp; is)
{
s.erase();
s.reserve(is.rdbuf()-&gt;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 &lt; argc; ++i)
{
cout &lt;&lt; <font color=
#0000ff>"Processing file "</font> &lt;&lt; argv[i] &lt;&lt; endl;
std::ifstream fs(argv[i]);
load_file(text, fs);
<i><font color=
#000080>// construct our iterators:</font></i>
boost::regex_iterator&lt;std::string::const_iterator&gt; m1(text.begin(), text.end(), expression);
boost::regex_iterator&lt;std::string::const_iterator&gt; m2;
std::for_each(m1, m2, <20>ex_callback);
<i><font color="#000080">// copy results:</font></i>
cout &lt;&lt; class_index.size() &lt;&lt; <font color=
#0000ff>" matches found"</font> &lt;&lt; endl;
map_type::iterator c, d;
c = class_index.begin();
d = class_index.end();
<b>while</b>(c != d)
{
cout &lt;&lt; <font color=
#0000ff>"class \""</font> &lt;&lt; (*c).first &lt;&lt; <font
color=
#0000ff>"\" found at index: "</font> &lt;&lt; (*c).second &lt;&lt; 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 -->
Updated copyrights [SVN r20470]
2003-10-24 10:51:38 +00:00
24 Oct 2003
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
Updated copyrights [SVN r20470]
2003-10-24 10:51:38 +00:00
<p><i><EFBFBD> Copyright John Maddock&nbsp;1998-
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y" startspan -->
Updated copyrights [SVN r20470]
2003-10-24 10:51:38 +00:00
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>
Merged regex-4 branch. [SVN r18430]
2003-05-17 11:45:48 +00:00
</body>
</html>
Reference in New Issue Copy Permalink