ceph/src/boost/libs/iostreams/doc/classes/regex_filter.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4     <TITLE>Class Template basic_regex_filter</TITLE>
   5     <LINK REL="stylesheet" HREF="../../../../boost.css">
   6     <LINK REL="stylesheet" HREF="../theme/iostreams.css">
   7 </HEAD>
   8 <BODY>
   9
  10 <!-- Begin Banner -->
  11
  12     <H1 CLASS="title">Class Template <CODE>basic_regex_filter</CODE></H1>
  13     <HR CLASS="banner">
  14
  15 <!-- End Banner -->
  16
  17 <DL class="page-index">
  18   <DT><A href="#description">Description</A></DT>
  19   <DT><A href="#headers">Headers</A></DT>
  20   <DT><A href="#installation">Installation</A></DT>
  21   <DT><A href="#reference">Reference</A></DT>
  22 </DL>
  23
  24 <HR>
  25
  26 <A NAME="description"></A>
  27 <H2>Description</H2>
  28
  29 <P>
  30     The class template <CODE>basic_regex_filter</CODE> performs text substitutions using regular expressions from the <A HREF="http://www.boost.org/libs/regex" TARGET="_top">Boost Regular Expression Library</A> (<A CLASS="bib_ref" HREF="../bibliography.html#maddock">[Maddock]</A>).
  31 </P>
  32 <P>
  33     Each <CODE>basic_regex_filter</CODE> stores a regular expression and a formatting function. As unfiltered data is scanned for matches, portions of data which fall between regular expression matches are forwarded unchanged. Each time a match is found, the corresponding <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/match_results.html" TARGET="_top"><CODE>match_results</CODE></A> object is passed to the formatting function and the return value is forwarded in place of the matched text.
  34 </P>
  35 <P>
  36     Users may construct instances of <CODE>basic_regex_filter</CODE> either from <A HREF="#formatter">formatting functions</A> or from <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/format.html" TARGET="_top">format strings</A>.
  37 </P>
  38 <P>
  39     Since a regular expression may need to look arbitrarily far ahead in a character sequence, <CODE>basic_regex_filter</CODE> derives from <A HREF="aggregate.html"><CODE>aggregate_filter</CODE></A> and processes an entire sequence of data at once.
  40 </P>
  41
  42 <A NAME="headers"></A>
  43 <H2>Headers</H2>
  44
  45 <DL class="page-index">
  46   <DT><A CLASS="header" HREF="../../../../boost/iostreams/filter/regex.hpp"><CODE>&lt;boost/iostreams/filter/regex.hpp&gt;</CODE></A></DT>
  47 </DL>
  48
  49 <A NAME="installation"></A>
  50 <H2>Installation</H2>
  51
  52 <P>
  53     The template <CODE>basic_regex_filter</CODE> uses the <A HREF="http://www.boost.org/libs/regex" TARGET="_top">Boost Regular Expression Library</A>, which must be built separately. See <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/install.html" TARGET="_top">here</A> for details.
  54 </P>
  55
  56 <A NAME="reference"></A>
  57 <H2>Reference</H2>
  58
  59 <H4>Synopsis</H4>
  60
  61 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
  62
  63 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/function.hpp" TARGET="_top"><SPAN CLASS="literal">&lt;boost/function.hpp&gt;</SPAN></A>
  64 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/regex.hpp" TARGET="_top"><SPAN CLASS="literal">&lt;boost/regex.hpp&gt;</SPAN></A>
  65
  66 <SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A HREF="#template_params" CLASS="documented">Ch</A>,
  67           <SPAN CLASS="keyword">typename</SPAN> <A HREF="#template_params" CLASS="documented">Tr</A> = regex_traits&lt;Ch&gt;,
  68           <SPAN CLASS="keyword">typename</SPAN> <A HREF="#template_params" CLASS="documented">Alloc</A> = std::allocator&lt;Ch&gt; &gt;
  69 <SPAN CLASS="keyword">class</SPAN> <A HREF="#template_params" CLASS="documented">basic_regex_filter</A>
  70     : <SPAN CLASS="keyword">public</SPAN> <A CLASS="documented" HREF="aggregate.html">aggregate_filter</A>&lt;Ch, std::char_traits&lt;Ch&gt;, Alloc&gt; // Exposition only
  71 {
  72 <SPAN CLASS="keyword">public:</SPAN>
  73     <SPAN CLASS="keyword">typedef</SPAN> <A CLASS="documented" HREF="../../../../doc/html/function.html" TARGET="_top">boost::function1&lt;</A>
  74                 std::basic_string&lt;Ch&gt;,
  75                 <SPAN CLASS="keyword">const</SPAN> match_results&lt;const Ch*&gt;&amp;
  76             &gt;
  77             <A CLASS="documented" HREF="#formatter">formatter</A>;
  78     <A CLASS="documented" HREF="#first_constructor">basic_regex_filter</A>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
  79                         <SPAN CLASS="keyword">const</SPAN> formatter&amp; replace,
  80                         regex_constants::match_flag_type flags =
  81                             regex_constants::match_default );
  82     <A CLASS="documented" HREF="#second_constructor">basic_regex_filter</A>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
  83                         <SPAN CLASS="keyword">const</SPAN> std::basic_string&lt;Ch&gt;&amp; fmt,
  84                         regex_constants::match_flag_type flags =
  85                             regex_constants::match_default,
  86                         regex_constants::match_flag_type fmt_flags =
  87                             regex_constants::format_default );
  88     <A CLASS="documented" HREF="#third_constructor">basic_regex_filter</A>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
  89                         <SPAN CLASS="keyword">const</SPAN> Ch* fmt,
  90                         regex_constants::match_flag_type flags =
  91                             regex_constants::match_default,
  92                         regex_constants::match_flag_type fmt_flags =
  93                             regex_constants::format_default );
  94 };
  95
  96 <SPAN CLASS="keyword">typedef</SPAN> basic_regex_filter&lt;<SPAN CLASS="keyword">char</SPAN>&gt;     <SPAN CLASS="defined">regex_filter</SPAN>;
  97 <SPAN CLASS="keyword">typedef</SPAN> basic_regex_filter&lt;<SPAN CLASS="keyword">wchar_t</SPAN>&gt;  <SPAN CLASS="defined">wregex_filter</SPAN>;
  98
  99 } } // End namespace boost::io</PRE>
 100
 101 <A NAME="template_params"></A>
 102 <H4>Template parameters</H4>
 103
 104 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 105 <TR>
 106     <TR>
 107         <TD VALIGN="top"><I>Ch</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 108         <TD>The character type</TD>
 109     </TR>
 110     <TR>
 111         <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 112         <TD>The <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/regex_traits.html" TARGET="_top">regular expression traits</A> type</TD>
 113     </TR>
 114     <TR>
 115         <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 116         <TD>A standard library allocator type (<A CLASS="bib_ref" HREF="../bibliography.html#iso">[ISO]</A>, 20.1.5), used to allocate character buffers</TD>
 117     </TR>
 118 </TABLE>
 119
 120 <A NAME="formatter"></A>
 121 <H4><CODE>basic_regex_filter::formatter</CODE></H4>
 122
 123 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">typedef</SPAN> boost::function1&lt;
 124                 std::basic_string&lt;Ch&gt;,
 125                 <SPAN CLASS="keyword">const</SPAN> match_results&lt;const Ch*&gt;&amp;
 126             &gt;
 127             <B>formatter</B>;</PRE>
 128
 129 <P>
 130     The type of object which a <CODE>basic_regex_filter</CODE> uses to determine the replacement text for a given regular expression match. Each time a match is found, a corresponding <CODE>match_results</CODE> object is passed to a <CODE>formatter</CODE>, which returns the appropriate replacement text. Since <A HREF="http://www.boost.org/libs/function" TARGET="_top">Boost.Function</A> objects are implictly constructible from function objects with the correct signature, users of regular expression Filters may define their own function objects with the correct signature and pass them to the <CODE>basic_regex_filter</CODE> constructor which takes a <CODE>formatter</CODE>. E.g.,
 131 <PRE CLASS="broken_ie">    struct my_formatter {
 132         std::string operator()(const match_results&lt;const char*&gt;&amp; match)
 133         {
 134             <SPAN CLASS="comment">// Examine match and return the appropriate replacement text</SPAN>
 135         }
 136     };
 137     int main()
 138     {
 139         regex         pattern( <SPAN CLASS="omitted">...</SPAN> );
 140         regex_filter  filter(pattern, my_formatter());
 141         <SPAN CLASS="omitted">...</SPAN>
 142     }</PRE>
 143 </P>
 144
 145 <H4><CODE>basic_regex_filter::basic_regex_filter</CODE></H4>
 146
 147 <A NAME="first_constructor"></A>
 148 <PRE CLASS="broken_ie">    <B>basic_regex_filter</B>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
 149                         <SPAN CLASS="keyword">const</SPAN> formatter&amp; replace,
 150                         regex_constants::match_flag_type flags =
 151                             regex_constants::match_default );</PRE>
 152
 153 <P>Constructs a <CODE>basic_regex_filter</CODE> from the given regular expression, formatting function and match flags. The parameters have the following interpretations:</P>
 154
 155 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 156 <TR>
 157     <TR>
 158         <TD VALIGN="top"><I>pattern</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 159         <TD>The regular expression to be matched against the stream of unfiltered data</TD>
 160     </TR>
 161     <TR>
 162         <TD VALIGN="top"><I>replace</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 163         <TD>A function which will be passed each <CODE>match_results</CODE> object in succession and whose return values will be be used as replacement text</TD>
 164     </TR>
 165     <TR>
 166         <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 167         <TD>Used to construct a <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/regex_iterator.html" TARGET="_top">regex_iterator</A></TD>
 168     </TR>
 169 </TABLE>
 170
 171 </P>
 172
 173 <A NAME="second_constructor"></A>
 174
 175 <PRE CLASS="broken_ie">    <B>basic_regex_filter</B>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
 176                         <SPAN CLASS="keyword">const</SPAN> std::basic_string&lt;Ch&gt;&amp; fmt,
 177                         regex_constants::match_flag_type flags =
 178                             regex_constants::match_default,
 179                         regex_constants::match_flag_type fmt_flags =
 180                             regex_constants::format_default );</PRE>
 181
 182 <P>Constructs a <CODE>basic_regex_filter</CODE> from the given regular expression, format string and pair of match flags. The parameters have the following interpretations:</P>
 183
 184 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 185 <TR>
 186     <TR>
 187         <TD VALIGN="top"><I>pattern</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 188         <TD>The regular expression to be matched against the stream of unfiltered data</TD>
 189     </TR>
 190     <TR>
 191         <TD VALIGN="top"><I>fmt</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 192         <TD>A <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/format.html" TARGET="_top">format string</A> which specifies the replacement text for each regular expression match, using <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/match_results.html#boost_regex.match_results.format2" TARGET="_top">match_results::format</A></TD>
 193     </TR>
 194     <TR>
 195         <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 196         <TD>Used to construct a <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/regex_iterator.html" TARGET="_top">regex_iterator</A></TD>
 197     </TR>
 198     <TR>
 199         <TD VALIGN="top"><I>fmt_flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 200         <TD>The flags argument to <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/match_results.html#boost_regex.match_results.format2" TARGET="_top">match_results::format</A></TD>
 201     </TR>
 202 </TABLE>
 203
 204 <A NAME="third_constructor"></A>
 205
 206 <PRE CLASS="broken_ie">    <B>basic_regex_filter</B>( <SPAN CLASS="keyword">const</SPAN> basic_regex&lt;Ch, Tr, Alloc&gt;&amp; pattern,
 207                         <SPAN CLASS="keyword">const</SPAN> Ch* fmt,
 208                         regex_constants::match_flag_type flags =
 209                             regex_constants::match_default,
 210                         regex_constants::match_flag_type fmt_flags =
 211                             regex_constants::format_default );</PRE>
 212
 213 <P>Constructs a <CODE>basic_regex_filter</CODE> from the given regular expression, format string and pair of match flags. The parameters have the following interpretations:</P>
 214
 215 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 216 <TR>
 217     <TR>
 218         <TD VALIGN="top"><I>pattern</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 219         <TD>The regular expression to be matched against the stream of unfiltered data</TD>
 220     </TR>
 221     <TR>
 222         <TD VALIGN="top"><I>fmt</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 223         <TD>A <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/format.html" TARGET="_top">format string</A> which specifies the replacement text for each regular expression match, using <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/match_results.html#boost_regex.match_results.format2" TARGET="_top">match_results::format</A></TD>
 224     </TR>
 225     <TR>
 226         <TD VALIGN="top"><I>flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 227         <TD>Used to construct a <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/regex_iterator.html" TARGET="_top">regex_iterator</A></TD>
 228     </TR>
 229     <TR>
 230         <TD VALIGN="top"><I>fmt_flags</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 231         <TD>The flags argument to <A HREF="http://www.boost.org/libs/regex/doc/html/boost_regex/ref/match_results.html#boost_regex.match_results.format2" TARGET="_top">match_results::format</A></TD>
 232     </TR>
 233 </TABLE>
 234
 235 <!-- Begin Footer -->
 236
 237 <HR>
 238
 239 <P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" target="_top">Jonathan Turkanis</a></P>
 240 <P CLASS="copyright">
 241     Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)
 242 </P>
 243
 244 <!-- End Footer -->
 245
 246 </BODY>