mirror of
https://github.com/boostorg/regex.git
synced 2025-07-29 12:07:28 +02:00
Updated docs to include recent changes, and improve general quality.
[SVN r20443]
This commit is contained in:
John Maddock
@ -29,7 +29,7 @@
|
||||
<H3><A name="synopsis"></A>Synopsis</H3>
|
||||
<PRE>#include <<A href="../../../boost/regex.hpp">boost/regex.hpp</A>> </PRE>
|
||||
<P>The algorithm regex_replace searches through a string finding
|
||||
all the matches to the regular expression: for each match it then calls <A href="match_results.html">
|
||||
all the matches to the regular expression: for each match it then calls <A href="match_results.html#format">
|
||||
match_results::format</A> to format the string and sends the result to the
|
||||
output iterator. Sections of text that do not match are copied to the output
|
||||
unchanged only if the <EM>flags</EM> parameter does not have the flag <A href="match_flag_type.html">
|
||||
@ -37,39 +37,87 @@
|
||||
is set then only the first occurrence is replaced rather than all
|
||||
occurrences. <PRE>template <class OutputIterator, class BidirectionalIterator, class traits,
|
||||
class Allocator, class charT>
|
||||
OutputIterator regex_replace(OutputIterator out,
|
||||
OutputIterator <A href="#f1">regex_replace</A>(OutputIterator out,
|
||||
BidirectionalIterator first,
|
||||
BidirectionalIterator last,
|
||||
const basic_regex<charT, traits, Allocator>& e,
|
||||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator>& e,
|
||||
const basic_string<charT>& fmt,
|
||||
match_flag_type flags = match_default);
|
||||
<A href="match_flag_type.html">match_flag_type flags = match_default</A>);
|
||||
|
||||
template <class traits, class Allocator, class charT>
|
||||
basic_string<charT> regex_replace(const basic_string<charT>& s,
|
||||
const basic_regex<charT, traits, Allocator>& e,
|
||||
basic_string<charT> <A href="#f2">regex_replace</A>(const basic_string<charT>& s,
|
||||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator>& e,
|
||||
const basic_string<charT>& fmt,
|
||||
match_flag_type flags = match_default);
|
||||
<A href="match_flag_type.html">match_flag_type flags = match_default</A>);
|
||||
|
||||
</PRE>
|
||||
<H3><A name="description"></A>Description</H3>
|
||||
<PRE>template <class OutputIterator, class BidirectionalIterator, class traits,
|
||||
<PRE><A name=f1></A>template <class OutputIterator, class BidirectionalIterator, class traits,
|
||||
class Allocator, class charT>
|
||||
OutputIterator regex_replace(OutputIterator out,
|
||||
BidirectionalIterator first,
|
||||
BidirectionalIterator last,
|
||||
const basic_regex<charT, traits, Allocator>& e,
|
||||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator>& e,
|
||||
const basic_string<charT>& fmt,
|
||||
match_flag_type flags = match_default);</PRE>
|
||||
<P><B> Effects:</B> Finds all the non-overlapping matches <I>m</I> of type <CODE>match_results<BidirectionalIterator>
|
||||
</CODE>that occur within the sequence [first, last). If no such matches are
|
||||
found and <CODE>!(flags & format_no_copy)</CODE> then calls <CODE>std::copy(first,
|
||||
last, out)</CODE>. Otherwise, for each match found, if <CODE>!(flags &
|
||||
format_no_copy)</CODE> calls <CODE>std::copy(m.prefix().first, m.prefix().last,
|
||||
out)</CODE>, and then calls <CODE>m.format(out, fmt, flags)</CODE>. Finally
|
||||
if <CODE>!(flags & format_no_copy)</CODE> calls <CODE>std::copy(last_m.suffix().first,
|
||||
last_m,suffix().last, out) </CODE>where <CODE>last_m</CODE> is a copy of the
|
||||
last match found. If <CODE>flags & format_first_only</CODE> is non-zero
|
||||
then only the first match found is replaced.</P>
|
||||
<A href="match_flag_type.html">match_flag_type flags = match_default</A>);</PRE>
|
||||
<P>Enumerates all the occurences of expression <EM>e</EM> in the sequence [first,
|
||||
last), replacing each occurence with the string that results by merging the
|
||||
match found with the format string <EM>fmt</EM>, and copies the resulting
|
||||
string to <EM>out</EM>. </P>
|
||||
<P>If the flag format_no_copy is set in <EM>flags</EM> then unmatched sections of
|
||||
text are not copied to output.
|
||||
</P>
|
||||
<P>If the flag format_first_only is set in <EM>flags</EM> then only the first
|
||||
occurence of <EM>e</EM> is replaced.
|
||||
</P>
|
||||
<P>The manner in which the format string <EM>fmt</EM> is interpretted, along with
|
||||
the rules used for finding matches, are determined by the <A href="match_flag_type.html">
|
||||
flags</A> set in <EM>flags</EM></P>
|
||||
<P><B>Effects:</B> Constructs an
|
||||
<SPAN class="spelle">regex_iterator</SPAN>
|
||||
object:
|
||||
</P>
|
||||
<PRE><SPAN style="FONT-SIZE: 10pt">regex_iterator<</SPAN><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">BidirectionalIterator</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt">, </SPAN><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">charT</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt">, traits, Allocator> <BR> </SPAN><SPAN class=grame><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">i(</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt">first, last, e, flags)</SPAN>, </PRE>
|
||||
<P>and uses
|
||||
<SPAN class="spelle">
|
||||
<I>i</I></SPAN>
|
||||
to enumerate through all of the matches <I>m</I> of type
|
||||
<SPAN class="spelle">
|
||||
<SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">match_results</SPAN>
|
||||
</SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'"><<SPAN class="spelle">BidirectionalIterator</SPAN>> </SPAN>that
|
||||
occur within the sequence [first, last).
|
||||
</P>
|
||||
<P>If no such matches are found
|
||||
<SPAN class="grame">and </SPAN></P>
|
||||
<PRE><SPAN class=grame></SPAN><SPAN class=grame><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">!</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(flags & <SPAN class=spelle>format_no_copy</SPAN>)</SPAN> </PRE>
|
||||
<P>then calls
|
||||
</P>
|
||||
<PRE><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">std::copy</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(first, last, out)</SPAN>. </PRE>
|
||||
<P>Otherwise, for each match found,
|
||||
<SPAN class="grame">if </SPAN></P>
|
||||
<PRE><SPAN class=grame></SPAN><SPAN class=grame><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">!</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(flags & <SPAN class=spelle>format_no_copy</SPAN>)</SPAN> </PRE>
|
||||
<P>calls
|
||||
</P>
|
||||
<PRE><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">std::copy</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(<SPAN class=spelle>m.prefix</SPAN>().first, <SPAN class=spelle>m.prefix</SPAN>().last, out)</SPAN>, </PRE>
|
||||
<P>and then calls
|
||||
</P>
|
||||
<PRE><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">m.format</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(out, <SPAN class=spelle>fmt</SPAN>, flags)</SPAN>. </PRE>
|
||||
<P>Finally
|
||||
<SPAN class="grame">if </SPAN></P>
|
||||
<PRE><SPAN class=grame></SPAN><SPAN class=grame><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">!</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(flags & <SPAN class=spelle>format_no_copy</SPAN>)</SPAN> </PRE>
|
||||
<P>calls
|
||||
</P>
|
||||
<PRE><SPAN class=spelle><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">std::copy</SPAN></SPAN><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">(<SPAN class=spelle>last_m.suffix</SPAN>().first, <SPAN class=spelle>last_m,suffix</SPAN>().last, out) </SPAN></PRE>
|
||||
<P><SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'"></SPAN>where
|
||||
<SPAN class="spelle">
|
||||
<SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">last_m</SPAN>
|
||||
</SPAN>
|
||||
is a copy of the last match found.
|
||||
</P>
|
||||
<P>If
|
||||
<SPAN style="FONT-SIZE: 10pt; FONT-FAMILY: 'Courier New'">flags &
|
||||
<SPAN class="spelle">format_first_only</SPAN></SPAN>
|
||||
is non-zero then only the first match found is replaced.</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
|
||||
@ -78,11 +126,11 @@ OutputIterator regex_replace(OutputIterator out,
|
||||
configured</A> in non-recursive mode).</P>
|
||||
<P><B> Returns:</B> <CODE>out</CODE>.
|
||||
</P>
|
||||
<PRE>template <class traits, class Allocator, class charT>
|
||||
<PRE><A name=f2></A>template <class traits, class Allocator, class charT>
|
||||
basic_string<charT> regex_replace(const basic_string<charT>& s,
|
||||
const basic_regex<charT, traits, Allocator>& e,
|
||||
const <A href="basic_regex.html">basic_regex</A><charT, traits, Allocator>& e,
|
||||
const basic_string<charT>& fmt,
|
||||
match_flag_type flags = match_default);</PRE>
|
||||
<A href="match_flag_type.html">match_flag_type flags = match_default</A>);</PRE>
|
||||
<P><B> Effects:</B> Constructs an object <CODE>basic_string<charT> result</CODE>,
|
||||
calls <CODE>regex_replace(back_inserter(result), s.begin(), s.end(), e, fmt,
|
||||
flags)</CODE>, and then returns <CODE>result</CODE>.
|
||||
|
||||
Reference in New Issue
Block a user