8f495bc015e89e57af029388fcea2e028011a02f
[platform/upstream/boost.git] / libs / algorithm / string / doc / quickref.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.quickref" last-revision="$Date: 2012-01-15 08:49:25 -0800 (Sun, 15 Jan 2012) $">
11     <title>Quick Reference</title>
12
13     <using-namespace name="boost"/>
14     <using-namespace name="boost::algorithm"/>
15
16     <section>   
17         <title>Algorithms</title>
18         
19         <table>
20             <title>Case Conversion</title>
21             <tgroup cols="3" align="left">
22                 <thead>
23                     <row>
24                         <entry>Algorithm name</entry>
25                         <entry>Description</entry>
26                         <entry>Functions</entry>
27                     </row>
28                 </thead>
29                 <tbody>
30                     <row>
31                         <entry><code>to_upper</code></entry>
32                         <entry>Convert a string to upper case</entry>
33                         <entry>
34                             <functionname>to_upper_copy()</functionname>
35                             <sbr/>
36                             <functionname>to_upper()</functionname>
37                         </entry>
38                     </row>
39                     <row>
40                         <entry><code>to_lower</code></entry>
41                         <entry>Convert a string to lower case</entry>
42                         <entry>
43                             <functionname>to_lower_copy()</functionname>
44                             <sbr/>
45                             <functionname>to_lower()</functionname>
46                         </entry>
47                     </row>
48                 </tbody>
49             </tgroup>
50         </table>
51         <table>
52             <title>Trimming</title>
53             <tgroup cols="3" align="left">
54                 <thead>
55                     <row>
56                         <entry>Algorithm name</entry>
57                         <entry>Description</entry>
58                         <entry>Functions</entry>
59                     </row>
60                 </thead>
61                 <tbody>
62                     <row>
63                         <entry><code>trim_left</code></entry>
64                         <entry>Remove leading spaces from a string</entry>
65                         <entry>
66                             <functionname>trim_left_copy_if()</functionname>
67                             <sbr/>
68                             <functionname>trim_left_if()</functionname>
69                             <sbr/>
70                             <functionname>trim_left_copy()</functionname>
71                             <sbr/>
72                             <functionname>trim_left()</functionname>
73                         </entry>
74                     </row>
75                     <row>
76                         <entry><code>trim_right</code></entry>
77                         <entry>Remove trailing spaces from a string</entry>
78                         <entry>
79                             <functionname>trim_right_copy_if()</functionname>
80                             <sbr/>
81                             <functionname>trim_right_if()</functionname>
82                             <sbr/>
83                             <functionname>trim_right_copy()</functionname>
84                             <sbr/>
85                             <functionname>trim_right()</functionname>
86                         </entry>
87                     </row>
88                     <row>
89                         <entry><code>trim</code></entry>
90                         <entry>Remove leading and trailing spaces from a string</entry>
91                         <entry>
92                             <functionname>trim_copy_if()</functionname>
93                             <sbr/>
94                             <functionname>trim_if()</functionname>
95                             <sbr/>
96                             <functionname>trim_copy()</functionname>
97                             <sbr/>
98                             <functionname>trim()</functionname>
99                         </entry>
100                     </row>
101  
102                 </tbody>
103             </tgroup>
104         </table>
105         <table>
106             <title>Predicates</title>
107             <tgroup cols="3" align="left">
108                 <thead>
109                     <row>
110                         <entry>Algorithm name</entry>
111                         <entry>Description</entry>
112                         <entry>Functions</entry>
113                     </row>
114                 </thead>
115                 <tbody>
116                     <row>
117                         <entry><code>starts_with</code></entry>
118                         <entry>Check if a string is a prefix of the other one</entry>
119                         <entry>
120                             <functionname>starts_with()</functionname>
121                             <sbr/>
122                             <functionname>istarts_with()</functionname>
123                         </entry>
124                     </row>
125                     <row>
126                         <entry><code>ends_with</code></entry>
127                         <entry>Check if a string is a suffix of the other one</entry>
128                         <entry>
129                             <functionname>ends_with()</functionname>
130                             <sbr/>
131                             <functionname>iends_with()</functionname>
132                         </entry>
133                     </row>
134                     <row>
135                         <entry><code>contains</code></entry>
136                         <entry>Check if a string is contained of the other one</entry>
137                         <entry>
138                             <functionname>contains()</functionname>
139                             <sbr/>
140                             <functionname>icontains()</functionname>
141                         </entry>
142                     </row>
143                     <row>
144                         <entry><code>equals</code></entry>
145                         <entry>Check if two strings are equal</entry>
146                         <entry>
147                             <functionname>equals()</functionname>
148                             <sbr/>
149                             <functionname>iequals()</functionname>
150                         </entry>
151                     </row>
152                     <row>
153                         <entry><code>lexicographical_compare</code></entry>
154                         <entry>Check if a string is lexicographically less then another one</entry>
155                         <entry>
156                             <functionname>lexicographical_compare()</functionname>
157                             <sbr/>
158                             <functionname>ilexicographical_compare()</functionname>
159                         </entry>
160                     </row>
161
162                     <row>
163                         <entry><code>all</code></entry>
164                         <entry>Check if all elements of a string satisfy the given predicate</entry>
165                         <entry>
166                             <functionname>all()</functionname>
167                         </entry>
168                     </row>
169                 </tbody>
170             </tgroup>
171         </table>
172         <table>
173             <title>Find algorithms</title>
174             <tgroup cols="3" align="left">
175                 <thead>
176                     <row>
177                         <entry>Algorithm name</entry>
178                         <entry>Description</entry>
179                         <entry>Functions</entry>
180                     </row>
181                 </thead>
182                 <tbody>
183                     <row>
184                         <entry>find_first</entry>
185                         <entry>Find the first occurrence of a string in the input</entry>
186                         <entry>
187                             <functionname>find_first()</functionname>
188                             <sbr/>
189                             <functionname>ifind_first()</functionname>
190                         </entry>
191                     </row>
192                     <row>
193                         <entry>find_last</entry>
194                         <entry>Find the last occurrence of a string in the input</entry>
195                         <entry>
196                             <functionname>find_last()</functionname>
197                             <sbr/>
198                             <functionname>ifind_last()</functionname>
199                         </entry>
200                     </row>
201                     <row>
202                         <entry>find_nth</entry>
203                         <entry>Find the nth (zero-indexed) occurrence of a string in the input</entry>
204                         <entry>
205                             <functionname>find_nth()</functionname>
206                             <sbr/>
207                             <functionname>ifind_nth()</functionname>
208                         </entry>
209                     </row>
210                     <row>
211                         <entry>find_head</entry>
212                         <entry>Retrieve the head of a string</entry>
213                         <entry>
214                             <functionname>find_head()</functionname>
215                         </entry>
216                     </row>                  
217                     <row>
218                         <entry>find_tail</entry>
219                         <entry>Retrieve the tail of a string</entry>
220                         <entry>
221                             <functionname>find_tail()</functionname>
222                         </entry>
223                     </row>
224                     <row>
225                         <entry>find_token</entry>
226                         <entry>Find first matching token in the string</entry>
227                         <entry>
228                             <functionname>find_token()</functionname>
229                         </entry>
230                     </row>                      
231                     <row>
232                         <entry>find_regex</entry>
233                         <entry>Use the regular expression to search the string</entry>
234                         <entry>
235                             <functionname>find_regex()</functionname>
236                         </entry>
237                     </row>                      
238                     <row>
239                         <entry>find</entry>
240                         <entry>Generic find algorithm</entry>
241                         <entry>
242                             <functionname>find()</functionname>
243                         </entry>
244                     </row>                      
245                 </tbody>
246             </tgroup>
247         </table>
248         <table>
249             <title>Erase/Replace</title>
250             <tgroup cols="3" align="left">
251                 <thead>
252                     <row>
253                         <entry>Algorithm name</entry>
254                         <entry>Description</entry>
255                         <entry>Functions</entry>
256                     </row>
257                 </thead>
258                 <tbody>
259                     <row>
260                         <entry>replace/erase_first</entry>
261                         <entry>Replace/Erase the first occurrence of a string in the input</entry>
262                         <entry>
263                             <functionname>replace_first()</functionname>
264                             <sbr/>
265                             <functionname>replace_first_copy()</functionname>
266                             <sbr/>
267                             <functionname>ireplace_first()</functionname>
268                             <sbr/>
269                             <functionname>ireplace_first_copy()</functionname>
270                             <sbr/>                      
271                             <functionname>erase_first()</functionname>
272                             <sbr/>
273                             <functionname>erase_first_copy()</functionname>
274                             <sbr/>
275                             <functionname>ierase_first()</functionname>
276                             <sbr/>
277                             <functionname>ierase_first_copy()</functionname>
278                         </entry>
279                     </row>
280                     <row>
281                         <entry>replace/erase_last</entry>
282                         <entry>Replace/Erase the last occurrence of a string in the input</entry>
283                         <entry>
284                             <functionname>replace_last()</functionname>
285                             <sbr/>
286                             <functionname>replace_last_copy()</functionname>
287                             <sbr/>
288                             <functionname>ireplace_last()</functionname>
289                             <sbr/>
290                             <functionname>ireplace_last_copy()</functionname>
291                             <sbr/>                      
292                             <functionname>erase_last()</functionname>
293                             <sbr/>
294                             <functionname>erase_last_copy()</functionname>
295                             <sbr/>
296                             <functionname>ierase_last()</functionname>
297                             <sbr/>
298                             <functionname>ierase_last_copy()</functionname>
299                         </entry>
300                     </row>
301                     <row>
302                         <entry>replace/erase_nth</entry>
303                         <entry>Replace/Erase the nth (zero-indexed) occurrence of a string in the input</entry>
304                         <entry>
305                             <functionname>replace_nth()</functionname>
306                             <sbr/>
307                             <functionname>replace_nth_copy()</functionname>
308                             <sbr/>
309                             <functionname>ireplace_nth()</functionname>
310                             <sbr/>
311                             <functionname>ireplace_nth_copy()</functionname>
312                             <sbr/>                      
313                             <functionname>erase_nth()</functionname>
314                             <sbr/>
315                             <functionname>erase_nth_copy()</functionname>
316                             <sbr/>
317                             <functionname>ierase_nth()</functionname>
318                             <sbr/>
319                             <functionname>ierase_nth_copy()</functionname>
320                         </entry>
321                     </row>
322                     <row>
323                         <entry>replace/erase_all</entry>
324                         <entry>Replace/Erase the all occurrences of a string in the input</entry>
325                         <entry>
326                             <functionname>replace_all()</functionname>
327                             <sbr/>
328                             <functionname>replace_all_copy()</functionname>
329                             <sbr/>
330                             <functionname>ireplace_all()</functionname>
331                             <sbr/>
332                             <functionname>ireplace_all_copy()</functionname>
333                             <sbr/>                      
334                             <functionname>erase_all()</functionname>
335                             <sbr/>
336                             <functionname>erase_all_copy()</functionname>
337                             <sbr/>
338                             <functionname>ierase_all()</functionname>
339                             <sbr/>
340                             <functionname>ierase_all_copy()</functionname>
341                         </entry>
342                     </row>
343                     <row>
344                         <entry>replace/erase_head</entry>
345                         <entry>Replace/Erase the head of the input</entry>
346                         <entry>
347                             <functionname>replace_head()</functionname>
348                             <sbr/>
349                             <functionname>replace_head_copy()</functionname>
350                             <sbr/>
351                             <functionname>erase_head()</functionname>
352                             <sbr/>
353                             <functionname>erase_head_copy()</functionname>
354                             <sbr/>
355                         </entry>
356                     </row>
357                     <row>
358                         <entry>replace/erase_tail</entry>
359                         <entry>Replace/Erase the tail of the input</entry>
360                         <entry>
361                             <functionname>replace_tail()</functionname>
362                             <sbr/>
363                             <functionname>replace_tail_copy()</functionname>
364                             <sbr/>
365                             <functionname>erase_tail()</functionname>
366                             <sbr/>
367                             <functionname>erase_tail_copy()</functionname>
368                             <sbr/>
369                         </entry>
370                     </row>
371                     <row>
372                         <entry>replace/erase_regex</entry>
373                         <entry>Replace/Erase a substring matching the given regular expression</entry>
374                         <entry>
375                             <functionname>replace_regex()</functionname>
376                             <sbr/>
377                             <functionname>replace_regex_copy()</functionname>
378                             <sbr/>
379                             <functionname>erase_regex()</functionname>
380                             <sbr/>
381                             <functionname>erase_regex_copy()</functionname>
382                             <sbr/>
383                         </entry>
384                     </row>
385                     <row>
386                         <entry>replace/erase_regex_all</entry>
387                         <entry>Replace/Erase all substrings matching the given regular expression</entry>
388                         <entry>
389                             <functionname>replace_all_regex()</functionname>
390                             <sbr/>
391                             <functionname>replace_all_regex_copy()</functionname>
392                             <sbr/>
393                             <functionname>erase_all_regex()</functionname>
394                             <sbr/>
395                             <functionname>erase_all_regex_copy()</functionname>
396                             <sbr/>
397                         </entry>
398                     </row>
399                     <row>
400                         <entry>find_format</entry>
401                         <entry>Generic replace algorithm</entry>
402                         <entry>
403                             <functionname>find_format()</functionname>
404                             <sbr/>
405                             <functionname>find_format_copy()</functionname>
406                             <sbr/>
407                             <functionname>find_format_all()</functionname>
408                             <sbr/>
409                             <functionname>find_format_all_copy()()</functionname>
410                         </entry>
411                     </row>
412                 </tbody>
413             </tgroup>
414         </table>
415         <table>
416             <title>Split</title>
417             <tgroup cols="3" align="left">
418                 <thead>
419                     <row>
420                         <entry>Algorithm name</entry>
421                         <entry>Description</entry>
422                         <entry>Functions</entry>
423                     </row>
424                 </thead>
425                 <tbody>
426                     <row>
427                         <entry>find_all</entry>
428                         <entry>Find/Extract all matching substrings in the input</entry>
429                         <entry>
430                             <functionname>find_all()</functionname>
431                             <sbr/>
432                             <functionname>ifind_all()</functionname>
433                             <sbr/>
434                             <functionname>find_all_regex()</functionname>
435                         </entry>
436                     </row>
437                     <row>
438                         <entry>split</entry>
439                         <entry>Split input into parts</entry>
440                         <entry>
441                             <functionname>split()</functionname>
442                             <sbr/>
443                             <functionname>split_regex()</functionname>
444                         </entry>
445                                         </row>
446                                         <row>
447                                                 <entry>iter_find</entry>
448                                                 <entry>Iteratively apply the finder to the input to find all matching substrings</entry>
449                                                 <entry>
450                                                         <functionname>iter_find()</functionname>
451                                                 </entry>
452                                         </row>
453                                         <row>
454                                                 <entry>iter_split</entry>
455                                                 <entry>Use the finder to find matching substrings in the input and use them as separators to split the input into parts</entry>
456                                                 <entry>
457                                                         <functionname>iter_split()</functionname>
458                                                 </entry>
459                                         </row>
460                 </tbody>
461             </tgroup>
462         </table>
463         <table>
464             <title>Join</title>
465             <tgroup cols="3" align="left">
466                 <thead>
467                     <row>
468                         <entry>Algorithm name</entry>
469                         <entry>Description</entry>
470                         <entry>Functions</entry>
471                     </row>
472                 </thead>
473                 <tbody>
474                     <row>
475                         <entry>join</entry>
476                         <entry>Join all elements in a container into a single string</entry>
477                         <entry>
478                             <functionname>join</functionname>
479                         </entry>
480                     </row>
481                         <row>
482                         <entry>join_if</entry>
483                         <entry>Join all elements in a container that satisfies the condition into a single string</entry>
484                         <entry>
485                             <functionname>join_if()</functionname>
486                         </entry>
487                    </row>
488                 </tbody>
489             </tgroup>
490         </table>
491     </section>
492     <section>
493         <title>Finders and Formatters</title>
494         
495         <table>
496             <title>Finders</title>
497             <tgroup cols="3" align="left">
498                 <thead>
499                     <row>
500                         <entry>Finder</entry>
501                         <entry>Description</entry>
502                         <entry>Generators</entry>
503                     </row>
504                 </thead>
505                 <tbody>
506                     <row>
507                         <entry>first_finder</entry>
508                         <entry>Search for the first match of the string in an input</entry>
509                         <entry>
510                             <functionname>first_finder()</functionname>
511                         </entry>
512                     </row>
513                     <row>
514                         <entry>last_finder</entry>
515                         <entry>Search for the last match of the string in an input</entry>
516                         <entry>
517                             <functionname>last_finder()</functionname>
518                         </entry>
519                     </row>
520                     <row>
521                         <entry>nth_finder</entry>
522                         <entry>Search for the nth (zero-indexed) match of the string in an input</entry>
523                         <entry>
524                             <functionname>nth_finder()</functionname>
525                         </entry>
526                     </row>
527                     <row>
528                         <entry>head_finder</entry>
529                         <entry>Retrieve the head of an input</entry>
530                         <entry>
531                             <functionname>head_finder()</functionname>
532                         </entry>
533                     </row>
534                     <row>
535                         <entry>tail_finder</entry>
536                         <entry>Retrieve the tail of an input</entry>
537                         <entry>
538                             <functionname>tail_finder()</functionname>
539                         </entry>
540                     </row>
541                     <row>
542                         <entry>token_finder</entry>
543                         <entry>Search for a matching token in an input</entry>
544                         <entry>
545                             <functionname>token_finder()</functionname>
546                         </entry>
547                     </row>
548                     <row>
549                         <entry>range_finder</entry>
550                         <entry>Do no search, always returns the given range</entry>
551                         <entry>
552                             <functionname>range_finder()</functionname>
553                         </entry>
554                     </row>
555                     <row>
556                         <entry>regex_finder</entry>
557                         <entry>Search for a substring matching the given regex</entry>
558                         <entry>
559                             <functionname>regex_finder()</functionname>
560                         </entry>
561                     </row>
562                 </tbody>
563             </tgroup>
564         </table>
565
566         <table>
567             <title>Formatters</title>
568             <tgroup cols="3" align="left">
569                 <thead>
570                     <row>
571                         <entry>Formatter</entry>
572                         <entry>Description</entry>
573                         <entry>Generators</entry>
574                     </row>
575                 </thead>
576                 <tbody>
577                     <row>
578                         <entry>const_formatter</entry>
579                         <entry>Constant formatter. Always return the specified string</entry>
580                         <entry>
581                             <functionname>const_formatter()</functionname>
582                         </entry>                                                
583                     </row>
584                     <row>
585                         <entry>identity_formatter</entry>
586                         <entry>Identity formatter. Return unmodified input input</entry>
587                         <entry>
588                             <functionname>identity_formatter()</functionname>
589                         </entry>
590                     </row>
591                     <row>
592                         <entry>empty_formatter</entry>
593                         <entry>Null formatter. Always return an empty string</entry>
594                         <entry>
595                             <functionname>empty_formatter()</functionname>
596                         </entry>
597                     </row>
598                     <row>
599                         <entry>regex_formatter</entry>
600                         <entry>Regex formatter. Format regex match using the specification in the format string</entry>
601                         <entry>
602                             <functionname>regex_formatter()</functionname>
603                         </entry>
604                     </row>
605                 </tbody>
606             </tgroup>
607         </table>
608     </section>
609     <section>
610         <title>Iterators</title>
611         
612         <table>
613             <title>Find Iterators</title>
614             <tgroup cols="3" align="left">
615                 <thead>
616                     <row>
617                         <entry>Iterator name</entry>
618                         <entry>Description</entry>
619                         <entry>Iterator class</entry>
620                     </row>
621                 </thead>
622                 <tbody>
623                     <row>
624                         <entry>find_iterator</entry>
625                         <entry>Iterates through matching substrings in the input</entry>
626                         <entry>
627                             <classname>find_iterator</classname>
628                         </entry>
629                     </row>
630                     <row>
631                         <entry>split_iterator</entry>
632                         <entry>Iterates through gaps between matching substrings in the input</entry>
633                         <entry>
634                             <classname>split_iterator</classname>
635                         </entry>
636                     </row>              
637                 </tbody>
638             </tgroup>
639         </table>
640     </section>
641     
642     <section>
643         <title>Classification</title>
644         
645         <table>
646             <title>Predicates</title>
647             <tgroup cols="3" align="left">
648                 <thead>
649                     <row>
650                         <entry>Predicate name</entry>
651                         <entry>Description</entry>
652                         <entry>Generator</entry>
653                     </row>
654                 </thead>
655                 <tbody>
656                     <row>
657                         <entry>is_classified</entry>
658                         <entry>Generic <code>ctype</code> mask based classification</entry>
659                         <entry>
660                             <functionname>is_classified()</functionname>
661                         </entry>
662                     </row>
663                     <row>
664                         <entry>is_space</entry>
665                         <entry>Recognize spaces</entry>
666                         <entry>
667                             <functionname>is_space()</functionname>
668                         </entry>
669                     </row>
670                     <row>
671                         <entry>is_alnum</entry>
672                         <entry>Recognize alphanumeric characters</entry>
673                         <entry>
674                             <functionname>is_alnum()</functionname>
675                         </entry>
676                     </row>
677                     <row>
678                         <entry>is_alpha</entry>
679                         <entry>Recognize letters</entry>
680                         <entry>
681                             <functionname>is_alpha()</functionname>
682                         </entry>
683                     </row>
684                     <row>
685                         <entry>is_cntrl</entry>
686                         <entry>Recognize control characters</entry>
687                         <entry>
688                             <functionname>is_cntrl()</functionname>
689                         </entry>
690                     </row>
691                     <row>
692                         <entry>is_digit</entry>
693                         <entry>Recognize decimal digits</entry>
694                         <entry>
695                             <functionname>is_digit()</functionname>
696                         </entry>
697                     </row>
698                     <row>
699                         <entry>is_graph</entry>
700                         <entry>Recognize graphical characters</entry>
701                         <entry>
702                             <functionname>is_graph()</functionname>
703                         </entry>
704                     </row>
705                     <row>
706                         <entry>is_lower</entry>
707                         <entry>Recognize lower case characters</entry>
708                         <entry>
709                             <functionname>is_lower()</functionname>
710                         </entry>
711                     </row>
712                     <row>
713                         <entry>is_print</entry>
714                         <entry>Recognize printable characters</entry>
715                         <entry>
716                             <functionname>is_print()</functionname>
717                         </entry>
718                     </row>
719                     <row>
720                         <entry>is_punct</entry>
721                         <entry>Recognize punctuation characters</entry>
722                         <entry>
723                             <functionname>is_punct()</functionname>
724                         </entry>
725                     </row>
726                     <row>
727                         <entry>is_upper</entry>
728                         <entry>Recognize uppercase characters</entry>
729                         <entry>
730                             <functionname>is_upper()</functionname>
731                         </entry>
732                     </row>
733                     <row>
734                         <entry>is_xdigit</entry>
735                         <entry>Recognize hexadecimal digits</entry>
736                         <entry>
737                             <functionname>is_xdigit()</functionname>
738                         </entry>
739                     </row>
740                     <row>
741                         <entry>is_any_of</entry>
742                         <entry>Recognize any of a sequence of characters</entry>
743                         <entry>
744                             <functionname>is_any_of()</functionname>
745                         </entry>
746                     </row>
747                     <row>
748                         <entry>is_from_range</entry>
749                         <entry>Recognize characters inside a min..max range</entry>
750                         <entry>
751                             <functionname>is_from_range()</functionname>
752                         </entry>
753                     </row>
754                 </tbody>
755             </tgroup>
756         </table>
757     </section>
758 </section>