doc/html/string_algo/concept.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Concepts</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../string_algo.html" title="Chapter&#160;2.&#160;Boost String Algorithms Library">
  10 <link rel="prev" href="design.html" title="Design Topics">
  11 <link rel="next" href="reference.html" title="Reference">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="design.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string_algo.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="string_algo.concept"></a>Concepts</h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="concept.html#idp125098096">Definitions</a></span></dt>
  31 <dt><span class="section"><a href="concept.html#string_algo.finder_concept">Finder Concept</a></span></dt>
  32 <dt><span class="section"><a href="concept.html#string_algo.formatter_concept">Formatter concept</a></span></dt>
  33 </dl></div>
  34 <div class="section">
  35 <div class="titlepage"><div><div><h3 class="title">
  36 <a name="idp125098096"></a>Definitions</h3></div></div></div>
  37 <div class="table">
  38 <a name="idp125098736"></a><p class="title"><b>Table&#160;2.13.&#160;Notation</b></p>
  39 <div class="table-contents"><table class="table" summary="Notation">
  40 <colgroup>
  41 <col>
  42 <col>
  43 </colgroup>
  44 <tbody>
  45 <tr>
  46 <td align="left"><code class="computeroutput">F</code></td>
  47 <td align="left">A type that is a model of Finder</td>
  48 </tr>
  49 <tr>
  50 <td align="left"><code class="computeroutput">Fmt</code></td>
  51 <td align="left">A type that is a model of Formatter</td>
  52 </tr>
  53 <tr>
  54 <td align="left"><code class="computeroutput">Iter</code></td>
  55 <td align="left">
  56                             Iterator Type
  57                         </td>
  58 </tr>
  59 <tr>
  60 <td align="left"><code class="computeroutput">f</code></td>
  61 <td align="left">Object of type <code class="computeroutput">F</code>
  62 </td>
  63 </tr>
  64 <tr>
  65 <td align="left"><code class="computeroutput">fmt</code></td>
  66 <td align="left">Object of type <code class="computeroutput">Fmt</code>
  67 </td>
  68 </tr>
  69 <tr>
  70 <td align="left"><code class="computeroutput">i,j</code></td>
  71 <td align="left">Objects of type <code class="computeroutput">Iter</code>
  72 </td>
  73 </tr>
  74 </tbody>
  75 </table></div>
  76 </div>
  77 <br class="table-break">
  78 </div>
  79 <div class="section">
  80 <div class="titlepage"><div><div><h3 class="title">
  81 <a name="string_algo.finder_concept"></a>Finder Concept</h3></div></div></div>
  82 <p>
  83             Finder is a functor which searches for an arbitrary part of a container.
  84             The result of the search is given as an <code class="computeroutput">iterator_range</code>
  85             delimiting the selected part.
  86         </p>
  87 <div class="table">
  88 <a name="idp125114848"></a><p class="title"><b>Table&#160;2.14.&#160;Valid Expressions</b></p>
  89 <div class="table-contents"><table class="table" summary="Valid Expressions">
  90 <colgroup>
  91 <col>
  92 <col>
  93 <col>
  94 </colgroup>
  95 <thead><tr>
  96 <th align="left">Expression</th>
  97 <th align="left">Return Type</th>
  98 <th align="left">Effects</th>
  99 </tr></thead>
 100 <tbody><tr>
 101 <td align="left"><code class="computeroutput">f(i,j)</code></td>
 102 <td align="left">Convertible to <code class="computeroutput">iterator_range&lt;Iter&gt;</code>
 103 </td>
 104 <td align="left">Perform the search on the interval [i,j) and returns the result of the search</td>
 105 </tr></tbody>
 106 </table></div>
 107 </div>
 108 <br class="table-break"><p>
 109             Various algorithms need to perform a search in a container and a Finder is a generalization of such
 110             search operations that allows algorithms to abstract from searching. For instance, generic replace
 111             algorithms can replace any part of the input, and the Finder is used to select the desired one.
 112         </p>
 113 <p>
 114             Note, that it is only required that the finder works with a particular iterator type. However,
 115             a Finder operation can be defined as a template, allowing the Finder to work with any iterator.
 116         </p>
 117 <p>
 118             <span class="bold"><strong>Examples</strong></span>
 119         </p>
 120 <p>
 121             </p>
 122 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 123 <li class="listitem">
 124                     Finder implemented as a class. This Finder always returns the whole input as a match. <code class="computeroutput">operator()</code>
 125                     is templated, so that the finder can be used on any iterator type.
 126
 127                     <pre class="programlisting">
 128 struct simple_finder
 129 {
 130     template&lt;typename ForwardIteratorT&gt;
 131     boost::iterator_range&lt;ForwardIteratorT&gt; operator()(
 132         ForwardIteratorT Begin,
 133         ForwardIteratorT End )
 134     {
 135         return boost::make_range( Begin, End );
 136     }
 137 };
 138         </pre>
 139 </li>
 140 <li class="listitem">
 141                     Function Finder. Finder can be any function object. That is, any ordinary function with the
 142                     required signature can be used as well. However, such a function can be used only for
 143                     a specific iterator type.
 144
 145                     <pre class="programlisting">
 146 boost::iterator_range&lt;std::string&gt; simple_finder(
 147     std::string::const_iterator Begin,
 148     std::string::const_iterator End )
 149 {
 150     return boost::make_range( Begin, End );
 151 }
 152         </pre>
 153 </li>
 154 </ul></div>
 155 <p>
 156         </p>
 157 </div>
 158 <div class="section">
 159 <div class="titlepage"><div><div><h3 class="title">
 160 <a name="string_algo.formatter_concept"></a>Formatter concept</h3></div></div></div>
 161 <p>
 162             Formatters are used by <a class="link" href="design.html#string_algo.replace" title="Replace Algorithms">replace algorithms</a>.
 163             They are used in close combination with finders.
 164             A formatter is a functor, which takes a result from a Finder operation and transforms it in a specific way.
 165             The operation of the formatter can use additional information provided by a specific finder,
 166             for example <code class="computeroutput"><a class="link" href="../boost/algorithm/regex_formatter.html" title="Function template regex_formatter">regex_formatter()</a></code> uses the match information from
 167             <code class="computeroutput"><a class="link" href="../boost/algorithm/regex_finder.html" title="Function template regex_finder">regex_finder()</a></code> to format the result of formatter operation.
 168         </p>
 169 <div class="table">
 170 <a name="idp125134896"></a><p class="title"><b>Table&#160;2.15.&#160;Valid Expressions</b></p>
 171 <div class="table-contents"><table class="table" summary="Valid Expressions">
 172 <colgroup>
 173 <col>
 174 <col>
 175 <col>
 176 </colgroup>
 177 <thead><tr>
 178 <th align="left">Expression</th>
 179 <th align="left">Return Type</th>
 180 <th align="left">Effects</th>
 181 </tr></thead>
 182 <tbody><tr>
 183 <td align="left"><code class="computeroutput">fmt(f(i,j))</code></td>
 184 <td align="left">A container type, accessible using container traits</td>
 185 <td align="left">Formats the result of the finder operation</td>
 186 </tr></tbody>
 187 </table></div>
 188 </div>
 189 <br class="table-break"><p>
 190             Similarly to finders, formatters generalize format operations. When a finder is used to
 191             select a part of the input, formatter takes this selection and performs some formatting
 192             on it. Algorithms can abstract from formatting using a formatter.
 193         </p>
 194 <p>
 195             <span class="bold"><strong>Examples</strong></span>
 196         </p>
 197 <p>
 198             </p>
 199 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 200 <li class="listitem">
 201                     Formatter implemented as a class. This Formatter does not perform any formatting and
 202                     returns the match, repackaged. <code class="computeroutput">operator()</code>
 203                     is templated, so that the Formatter can be used on any Finder type.
 204
 205                     <pre class="programlisting">
 206 struct simple_formatter
 207 {
 208     template&lt;typename FindResultT&gt;
 209     std::string operator()( const FindResultT&amp; Match )
 210     {
 211         std::string Temp( Match.begin(), Match.end() );
 212         return Temp;
 213     }
 214 };
 215                 </pre>
 216 </li>
 217 <li class="listitem">
 218                     Function Formatter. Similarly to Finder, Formatter can be any function object.
 219                     However, as a function, it can be used only with a specific Finder type.
 220
 221                     <pre class="programlisting">
 222 std::string simple_formatter( boost::iterator_range&lt;std::string::const_iterator&gt;&amp; Match )
 223 {
 224     std::string Temp( Match.begin(), Match.end() );
 225     return Temp;
 226 }
 227                     </pre>
 228 </li>
 229 </ul></div>
 230 <p>
 231         </p>
 232 </div>
 233 </div>
 234 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 235 <td align="left"></td>
 236 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2004 Pavol Droba<p>Use, modification and distribution is subject to the Boost
 237                 Software License, Version 1.0. (See accompanying file
 238                 <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 239             </p>
 240 </div></td>
 241 </tr></table>
 242 <hr>
 243 <div class="spirit-nav">
 244 <a accesskey="p" href="design.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string_algo.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 245 </div>
 246 </body>
 247 </html>