ceph/src/boost/libs/algorithm/string/doc/concept.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4
   5 <!-- Copyright (c) 2002-2006 Pavol Droba.
   6      Subject to the Boost Software License, Version 1.0.
   7      (See accompanying file LICENSE_1_0.txt or  http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9
  10 <section id="string_algo.concept" last-revision="$Date$">
  11     <title>Concepts</title>
  12
  13     <using-namespace name="boost"/>
  14     <using-namespace name="boost::algorithm"/>
  15
  16     <section>
  17         <title>Definitions</title>
  18
  19         <table>
  20             <title>Notation</title>
  21             <tgroup cols="2" align="left">
  22                 <tbody>
  23                     <row>
  24                         <entry><code>F</code></entry>
  25                         <entry>A type that is a model of Finder</entry>
  26                     </row>
  27                     <row>
  28                         <entry><code>Fmt</code></entry>
  29                         <entry>A type that is a model of Formatter</entry>
  30                     </row>
  31                     <row>
  32                         <entry><code>Iter</code></entry>
  33                         <entry>
  34                             Iterator Type
  35                         </entry>
  36                     </row>
  37                     <row>
  38                         <entry><code>f</code></entry>
  39                         <entry>Object of type <code>F</code></entry>
  40                     </row>
  41                     <row>
  42                         <entry><code>fmt</code></entry>
  43                         <entry>Object of type <code>Fmt</code></entry>
  44                     </row>
  45                     <row>
  46                         <entry><code>i,j</code></entry>
  47                         <entry>Objects of type <code>Iter</code></entry>
  48                     </row>
  49                     </tbody>
  50             </tgroup>
  51         </table>
  52     </section>
  53
  54     <section id="string_algo.finder_concept">
  55         <title>Finder Concept</title>
  56
  57         <para>
  58             Finder is a functor which searches for an arbitrary part of a container.
  59             The result of the search is given as an <classname>iterator_range</classname>
  60             delimiting the selected part.
  61         </para>
  62
  63         <table>
  64             <title>Valid Expressions</title>
  65             <tgroup cols="3" align="left">
  66                 <thead>
  67                     <row>
  68                         <entry>Expression</entry>
  69                         <entry>Return Type</entry>
  70                         <entry>Effects</entry>
  71                     </row>
  72                 </thead>
  73                 <tbody>
  74                     <row>
  75                         <entry><code>f(i,j)</code></entry>
  76                         <entry>Convertible to <code>iterator_range&lt;Iter&gt;</code></entry>
  77                         <entry>Perform the search on the interval [i,j) and returns the result of the search</entry>
  78                     </row>
  79                 </tbody>
  80             </tgroup>
  81         </table>
  82
  83         <para>
  84             Various algorithms need to perform a search in a container and a Finder is a generalization of such
  85             search operations that allows algorithms to abstract from searching. For instance, generic replace
  86             algorithms can replace any part of the input, and the Finder is used to select the desired one.
  87         </para>
  88         <para>
  89             Note, that it is only required that the finder works with a particular iterator type. However,
  90             a Finder operation can be defined as a template, allowing the Finder to work with any iterator.
  91         </para>
  92         <para>
  93             <emphasis role="bold">Examples</emphasis>
  94         </para>
  95         <para>
  96             <itemizedlist>
  97                 <listitem>
  98                     Finder implemented as a class. This Finder always returns the whole input as a match. <code>operator()</code>
  99                     is templated, so that the finder can be used on any iterator type.
 100
 101                     <programlisting>
 102 struct simple_finder
 103 {
 104     template&lt;typename ForwardIteratorT&gt;
 105     boost::iterator_range&lt;ForwardIteratorT&gt; operator()(
 106         ForwardIteratorT Begin,
 107         ForwardIteratorT End )
 108     {
 109         return boost::make_range( Begin, End );
 110     }
 111 };
 112         </programlisting>
 113                 </listitem>
 114                 <listitem>
 115                     Function Finder. Finder can be any function object. That is, any ordinary function with the
 116                     required signature can be used as well. However, such a function can be used only for
 117                     a specific iterator type.
 118
 119                     <programlisting>
 120 boost::iterator_range&lt;std::string&gt; simple_finder(
 121     std::string::const_iterator Begin,
 122     std::string::const_iterator End )
 123 {
 124     return boost::make_range( Begin, End );
 125 }
 126         </programlisting>
 127                 </listitem>
 128             </itemizedlist>
 129         </para>
 130     </section>
 131     <section id="string_algo.formatter_concept">
 132         <title>Formatter concept</title>
 133
 134         <para>
 135             Formatters are used by <link linkend="string_algo.replace">replace algorithms</link>.
 136             They are used in close combination with finders.
 137             A formatter is a functor, which takes a result from a Finder operation and transforms it in a specific way.
 138             The operation of the formatter can use additional information provided by a specific finder,
 139             for example <functionname>regex_formatter()</functionname> uses the match information from
 140             <functionname>regex_finder()</functionname> to format the result of formatter operation.
 141         </para>
 142
 143         <table>
 144             <title>Valid Expressions</title>
 145             <tgroup cols="3" align="left">
 146                 <thead>
 147                     <row>
 148                         <entry>Expression</entry>
 149                         <entry>Return Type</entry>
 150                         <entry>Effects</entry>
 151                     </row>
 152                 </thead>
 153                 <tbody>
 154                    <row>
 155                         <entry><code>fmt(f(i,j))</code></entry>
 156                         <entry>A container type, accessible using container traits</entry>
 157                         <entry>Formats the result of the finder operation</entry>
 158                     </row>
 159                 </tbody>
 160             </tgroup>
 161         </table>
 162
 163         <para>
 164             Similarly to finders, formatters generalize format operations. When a finder is used to
 165             select a part of the input, formatter takes this selection and performs some formatting
 166             on it. Algorithms can abstract from formatting using a formatter.
 167         </para>
 168         <para>
 169             <emphasis role="bold">Examples</emphasis>
 170         </para>
 171         <para>
 172             <itemizedlist>
 173                 <listitem>
 174                     Formatter implemented as a class. This Formatter does not perform any formatting and
 175                     returns the match, repackaged. <code>operator()</code>
 176                     is templated, so that the Formatter can be used on any Finder type.
 177
 178                     <programlisting>
 179 struct simple_formatter
 180 {
 181     template&lt;typename FindResultT&gt;
 182     std::string operator()( const FindResultT&amp; Match )
 183     {
 184         std::string Temp( Match.begin(), Match.end() );
 185         return Temp;
 186     }
 187 };
 188                 </programlisting>
 189                 </listitem>
 190                 <listitem>
 191                     Function Formatter. Similarly to Finder, Formatter can be any function object.
 192                     However, as a function, it can be used only with a specific Finder type.
 193
 194                     <programlisting>
 195 std::string simple_formatter( boost::iterator_range&lt;std::string::const_iterator&gt;&amp; Match )
 196 {
 197     std::string Temp( Match.begin(), Match.end() );
 198     return Temp;
 199 }
 200                     </programlisting>
 201                 </listitem>
 202             </itemizedlist>
 203         </para>
 204      </section>
 205 </section>