feedc0de/boost_algorithm
1
0
Fork 0
forked from boostorg/algorithm
Code Pull Requests Activity

Documentation update

Browse Source 
[SVN r23559]
This commit is contained in:
Pavol Droba
2004-07-14 21:46:50 +00:00
parent 8cf6df3ad6
commit 54075a951b
10 changed files with 1022 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
string/doc/usage.xml
View File

@ -5,7 +5,7 @@
<title>Usage</title>
<using-namespace name="boost"/>
<using-namespace name="boost::string_algo"/>
<using-namespace name="boost::algorithm"/>
<section>
@ -18,14 +18,17 @@
#include &lt;boost/string_algo.hpp&gt;
using namespace std;
using namespace boost;
namespace sa=boost::string_algo
// ...
string str1(" hello world! ");
trim( to_upper(str1) ); // str1 == "HELLO WORLD!"
to_upper(str1); // str1 == " HELLO WORLD! "
trim(str1); // str1 == "HELLOW WORLD!"
string str2=ireplace_first_copy(str1,"hello","goodbye"); // str2 == "goodbye WORLD!"
string str2=
to_lower_copy(
ireplace_first_copy(
str1,"hello","goodbye")); // str2 == "goodbye world!"
</programlisting>
<para>
This example converts str1 to upper case and trims spaces from the start and the end
@ -43,11 +46,11 @@
<code>to_lower(str1)</code>, then <code>to_lower(str1.begin(), str1.end())</code>.
</para>
<para>
The magic of <link linkend="string_algo.container_traits">container_traits</link>
provides a uniform way of handling different containers.
The magic of <link linkend="string_algo.collection_traits">collection_traits</link>
provides a uniform way of handling different string types.
If there is a need to pass a pair of iterators,
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
can be used to package iterators into a structure with the container interface.
can be used to package iterators into a structure with the compatible interface.
</para>
</listitem>
<listitem>
@ -61,10 +64,9 @@
</listitem>
<listitem>
<para><emphasis role="bold">Algorithm stacking:</emphasis>
Copy versions return a transformed input as a result. Mutable variants return
a reference to the input. Thus both versions allow a simple chaining of
transformations within one expression (i.e. one can write
<code>trim_copy(to_upper_copy(s))</code> as well as <code>trim(to_upper(s))</code>).
Copy versions return a transformed input as a result, thus allow a simple chaining of
transformations within one expression (i.e. one can write <code>trim_copy(to_upper_copy(s))</code>).
Mutable versions have <code>void</code> return, to avoid missuse.
</para>
</listitem>
<listitem>
@ -79,9 +81,9 @@
</listitem>
</itemizedlist>
<para>
To use the library, include the <headername>boost/string_algo.hpp</headername> header.
To use the library, include the <headername>boost/algorithm/string.hpp</headername> header.
If the regex related functions are needed, include the
<headername>boost/string_algo_regex.hpp</headername> header.
<headername>boost/algorithm/string_regex.hpp</headername> header.
</para>
</section>
<section>
@ -97,7 +99,10 @@
</programlisting>
<para>
<functionname>to_upper()</functionname> and <functionname>to_lower()</functionname> convert the case of
characters in a container using a specified locale.
characters in a string using a specified locale.
</para>
<para>
For more information see the reference for <headername>boost/algorithm/string/case_conv.hpp</headername>.
</para>
</section>
<section>
@ -125,7 +130,7 @@
char text1[]="hello world!";
cout
&lt;&lt; text1
&lt;&lt; all( text1, is_lower&lt;char&gt;() )? "is": "is not"
&lt;&lt; all( text1, is_lower() )? "is": "is not"
&lt;&lt; "written in the lower case"
&lt;&lt; endl; // prints "hello world! is written in the lower case"
</programlisting>
@ -134,12 +139,16 @@
under various conditions. The conditions are if a string starts with the substring,
ends with the substring,
simply contains the substring or if both strings are equal. See the reference for
<headername>boost/string_algo/predicate.hpp</headername> for more details.
<headername>boost/algorithm/string/predicate.hpp</headername> for more details.
</para>
<para>
In addition the algorithm <functionname>all()</functionname> checks
all elements of a container to satisfy a condition specified by a predicate.
This predicate can be any unary predicate, but the library provides a bunch of
useful string-related predicates ready for use.
These are located in the <headername>boost/string_algo/classification.hpp</headername> header.
useful string-related predicates and combinators ready for use.
These are located in the <headername>boost/algorithm/string/classification.hpp</headername> header.
Classification predicates can be combined using logical combinators for form
a more complicated expressions. For example: <code>is_from_range('a','z') || is_digit()</code>
</para>
</section>
<section>
@ -157,15 +166,15 @@
string phone="00423333444";
// remove leading 0 from the phone number
sa::trim_left(phone,is_any_of&lt;char&gt;("0")); // phone == "423333444"
trim_left_if(phone,is_any_of("0")); // phone == "423333444"
</programlisting>
<para>
It is possible to trim the spaces on the right, on the left or on the both sides of a string.
And for those cases when there is a need to remove something else than blank space, the
<code>string_algo</code> namespace contains generic versions of the trim algorithms. Using these,
a user can specify a functor which will select the <emphasis>space</emphasis> to be removed. It is possible to use
classification predicates like <functionname>is_digit()</functionname> mentioned in the previous paragraph.
See the reference for the <headername>boost/string_algo/trim.hpp</headername>.
And for those cases when there is a need to remove something else than blank space, there
are <emphasis>_if</emphasis> variants. Using these, a user can specify a functor which will
select the <emphasis>space</emphasis> to be removed. It is possible to use classification
predicates like <functionname>is_digit()</functionname> mentioned in the previous paragraph.
See the reference for the <headername>boost/algorithm/string/trim.hpp</headername>.
</para>
</section>
<section>
@ -191,17 +200,20 @@
As we can see, input of the <functionname>find_last()</functionname> algorithm can be also
char[] because this type is supported by
<link linkend="string_algo.container_traits">container_traits</link>.
<link linkend="string_algo.collection_traits">collection_traits</link>.
Following lines transform the result. Notice, that
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link> have familiar
<code>begin()</code> and <code>end()</code> methods, so it can be used like any other STL container.
</para>
<para>
Find algorithms are located in <headername>boost/algorithm/string/find.hpp</headername>.
</para>
</section>
<section>
<title>Replace Algorithms</title>
<para>
Find algorithms can be used for searching for a specific part of the sequence. Replace goes one step
Find algorithms can be used for searching for a specific part of string. Replace goes one step
further. After a matching part is found, it is substituted with something else. The substitution is computed
from an original, using some transformation.
</para>
@ -216,7 +228,7 @@
For the complete list of replace and erase functions see the
<link linkend="string_algo.reference">reference</link>.
There is a lot of predefined function for common usage, however, the library allows you to
define a custom <code>replace()</code> that suits a specific need. There is a generic <functionname>replace()</functionname>
define a custom <code>replace()</code> that suits a specific need. There is a generic <functionname>find_format()</functionname>
function which takes two parameters.
The first one is a <link linkend="string_algo.finder_concept">Finder</link> object, the second one is
a <link linkend="string_algo.formatter_concept">Formatter</link> object.
@ -224,14 +236,81 @@
takes the result of the Finder (usually a reference to the found substring) and creates a
substitute for it. Replace algorithm puts these two together and makes the desired substitution.
</para>
<para>
Check <headername>boost/algorithm/string/replace.hpp</headername>, <headername>boost/algorithm/string/erase.hpp</headername> and
<headername>boost/algorithm/string/find_format.hpp</headername> for reference.
</para>
</section>
<section>
<title>Find Iterator</title>
<para>
An extension to find algorithms it the Find Iterator. Instead of searching for just a one part of a string,
the find iterator allows us to iterate over the substrings matching the specified criterium.
This facility is using the <link linkend="string_algo.finder_concept">Finder</link> to incrementaly
search the string.
Dereferencing a find iterator yields an <link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
object, that delimits the current match.
</para>
<para>
There are two iterators provided <classname>find_iterator</classname> and
<classname>split_iterator</classname>. First one iterates over substrings that are found using the specified
Finder. The second one iterates over the gasps between these substrings.
</para>
<programlisting>
string str1("abc-*-ABC-*-aBc");
// Find all 'abc' substrings (ignoring the case)
// Create a find_iterator
typedef find_iterator&lt;string::iterator&gt; string_find_iterator;
for(string_find_iterator It=
make_find_iterator(str1, first_finder("abc", is_iequal()));
It!=string_find_iterator();
++It)
{
cout &lt;&lt; copy_iterator_range&lt;std::string&gt;(*It) &lt;&lt; endl;
}
// Output will be:
// abc
// ABC
// aBC
typedef split_iterator&lt;string::iterator&gt; string_split_iterator;
for(string_find_iterator It=
make_split_iterator(str1, first_finder("-*-", is_iequal()));
It!=string_find_iterator();
++It)
{
cout &lt;&lt; copy_iterator_range&lt;std::string&gt;(*It) &lt;&lt; endl;
}
// Output will be:
// abc
// ABC
// aBC
</programlisting>
<para>
Note that find iterators have only one template parameter. It is the base iterator type.
Finder is specified at runtime. This allows us to typedef a find iterator for
a common string types and reuse it. Additionaly make_*_iterator functions helps
to contruct a find iterator for a particular collection.
</para>
<para>
See the reference in <headername>boost/algorithm/string/find_iterator.hpp</headername>.
</para>
</section>
<section>
<title>Split</title>
<para>
Split algorithms allow one to divide a sequence into parts. Each part represents a
<emphasis>token</emphasis> and tokens are separated by <emphasis>separators</emphasis>.
One can either search for tokens or search for separators:
Split algorithms are an extension to the find iterator for one common usage scenario.
These algorithms use a find iterator and store all matches into the provided
container. This container must be able to hold copies (f.e std::string) or
references (f.e. iterator_range) of the extracted substrings.
</para>
<para>
Two algorithms are provided. <functionname>find_all()</functionname> finds all copies
of a string in the input. <functionname>split()</functionname> splits the input into parts.
</para>
<programlisting>
@ -251,25 +330,17 @@
<code>[hello]</code> designates an <code>iterator_range</code> delimiting this substring.
</para>
<para>
The result of a split algorithm is a <emphasis>container of containers</emphasis>. There is only one restriction:
The inner container type must be able to hold extracted parts of the input sequence. This example
shows the special case where the inner container is an
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
instead of e.g. <code>std::string</code>. This way, a user gets a reference
(in the form of iterators) delimiting the parts of the input sequence. Otherwise, a copy of
each extracted part is created and added to the outer container.
First example show how to construct a container to hold references to all extracted
substrings. Algorithm <functionname>ifind_all()</functionname> puts into FindVec references
to all substrings that are in case-insensitive manner equal to "abc".
</para>
<para>
So to recap, there are two basic algorithms: <functionname>find_all()</functionname>
returns extracts the parts
matching the specification whereas <functionname>split()</functionname> uses the matching
parts as delimiters, and extracts the parts in between them.
Second example uses <functionname>split()</functionname> to split string str1 into parts
separated by characters '-' or '*'. These parts are then put into the SplitVec.
It is possible to specify if adjacent separators are concatenated or not.
</para>
<para>
Generalizations of these two algorithms are called <functionname>iter_find()</functionname> and
<functionname>iter_split()</functionname>. They take a
<link linkend="string_algo.finder_concept">Finder</link> object, as an argument to search for
the substring.
</para>
</section>
More information can be found in the reference: <headername>boost/algorithm/string/split.hpp</headername>.
</para>
</section>
</section>