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<Iter></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> 102struct simple_finder 103{ 104 template<typename ForwardIteratorT> 105 boost::iterator_range<ForwardIteratorT> 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> 120boost::iterator_range<std::string> 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> 179struct simple_formatter 180{ 181 template<typename FindResultT> 182 std::string operator()( const FindResultT& 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> 195std::string simple_formatter( boost::iterator_range<std::string::const_iterator>& 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> 206