Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/string_algo/usage.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 23.1 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Usage</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../string_algo.html" title="Chapter 14. Boost String Algorithms Library">
9<link rel="prev" href="release_notes.html" title="Release Notes">
10<link rel="next" href="quickref.html" title="Quick Reference">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="release_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../string_algo.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="quickref.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="string_algo.usage"></a>Usage</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="usage.html#id1637783">First Example</a></span></dt>
30<dt><span class="section"><a href="usage.html#id1637979">Case conversion</a></span></dt>
31<dt><span class="section"><a href="usage.html#id1638044">Predicates and Classification</a></span></dt>
32<dt><span class="section"><a href="usage.html#id1638126">Trimming</a></span></dt>
33<dt><span class="section"><a href="usage.html#id1638194">Find algorithms</a></span></dt>
34<dt><span class="section"><a href="usage.html#id1638314">Replace Algorithms</a></span></dt>
35<dt><span class="section"><a href="usage.html#id1638440">Find Iterator</a></span></dt>
36<dt><span class="section"><a href="usage.html#id1638536">Split</a></span></dt>
37</dl></div>
38<div class="section" lang="en">
39<div class="titlepage"><div><div><h3 class="title">
40<a name="id1637783"></a>First Example</h3></div></div></div>
41<p>
42            Using the algorithms is straightforward. Let us have a look at the first example:
43        </p>
44<pre class="programlisting">
45    #include &lt;boost/algorithm/string.hpp&gt;
46    using namespace std;
47    using namespace boost;
48   
49    // ...
50
51    string str1(" hello world! ");
52    to_upper(str1);  // str1 == " HELLO WORLD! "
53    trim(str1);      // str1 == "HELLO WORLD!"
54
55    string str2=
56       to_lower_copy(
57          ireplace_first_copy(
58             str1,"hello","goodbye")); // str2 == "goodbye world!"
59        </pre>
60<p>
61            This example converts str1 to upper case and trims spaces from the start and the end
62            of the string. str2 is then created as a copy of str1 with "hello" replaced with "goodbye".
63            This example demonstrates several important concepts used in the library:
64        </p>
65<div class="itemizedlist"><ul type="disc">
66<li>
67<p><span class="bold"><strong>Container parameters:</strong></span>
68                    Unlike in the STL algorithms, parameters are not specified only in the form
69                    of iterators. The STL convention allows for great flexibility,
70                    but it has several limitations. It is not possible to <span class="emphasis"><em>stack</em></span> algorithms together,
71                    because a container is passed in two parameters. Therefore it is not possible to use
72                    a return value from another algorithm. It is considerably easier to write
73                    <code class="computeroutput">to_lower(str1)</code>, than <code class="computeroutput">to_lower(str1.begin(), str1.end())</code>.
74                </p>
75<p>
76                    The magic of <a href="../../../libs/range/index.html" target="_top">Boost.Range</a> 
77                    provides a uniform way of handling different string types.
78                    If there is a need to pass a pair of iterators,
79                    <a href="../../../libs/range/doc/utility_class.html" target="_top"><code class="computeroutput">boost::iterator_range</code></a>
80                    can be used to package iterators into a structure with a compatible interface.
81                </p>
82</li>
83<li><p><span class="bold"><strong>Copy vs. Mutable:</strong></span>
84                    Many algorithms in the library are performing a transformation of the input.
85                    The transformation can be done in-place, mutating the input sequence, or a copy
86                    of the transformed input can be created, leaving the input intact. None of
87                    these possibilities is superior to the other one and both have different
88                    advantages and disadvantages. For this reason, both are provided with the library.
89                </p></li>
90<li><p><span class="bold"><strong>Algorithm stacking:</strong></span>
91                    Copy versions return a transformed input as a result, thus allow a simple chaining of
92                    transformations within one expression (i.e. one can write <code class="computeroutput">trim_copy(to_upper_copy(s))</code>).
93                    Mutable versions have <code class="computeroutput">void</code> return, to avoid misuse.
94                </p></li>
95<li><p><span class="bold"><strong>Naming:</strong></span>
96                    Naming follows the conventions from the Standard C++ Library. If there is a
97                    copy and a mutable version of the same algorithm, the mutable version has no suffix
98                    and the copy version has the suffix <span class="emphasis"><em>_copy</em></span>.
99                    Some algorithms have the prefix <span class="emphasis"><em>i</em></span> 
100                    (e.g. <code class="computeroutput"><a href="../boost/algorithm/ifind_first.html" title="Function template ifind_first">ifind_first()</a></code>).
101                    This prefix identifies that the algorithm works in a case-insensitive manner.
102                </p></li>
103</ul></div>
104<p>
105            To use the library, include the <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.hpp" title="Header &lt;boost/algorithm/string.hpp&gt;">boost/algorithm/string.hpp</a></code> header.
106            If the regex related functions are needed, include the
107            <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string_regex.hpp" title="Header &lt;boost/algorithm/string_regex.hpp&gt;">boost/algorithm/string_regex.hpp</a></code> header.
108        </p>
109</div>
110<div class="section" lang="en">
111<div class="titlepage"><div><div><h3 class="title">
112<a name="id1637979"></a>Case conversion</h3></div></div></div>
113<p>
114            STL has a nice way of converting character case. Unfortunately, it works only
115            for a single character and we want to convert a string,
116        </p>
117<pre class="programlisting">
118    string str1("HeLlO WoRld!");
119    to_upper(str1); // str1=="HELLO WORLD!"
120        </pre>
121<p>
122            <code class="computeroutput"><a href="../boost/algorithm/to_upper.html" title="Function template to_upper">to_upper()</a></code> and <code class="computeroutput"><a href="../boost/algorithm/to_lower.html" title="Function template to_lower">to_lower()</a></code> convert the case of
123            characters in a string using a specified locale.
124        </p>
125<p>
126            For more information see the reference for <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.case_conv.hpp" title="Header &lt;boost/algorithm/string/case_conv.hpp&gt;">boost/algorithm/string/case_conv.hpp</a></code>.
127        </p>
128</div>
129<div class="section" lang="en">
130<div class="titlepage"><div><div><h3 class="title">
131<a name="id1638044"></a>Predicates and Classification</h3></div></div></div>
132<p>
133            A part of the library deals with string related predicates. Consider this example:
134        </p>
135<pre class="programlisting">
136    bool is_executable( string&amp; filename )
137    {
138        return
139            iends_with(filename, ".exe") ||
140            iends_with(filename, ".com");
141    }
142
143    // ...
144    string str1("command.com");
145    cout
146        &lt;&lt; str1
147        &lt;&lt; is_executable("command.com")? "is": "is not"
148        &lt;&lt; "an executable"
149        &lt;&lt; endl; // prints "command.com is an executable"
150   
151    //..
152    char text1[]="hello world!";
153    cout
154        &lt;&lt; text1
155        &lt;&lt; all( text1, is_lower() )? "is": "is not"
156        &lt;&lt; " written in the lower case"
157        &lt;&lt; endl; // prints "hello world! is written in the lower case"
158        </pre>
159<p>
160            The predicates determine whether if a substring is contained in the input string
161            under various conditions. The conditions are: a string starts with the substring,
162            ends with the substring,
163            simply contains the substring or if both strings are equal. See the reference for
164            <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.predicate.hpp" title="Header &lt;boost/algorithm/string/predicate.hpp&gt;">boost/algorithm/string/predicate.hpp</a></code> for more details.
165        </p>
166<p> 
167            In addition the algorithm <code class="computeroutput"><a href="../boost/algorithm/all.html" title="Function template all">all()</a></code> checks
168            all elements of a container to satisfy a condition specified by a predicate.
169            This predicate can be any unary predicate, but the library provides a bunch of
170            useful string-related predicates and combinators ready for use.
171            These are located in the <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.classification.hpp" title="Header &lt;boost/algorithm/string/classification.hpp&gt;">boost/algorithm/string/classification.hpp</a></code> header.
172            Classification predicates can be combined using logical combinators to form
173            a more complex expressions. For example: <code class="computeroutput">is_from_range('a','z') || is_digit()</code>
174        </p>
175</div>
176<div class="section" lang="en">
177<div class="titlepage"><div><div><h3 class="title">
178<a name="id1638126"></a>Trimming</h3></div></div></div>
179<p>
180            When parsing the input from a user, strings usually have unwanted leading or trailing
181            characters. To get rid of them, we need trim functions:
182        </p>
183<pre class="programlisting">
184    string str1="     hello world!     ";
185    string str2=trim_left_copy(str1);   // str2 == "hello world!     "
186    string str3=trim_right_copy(str2);  // str3 == "     hello world!"
187    trim(str1);                         // str1 == "hello world!"
188
189    string phone="00423333444";
190    // remove leading 0 from the phone number
191    trim_left_if(phone,is_any_of("0")); // phone == "423333444"
192        </pre>
193<p>
194            It is possible to trim the spaces on the right, on the left or on both sides of a string.
195            And for those cases when there is a need to remove something else than blank space, there
196            are <span class="emphasis"><em>_if</em></span> variants. Using these, a user can specify a functor which will
197            select the <span class="emphasis"><em>space</em></span> to be removed. It is possible to use classification
198            predicates like <code class="computeroutput"><a href="../boost/algorithm/is_digit.html" title="Function is_digit">is_digit()</a></code> mentioned in the previous paragraph.
199            See the reference for the <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.trim.hpp" title="Header &lt;boost/algorithm/string/trim.hpp&gt;">boost/algorithm/string/trim.hpp</a></code>.
200        </p>
201</div>
202<div class="section" lang="en">
203<div class="titlepage"><div><div><h3 class="title">
204<a name="id1638194"></a>Find algorithms</h3></div></div></div>
205<p>
206            The library contains a set of find algorithms. Here is an example:
207        </p>
208<pre class="programlisting">
209    char text[]="hello dolly!";
210    iterator_range&lt;char*&gt; result=find_last(text,"ll");
211
212    transform( result.begin(), result.end(), result.begin(), bind2nd(plus&lt;char&gt;(), 1) );
213    // text = "hello dommy!"           
214
215    to_upper(result); // text == "hello doMMy!"
216
217    // iterator_range is convertible to bool
218    if(find_first(text, "dolly"))
219    {
220        cout &lt;&lt; "Dolly is there" &lt;&lt; endl;
221    }
222        </pre>
223<p>
224            We have used <code class="computeroutput"><a href="../boost/algorithm/find_last.html" title="Function template find_last">find_last()</a></code> to search the <code class="computeroutput">text</code> for "ll".
225            The result is given in the <a href="../../../libs/range/doc/utility_class.html" target="_top"><code class="computeroutput">boost::iterator_range</code></a>.
226            This range delimits the
227            part of the input which satisfies the find criteria. In our example it is the last occurrence of "ll".
228           
229            As we can see, input of the <code class="computeroutput"><a href="../boost/algorithm/find_last.html" title="Function template find_last">find_last()</a></code> algorithm can be also
230            char[] because this type is supported by
231            <a href="../../../libs/range/index.html" target="_top">Boost.Range</a>.
232
233            The following lines transform the result. Notice that
234            <a href="../../../libs/range/doc/utility_class.html" target="_top"><code class="computeroutput">boost::iterator_range</code></a> has familiar
235            <code class="computeroutput">begin()</code> and <code class="computeroutput">end()</code> methods, so it can be used like any other STL container.
236            Also it is convertible to bool therefore it is easy to use find algorithms for a simple containment checking.
237        </p>
238<p>
239            Find algorithms are located in <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.find.hpp" title="Header &lt;boost/algorithm/string/find.hpp&gt;">boost/algorithm/string/find.hpp</a></code>.
240        </p>
241</div>
242<div class="section" lang="en">
243<div class="titlepage"><div><div><h3 class="title">
244<a name="id1638314"></a>Replace Algorithms</h3></div></div></div>
245<p>
246            Find algorithms can be used for searching for a specific part of string. Replace goes one step
247            further. After a matching part is found, it is substituted with something else. The substitution is computed
248            from the original, using some transformation.
249        </p>
250<pre class="programlisting">
251    string str1="Hello  Dolly,   Hello World!"
252    replace_first(str1, "Dolly", "Jane");      // str1 == "Hello  Jane,   Hello World!"
253    replace_last(str1, "Hello", "Goodbye");    // str1 == "Hello  Jane,   Goodbye World!"
254    erase_all(str1, " ");                      // str1 == "HelloJane,GoodbyeWorld!"
255    erase_head(str1, 6);                       // str1 == "Jane,GoodbyeWorld!"
256        </pre>
257<p>
258            For the complete list of replace and erase functions see the
259            <a href="reference.html" title="Reference">reference</a>.
260            There is a lot of predefined function for common usage, however, the library allows you to
261            define a custom <code class="computeroutput">replace()</code> that suits a specific need. There is a generic <code class="computeroutput"><a href="../boost/algorithm/find_format.html" title="Function template find_format">find_format()</a></code> 
262            function which takes two parameters.
263            The first one is a <a href="concept.html#string_algo.finder_concept" title="Finder Concept">Finder</a> object, the second one is
264            a <a href="concept.html#string_algo.formatter_concept" title="Formatter concept">Formatter</a> object.
265            The Finder object is a functor which performs the searching for the replacement part. The Formatter object
266            takes the result of the Finder (usually a reference to the found substring) and creates a
267            substitute for it. Replace algorithm puts these two together and makes the desired substitution.
268        </p>
269<p>
270            Check <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.replace.hpp" title="Header &lt;boost/algorithm/string/replace.hpp&gt;">boost/algorithm/string/replace.hpp</a></code>, <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.erase.hpp" title="Header &lt;boost/algorithm/string/erase.hpp&gt;">boost/algorithm/string/erase.hpp</a></code> and
271            <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.find_format.hpp" title="Header &lt;boost/algorithm/string/find_format.hpp&gt;">boost/algorithm/string/find_format.hpp</a></code> for reference.
272        </p>
273</div>
274<div class="section" lang="en">
275<div class="titlepage"><div><div><h3 class="title">
276<a name="id1638440"></a>Find Iterator</h3></div></div></div>
277<p>
278            An extension to find algorithms it the Find Iterator. Instead of searching for just a one part of a string,
279            the find iterator allows us to iterate over the substrings matching the specified criteria.
280            This facility is using the <a href="concept.html#string_algo.finder_concept" title="Finder Concept">Finder</a> to incrementally
281            search the string.
282            Dereferencing a find iterator yields an <a href="../../../libs/range/doc/utility_class.html" target="_top"><code class="computeroutput">boost::iterator_range</code></a> 
283            object, that delimits the current match.
284        </p>
285<p>
286            There are two iterators provided <code class="computeroutput"><a href="../boost/algorithm/find_iterator.html" title="Class template find_iterator">find_iterator</a></code> and
287            <code class="computeroutput"><a href="../boost/algorithm/split_iterator.html" title="Class template split_iterator">split_iterator</a></code>. The former iterates over substrings that are found using the specified
288            Finder. The latter iterates over the gaps between these substrings.
289        </p>
290<pre class="programlisting">
291    string str1("abc-*-ABC-*-aBc");
292    // Find all 'abc' substrings (ignoring the case)
293    // Create a find_iterator
294    typedef find_iterator&lt;string::iterator&gt; string_find_iterator;
295    for(string_find_iterator It=
296            make_find_iterator(str1, first_finder("abc", is_iequal()));
297        It!=string_find_iterator();
298        ++It)
299    {
300        cout &lt;&lt; copy_range&lt;std::string&gt;(*It) &lt;&lt; endl;
301    }
302
303    // Output will be:
304    // abc
305    // ABC
306    // aBC
307   
308    typedef split_iterator&lt;string::iterator&gt; string_split_iterator;
309    for(string_split_iterator It=
310        make_split_iterator(str1, first_finder("-*-", is_iequal()));
311        It!=string_split_iterator();
312        ++It)
313    {
314        cout &lt;&lt; copy_range&lt;std::string&gt;(*It) &lt;&lt; endl;
315    }
316
317    // Output will be:
318    // abc
319    // ABC
320    // aBC
321        </pre>
322<p>
323            Note that the find iterators have only one template parameter. It is the base iterator type.
324            The Finder is specified at runtime. This allows us to typedef a find iterator for
325            common string types and reuse it. Additionally make_*_iterator functions help
326            to construct a find iterator for a particular range.
327        </p>
328<p>
329            See the reference in <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.find_iterator.hpp" title="Header &lt;boost/algorithm/string/find_iterator.hpp&gt;">boost/algorithm/string/find_iterator.hpp</a></code>.
330        </p>
331</div>
332<div class="section" lang="en">
333<div class="titlepage"><div><div><h3 class="title">
334<a name="id1638536"></a>Split</h3></div></div></div>
335<p>
336            Split algorithms are an extension to the find iterator for one common usage scenario.
337            These algorithms use a find iterator and store all matches into the provided
338            container. This container must be able to hold copies (e.g. <code class="computeroutput">std::string</code>) or
339            references (e.g. <code class="computeroutput">iterator_range</code>) of the extracted substrings.
340        </p>
341<p>
342            Two algorithms are provided. <code class="computeroutput"><a href="../boost/algorithm/find_all.html" title="Function template find_all">find_all()</a></code> finds all copies
343            of a string in the input. <code class="computeroutput"><a href="../id691162-bb.html" title="Function template split">split()</a></code> splits the input into parts.
344        </p>
345<pre class="programlisting">
346    string str1("hello abc-*-ABC-*-aBc goodbye");
347
348    typedef vector&lt; iterator_range&lt;string::iterator&gt; &gt; find_vector_type;
349   
350    find_vector_type FindVec; // #1: Search for separators
351    ifind_all( FindVec, str1, "abc" ); // FindVec == { [abc],[ABC],[aBc] }
352
353    typedef vector&lt; string &gt; split_vector_type;
354   
355    split_vector_type SplitVec; // #2: Search for tokens
356    split( SplitVec, str1, is_any_of("-*") ); // SplitVec == { "hello abc","ABC","aBc goodbye" }
357        </pre>
358<p>
359            <code class="computeroutput">[hello]</code> designates an <code class="computeroutput">iterator_range</code> delimiting this substring.                       
360        </p>
361<p>
362            First example show how to construct a container to hold references to all extracted
363            substrings. Algorithm <code class="computeroutput"><a href="../boost/algorithm/ifind_all.html" title="Function template ifind_all">ifind_all()</a></code> puts into FindVec references
364            to all substrings that are in case-insensitive manner equal to "abc".
365        </p>
366<p>
367            Second example uses <code class="computeroutput"><a href="../id691162-bb.html" title="Function template split">split()</a></code> to split string str1 into parts
368            separated by characters '-' or '*'. These parts are then put into the SplitVec.
369            It is possible to specify if adjacent separators are concatenated or not.
370        </p>
371<p>
372            More information can be found in the reference: <code class="computeroutput"><a href="reference.html#header.boost.algorithm.string.split.hpp" title="Header &lt;boost/algorithm/string/split.hpp&gt;">boost/algorithm/string/split.hpp</a></code>.
373        </p>
374</div>
375</div>
376<table width="100%"><tr>
377<td align="left"><small><p>Last revised: January 30, 2007 at 07:58:35 GMT</p></small></td>
378<td align="right"><small>Copyright © 2002-2004 Pavol Droba</small></td>
379</tr></table>
380<hr>
381<div class="spirit-nav">
382<a accesskey="p" href="release_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../string_algo.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="quickref.html"><img src="../images/next.png" alt="Next"></a>
383</div>
384</body>
385</html>
Note: See TracBrowser for help on using the repository browser.