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