]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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> | |
102 | struct 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> | |
120 | boost::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> | |
179 | struct 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> | |
195 | std::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> |