boostorg/algorithm
1
0
Fork 1
mirror of https://github.com/boostorg/algorithm.git synced 2025-07-29 12:07:18 +02:00
Code Issues Packages Projects Releases Wiki 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

66
string/doc/Jamfile.v2
View File

@ -7,41 +7,39 @@
#
# See htt../..//www.boost.org for updates, documentation, and revision history.
project boost/libs/algorithm/string/doc ;
import toolset ;
toolset.using doxygen ;
doxygen reference
import path ;
boostbook string_algo : string_algo.xml ;
doxygen autodoc
:
../../../../boost/algorithm/string.hpp
../../../../boost/algorithm/string_regex.hpp
[ glob ../../../../boost/algorithm/string.hpp ]
[ glob ../../../../boost/algorithm/string_regex.hpp ]
../../../../boost/algorithm/string/classification.hpp
../../../../boost/algorithm/string/iterator_range.hpp
../../../../boost/algorithm/string/sequence_traits.hpp
../../../../boost/algorithm/string/std_containers_traits.hpp
../../../../boost/algorithm/string/collection_traits.hpp
../../../../boost/algorithm/string/concept.hpp
../../../../boost/algorithm/string/compare.hpp
../../../../boost/algorithm/string/constants.hpp
../../../../boost/algorithm/string/case_conv.hpp
../../../../boost/algorithm/string/find.hpp
../../../../boost/algorithm/string/finder.hpp
../../../../boost/algorithm/string/find_iterator.hpp
../../../../boost/algorithm/string/trim.hpp
../../../../boost/algorithm/string/predicate.hpp
../../../../boost/algorithm/string/split.hpp
../../../../boost/algorithm/string/iter_find.hpp
../../../../boost/algorithm/string/erase.hpp
../../../../boost/algorithm/string/replace.hpp
../../../../boost/algorithm/string/find_format.hpp
../../../../boost/algorithm/string/formatter.hpp
../../../../boost/algorithm/string/regex.hpp
../../../../boost/algorithm/string/regex_find_format.hpp
[ glob ../../../../boost/algorithm/string/classification.hpp ]
[ glob ../../../../boost/algorithm/string/iterator_range.hpp ]
[ glob ../../../../boost/algorithm/string/sequence_traits.hpp ]
[ glob ../../../../boost/algorithm/string/std_containers_traits.hpp ]
[ glob ../../../../boost/algorithm/string/collection_traits.hpp ]
[ glob ../../../../boost/algorithm/string/concept.hpp ]
[ glob ../../../../boost/algorithm/string/compare.hpp ]
[ glob ../../../../boost/algorithm/string/constants.hpp ]
[ glob ../../../../boost/algorithm/string/case_conv.hpp ]
[ glob ../../../../boost/algorithm/string/find.hpp ]
[ glob ../../../../boost/algorithm/string/finder.hpp ]
[ glob ../../../../boost/algorithm/string/find_iterator.hpp ]
[ glob ../../../../boost/algorithm/string/trim.hpp ]
[ glob ../../../../boost/algorithm/string/predicate.hpp ]
[ glob ../../../../boost/algorithm/string/split.hpp ]
[ glob ../../../../boost/algorithm/string/erase.hpp ]
[ glob ../../../../boost/algorithm/string/replace.hpp ]
[ glob ../../../../boost/algorithm/string/find_format.hpp ]
[ glob ../../../../boost/algorithm/string/formatter.hpp ]
[ glob ../../../../boost/algorithm/string/regex.hpp ]
[ glob ../../../../boost/algorithm/string/regex_find_format.hpp ]
:
<doxygen:param>HIDE_UNDOC_MEMBERS=YES
<doxygen:param>EXTRACT_PRIVATE=NO
@ -52,10 +50,6 @@ doxygen reference
<doxygen:param>PREDEFINED="BOOST_STRING_TYPENAME=typename \"BOOST_STATIC_CONSTANT(type,var)=static const type var;\""
;
boostbook string_algo
:
string_algo.xml
;

2
string/doc/concept.xml
View File

@ -5,7 +5,7 @@
<title>Concepts</title>
<using-namespace name="boost"/>
<using-namespace name="boost::string_algo"/>
<using-namespace name="boost::algorithm"/>
<section>
<title>Definitions</title>

160
string/doc/design.xml
View File

@ -5,7 +5,48 @@
<title>Design Topics</title>
<using-namespace name="boost"/>
<using-namespace name="boost::string_algo"/>
<using-namespace name="boost::algorithm"/>
<section id="string_algo.string">
<title>String Representation</title>
<para>
As the name suggest, this library works mainly with strings. However, in the context of this library,
a string is not restricted to any particular implementation (like <code>std::basic_string</code>),
rather it is a concept. This allows the algorithms in this library to be reused for any string type,
that satisfies the given requirements.
</para>
<para>
<emphasis role="bold">Definition:</emphasis> A string is a
<ulink url="../../libs/utility/Collection.html">collection</ulink> of characters accessible in sequential
ordered fashion. Character is any value type with "cheap" copying and assignment.
</para>
<para>
First requirement of string-type is that it must accessible using
<link linkend="string_algo.collection_traits">collection traits</link>. This facility allows to access
the elements inside the string in a uniform iterator-based fashion.
This facility actualy requires lessen requirements then collection concept. It implements
<ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection interface.
This is sufficient for our library
</para>
<para>
Second requirement defines the way in which are the characters stored in the string. Algorithms in
this library work with an assumption, that copying a character is cheaper then allocating an extra
storage to cache results. This is natural assumption for common character types. Algorithms will
work even if this requirement will not be satisfied, however at the cost of performance degradation.
<para>
</para>
In addition some algorithms have additional requirements on the string-type. Particulary, it is required,
that an algorithm can create a new string of the given type. In this case, it is required, that
the type satifies the sequence (Std &sect;23.1.1) requirements.
</para>
<para>
In the reference and also in the code, requirement on the string type is designated by the name of
template argument. <code>CollectionT</code> means that the basic collection requirements must be held.
<code>SequenceT</code> designates extended sequence requirements.
</para>
</section>
<section id="string_algo.iterator_range">
<title><code>iterator_range</code> class</title>
@ -32,27 +73,35 @@
</para>
<para>
The intention of the <code>iterator_range</code> class is to manage a range as a single value and provide
a basic interface for common operations. Its interface is similar to that of container.
a basic interface for common operations. Its interface is similar to that of collection.
In addition of <code>begin()</code>
and <code>end()</code> accessors, it has member functions for checking if the range is empty,
or to determine the size of the range. It has also a set of member typedefs that extract
type information from the encapsulated iterators. As such, the interface is compatible with
the <link linkend="string_algo.container_traits">container traits</link> requirements so
the <link linkend="string_algo.collection_traits">collecion traits</link> requirements so
it is possible to use this class as a parameter to many algorithms in this library.
</para>
<para>
<classname>iterator_range</classname> will be moved to Boost.Range library in the future
releases. Internal version will be deprecated then.
</para>
</section>
<section id="string_algo.container_traits">
<title>Container Traits</title>
<section id="string_algo.collection_traits">
<title>Collection Traits</title>
<para>
Container traits provide uniform access to different types of containers.
Collection traits provide uniform access to different types of
<ulink url="../../libs/utility/Collection.html">collections</ulink> .
This functionality allows to write generic algorithms which work with several
different kinds of containers. For this library it means, that, for instance,
different kinds of collections. For this library it means, that, for instance,
many algorithms work with <code>std::string</code> as well as with <code>char[]</code>.
This facility implements
<ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection
concept.
</para>
<para>
The following container types are supported:
The following collection types are supported:
<itemizedlist>
<listitem>
Standard containers
@ -69,78 +118,78 @@
</itemizedlist>
</para>
<para>
Container traits support a subset of container concept (Std &sect;23.1). This subset
Collection traits support a subset of container concept (Std &sect;23.1). This subset
can be described as an input container concept, e.g. a container with an immutable content.
Its definition can be found in the header <headername>boost/string_algo/container_traits.hpp</headername>.
Its definition can be found in the header <headername>boost/algorithm/string/collection_traits.hpp</headername>.
</para>
<para>
In the table C denotes a container and c is an object of C.
</para>
<table>
<title>Container Traits</title>
<title>Collection Traits</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Name</entry>
<entry>Standard container equivalent</entry>
<entry>Standard collection equivalent</entry>
<entry>Description</entry>
</row>Maeterlinck
</thead>
<tbody>
<row>
<entry><classname>container_value_type&lt;C&gt;</classname>::type</entry>
<entry><classname>value_type_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::value_type</code></entry>
<entry>Type of contained values</entry>
</row>
<row>
<entry><classname>container_difference_type&lt;C&gt;</classname>::type</entry>
<entry><classname>difference_type_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::difference_type</code></entry>
<entry>difference type of the container</entry>
<entry>difference type of the collection</entry>
</row>
<row>
<entry><classname>container_iterator&lt;C&gt;</classname>::type</entry>
<entry><classname>iterator_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::iterator</code></entry>
<entry>iterator type of the container</entry>
<entry>iterator type of the collection</entry>
</row>
<row>
<entry><classname>container_const_iterator&lt;C&gt;</classname>::type</entry>
<entry><classname>const_iterator_of&lt;C&gt;</classname>::type</entry>
<entry><code>C::const_iterator</code></entry>
<entry>const_iterator type of the container</entry>
<entry>const_iterator type of the collection</entry>
</row>
<row>
<entry><classname>container_result_iterator&lt;C&gt;</classname>::type</entry>
<entry><classname>result_iterator_of&lt;C&gt;</classname>::type</entry>
<entry></entry>
<entry>
result_iterator type of the container. This type maps to <code>C::iterator</code>
for mutable container and <code>C::const_iterator</code> for const containers.
result_iterator type of the collection. This type maps to <code>C::iterator</code>
for mutable collection and <code>C::const_iterator</code> for const collection.
</entry>
</row>
<row>
<entry><functionname>begin(c)</functionname></entry>
<entry><code>c.begin()</code></entry>
<entry>
Gets the iterator pointing to the start of the container.
Gets the iterator pointing to the start of the collection.
</entry>
</row>
<row>
<entry><functionname>end(c)</functionname></entry>
<entry><code>c.end()</code></entry>
<entry>
Gets the iterator pointing to the end of the container.
Gets the iterator pointing to the end of the collection.
</entry>
</row>
<row>
<entry><functionname>size(c)</functionname></entry>
<entry><code>c.size()</code></entry>
<entry>
Gets the size of the container.
Gets the size of the collection.
</entry>
</row>
<row>
<entry><functionname>empty(c)</functionname></entry>
<entry><code>c.empty()</code></entry>
<entry>
Checks if the container is empty.
Checks if the collection is empty.
</entry>
</row>
</tbody>
@ -148,9 +197,8 @@
</table>
<para>
The container traits are only a temporary part of this library. There is a plan for a separate submission
of a container_traits library to Boost. Once it gets accepted, String Algorithm Library will be adopted to
use it and the internal implementation will be deprecated.
The collection traits are only a temporary part of this library. They will be replaced in the future
releases by Boost.Range library. Use of the internal implementation will be deprecated then.
</para>
</section>
@ -169,7 +217,7 @@
Sequence traits allows one to specify additional properties of a sequence container (see Std.&sect;32.2).
These properties are then used by algorithms to select optimized handling for some operations.
The sequence traits are declared in the header
<headername>boost/string_algo/sequence_traits.hpp</headername>.
<headername>boost/algorithm/string/sequence_traits.hpp</headername>.
</para>
<para>
@ -186,11 +234,11 @@
</thead>
<tbody>
<row>
<entry><classname>sequence_has_native_replace&lt;C&gt;</classname>::value</entry>
<entry><classname>has_native_replace&lt;C&gt;</classname>::value</entry>
<entry>Specifies that the sequence has std::string like replace method</entry>
</row>
<row>
<entry><classname>sequence_has_stable_iterators&lt;C&gt;</classname>::value</entry>
<entry><classname>has_stable_iterators&lt;C&gt;</classname>::value</entry>
<entry>
Specifies that the sequence has stable iterators. It means,
that operations like <code>insert</code>/<code>erase</code>/<code>replace</code>
@ -198,14 +246,14 @@
</entry>
</row>
<row>
<entry><classname>sequence_has_const_time_insert&lt;C&gt;</classname>::value</entry>
<entry><classname>has_const_time_insert&lt;C&gt;</classname>::value</entry>
<entry>
Specifies that the insert method of the sequence has
constant time complexity.
</entry>
</row>
<row>
<entry><classname>sequence_has_const_time_erase&lt;C&gt;</classname>::value</entry>
<entry><classname>has_const_time_erase&lt;C&gt;</classname>::value</entry>
<entry>
Specifies that the erase method of the sequence has constant time complexity
</entry>
@ -243,7 +291,7 @@
Currently the library contains only naive implementation of find algorithms with complexity
O(n * m) where n is the size of the input sequence and m is the size of the search sequence.
There are algorithms with complexity O(n), but for smaller sequence a constant overhead is
rather big. For small m &lt;&lt; n (m magnitued smaller than n) the current implementation
rather big. For small m &lt;&lt; n (m by magnitude smaller than n) the current implementation
provides acceptable efficiency.
Even the C++ standard defines the required complexity for search algorithm as O(n * m).
It is possible that a future version of library will also contain algorithms with linear
@ -268,14 +316,44 @@
</para>
</section>
<section id="string_algo.split">
<title>Split Algorithms</title>
<title>Find Iterators &amp; Split Algorithms</title>
<para>
Split algorithms are a logical extension of <link linkend="string_algo.find">find facility</link>.
Instead of searching for one match, the whole input is searched. The result of the search is then used
to partition the input. It depends on the algorithms which parts are returned as the result of
split operations. It can be the matching parts (<functionname>find_all()</functionname>) of the parts in
between (<functionname>split()</functionname>).
Find iterators are a logical extension of <link linkend="string_algo.find">find facility</link>.
Instead of searching for one match, the whole input can be iteratively searched for multiple matches.
The result of the search is then used to partition the input. It depends on the algorithms which parts
are returned as the result. It can be the matching parts (<classname>find_iterator</classname>) of the parts in
between (<classname>split_iterator</classname>).
</para>
<para>
In addition the split algorithms like <functionname>find_all()</functionname> and <functionname>split()</functionname>
can simplify the common operations. They use a find iterator to search the whole input and copy the
matches they found into the supplied container.
</para>
</section>
<section id="string_algo.exception">
<title>Exception Safety</title>
<para>
The library provides some exceptions safety guaranties under following assumptions:
<orderedlist numeration="arabic">
<listitem>
<para>
All types that are used as a template arguments or passed as arguments to the
facilities in this library provide <emphasis>basic exception guarantie</emphasis>.
</para>
</listitem>
<listitem>
<para>
If the types mentioned in the first assumption can provide
<emphasis>strong exception guarantie</emphasis> for their const operations, some algorithm
can provide stronger guaranties.
</para>
</listitem>
</orderedlist>
</para>
<para>
Unless stated otherwise, all facilities and algorithms in this library have <emphasis>basic exception guarantie</emphasis>.
</para>
</section>
</section>

16
string/doc/environment.xml
View File

@ -8,7 +8,7 @@
<para>
The whole library is provided in headers. Regex variants of some algorithms,
however, are dependent on the <libraryname>Boost.Regex</libraryname> library. All such algorithms are
separated in <headername>boost/string_algo/regex.hpp</headername>.
separated in <headername>boost/algorithm/string_regex.hpp</headername>.
If this header is used, an application must be linked with the <libraryname>Boost.Regex</libraryname>
library.
</para>
@ -17,7 +17,7 @@
<section>
<title>Examples</title>
<para>
Examples showing the basic usage of the library can be found in the libs/string_algo/example
Examples showing the basic usage of the library can be found in the libs/algorithm/string/example
directory. There is a separate file for the each part of the library. Please follow the boost
build guidelines to build examples using the bjam. To successfully build regex examples
the <libraryname>Boost.Regex</libraryname> library is required.
@ -27,7 +27,7 @@
<section>
<title>Tests</title>
<para>
A full set of test cases for the library is located in the libs/string_algo/test directory.
A full set of test cases for the library is located in the libs/algorithm/string/test directory.
The test cases can be executed using the boost build system. For the tests of regular
expression variants of algorithms, the <libraryname>Boost.Regex</libraryname> library is required.
</para>
@ -44,12 +44,16 @@
<listitem>GCC 3.2</listitem>
<listitem>GCC 3.3.1</listitem>
</itemizedlist>
See <ulink url="http://boost.sourceforge.net/regression-logs/">Boost regression tables</ulink>
for additional info for a particular compiler.
</para>
<para>
There are known limitation on platforms not supporting partial template specialization.
Library depends on correctly implemented std::iterator_traits class. If a standard library provided
with compiler is broken, the String Algorithm Library cannot function properly. Usually it implies
that primitive pointer iterators are not working with the library functions.
Library depends on correctly implemented <code>std::iterator_traits</code> class.
If a standard library provided with compiler is broken, the String Algorithm Library
cannot function properly. Usually it implies that primitive pointer iterators are not
working with the library functions.
</para>
</section>
</section>

38
string/doc/external_concepts.html Normal file
View File

@ -0,0 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><title> Concepts and External Concepts </title><meta http-equiv="Content-Type"content="text/html; charset=iso-8859-1"></head> <body><table ><tr ><td ><img src="cboost.gif" width="100%" border="0"></td><td ><h1 >Concepts and External Concepts</h1></td></tr></table><p >Generic programming in C++ is characterized by the use of function and class templates where
the template parameter(s) must satisfy certain requirements.Often these
requirements are so important that we give them a name: we call
such a set of type requirements a <b>concept</b>. We say that a type <i>
conforms to a concept</i> or that it <i>is a model of a concept</i> if it
satisfies all of those requirements. The concept can be specified as a set
of member functions with well-defined semantics
and a set of nested typedefs with well-defined properties.</p><p >Often it much more flexible to provide free-standing functions and typedefs
which provides the exact same semantics (but a different syntax) as
specified
by the concept. This allows generic code to treat different types <i> as if
</i> they fulfilled the concept. In this case we say that the concept has
been <b> externalized </b> or that the new requirements constitutes an <b>external
concept </b>. We say that a type <i> conforms to an external concept </i>
or that it <i> is a model of an external concept </i>. A concept may exist
without a corresponding external concept and conversely.</p><p >Whenever a concept specifies a member function, the corresponding external
concept
must specify a free-standing function of the same name, same return type and
the same argument list except there is an extra first argument which must
be of the type (or a reference to that type) that is to fulfill the external
concept. If the corresonding member function has any cv-qulifiers, the
first argument must have the same cv-qualifiers. Whenever a concept
specifies a nested typedef, the corresponding external concept
specifies a <b>type-generator</b>, that is, a type with a nested typedef
named <code>type</code>. The type-generator has the name as the nested typedef with
<code>_of</code> appended.
The converse relationship of an external concept and its corresponding concept
also holds.</p><p ><b ><i >Example:</i></b></p><p >A type <code>T</code> fulfills the FooConcept if it
has the follwing public members:</p><code> void T::foo( int ) const; <br>
int T::bar(); <br>
typedef <i>implementation defined </i> foo_type;</code><p >The corresponding external concept is the ExternalFooConcept.</p><p >A type <code>T</code> fullfills the ExternalFooConcept if these
free-standing functions and type-generators exists:</p><code>void foo( const T&, int ); <br>
int bar( T& ); <br>
foo_type_of< T >::type;</code> <br> <br><hr size="1" ><h3 >Literature</h3><ul ><li > <a href="http://www.boost.org/more/generic_programming.html#type_generator" target="_self" >Type Generators</a> </li><li > <a href="http://www.boost.org/more/generic_programming.html#concept" target="_self" >Concepts</a> </li><li > <a href="http://www.sgi.com/tech/stl/stl_introduction.html" target="_self" >Concepts and SGI STL</a> </li></ul><hr size="1" ><p >&copy; Thorsten Ottosen 2003-2004 (nesotto_AT_cs.auc.dk).
Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears
in all copies. This software is provided "as is" without express or implied warranty, and with no
claim as to its suitability for any purpose.</p><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br></body></html>
<!-- Copyright Dezide Aps 2003-2004 -->

28
string/doc/intro.xml
View File

@ -18,23 +18,25 @@
algorithms are using container specific features when it means a performance
gain.
</para>
<para>
<emphasis role="bold">
Important note: In this documentation we use term <emphasis>string</emphasis> to
designate a sequence of <emphasis>characters</emphasis> stored in an arbitrary container.
A <emphasis>string</emphasis> is not restricted to <code>std::basic_string</code> and
<emphasis>character</emphasis> does not have to be <code>char</code> or <code>wchar_t</code>,
although these are most common candidates.
</emphasis>
Consult <link linkend="string_algo.design">design chapter</link> to see precise specification of
supported string types.
</para>
<para>
The library has layered structure to simplify the usage without sacrificing the
generalization.
The easy-to-use interface, defined in the namespace <code>boost</code>, represents the first layer.
Algorithms and classes defined here do not offer a lot of customization opportunities
rather they are provided in more different variants, so a user can chose the
one that suits her needs.
The second layer, defined in the namespace <code>boost::string_algo</code>, on the
other hand, is generic. Basically it contains the same set of algorithms as the first layer,
but the interface is more flexible and allows more customization, but it is harder to use.
The first layer is implemented as set of wrappers around the second layer.
The library interface functions and classes are defined in the namespace <code>boost::algorithm</code>, and
they are lift into namespace <code>boost</code> via using declaration.
</para>
<para>
The documentation is divided into several sections. For a quick start read the
<link linkend="string_algo.usage">Usage</link> section.
<link linkend="string_algo.usage">Usage</link> section followed by
<link linkend="string_algo.quickref">Quick Reference</link>.
<link linkend="string_algo.design">The Design Topics</link>,
<link linkend="string_algo.concept">Concepts</link> and <link linkend="string_algo.rationale">Rationale</link>
provide some explanation about the library design and structure an explain how it should be used.

686
string/doc/quickref.xml Normal file
View File

@ -0,0 +1,686 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section id="string_algo.quickref" last-revision="$Date$">
<title>Quick Reference</title>
<using-namespace name="boost"/>
<using-namespace name="boost::algorithm"/>
<section>
<title>Algorithms</title>
<table>
<title>Case Conversion</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>to_upper</code></entry>
<entry>Convert a string to upper case</entry>
<entry>
<functionname>to_upper_copy()()</functionname>
<sbr/>
<functionname>to_upper()()</functionname>
</entry>
</row>
<row>
<entry><code>to_lower</code></entry>
<entry>Convert a string to lower case</entry>
<entry>
<functionname>to_lower_copy()</functionname>
<sbr/>
<functionname>to_lower()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Trimming</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>trim_left</code></entry>
<entry>Remove leading spaces from a string</entry>
<entry>
<functionname>trim_left_copy_if()</functionname>
<sbr/>
<functionname>trim_left_if()</functionname>
<sbr/>
<functionname>trim_left_copy()</functionname>
<sbr/>
<functionname>trim_left()</functionname>
</entry>
</row>
<row>
<entry><code>trim_right</code></entry>
<entry>Remove trailing spaces from a string</entry>
<entry>
<functionname>trim_right_copy_if()</functionname>
<sbr/>
<functionname>trim_right_if()</functionname>
<sbr/>
<functionname>trim_right_copy()</functionname>
<sbr/>
<functionname>trim_right()</functionname>
</entry>
</row>
<row>
<entry><code>trim</code></entry>
<entry>Remove leading and trailing spaces from a string</entry>
<entry>
<functionname>trim_copy_if()</functionname>
<sbr/>
<functionname>trim_if()</functionname>
<sbr/>
<functionname>trim_copy()</functionname>
<sbr/>
<functionname>trim()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Predicates</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>starts_with</code></entry>
<entry>Check if a string is a prefix of the other one</entry>
<entry>
<functionname>starts_with()</functionname>
<sbr/>
<functionname>istarts_with()</functionname>
</entry>
</row>
<row>
<entry><code>ends_with</code></entry>
<entry>Check if a string is a suffix of the other one</entry>
<entry>
<functionname>ends_with()</functionname>
<sbr/>
<functionname>iends_with()</functionname>
</entry>
</row>
<row>
<entry><code>contains</code></entry>
<entry>Check if a string is contained of the other one</entry>
<entry>
<functionname>contains()</functionname>
<sbr/>
<functionname>icontains()</functionname>
</entry>
</row>
<row>
<entry><code>equals</code></entry>
<entry>Check if a two strings are equal</entry>
<entry>
<functionname>equals()</functionname>
<sbr/>
<functionname>iequals()</functionname>
</entry>
</row>
<row>
<entry><code>all</code></entry>
<entry>Check if all elements of a string satisfy the given predicate</entry>
<entry>
<functionname>all()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Find algorithms</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry>find_first</entry>
<entry>Find the first occurrence of a string in the input</entry>
<entry>
<functionname>find_first()</functionname>
<sbr/>
<functionname>ifind_first()</functionname>
</entry>
</row>
<row>
<entry>find_last</entry>
<entry>Find the last occurrence of a string in the input</entry>
<entry>
<functionname>find_last()</functionname>
<sbr/>
<functionname>ifind_last()</functionname>
</entry>
</row>
<row>
<entry>find_nth</entry>
<entry>Find the nth (zero-indexed) occurrence of a string in the input</entry>
<entry>
<functionname>find_nth()</functionname>
<sbr/>
<functionname>ifind_nth()</functionname>
</entry>
</row>
<row>
<entry>find_head</entry>
<entry>Retrieve the head of a string</entry>
<entry>
<functionname>find_head()</functionname>
</entry>
</row>
<row>
<entry>find_tail</entry>
<entry>Retrieve the fail of a string</entry>
<entry>
<functionname>find_tail()</functionname>
</entry>
</row>
<row>
<entry>find_token</entry>
<entry>Find first matching token in the string</entry>
<entry>
<functionname>find_token()</functionname>
</entry>
</row>
<row>
<entry>find_regex</entry>
<entry>Use the regular expression to search the string</entry>
<entry>
<functionname>find_regex()</functionname>
</entry>
</row>
<row>
<entry>find</entry>
<entry>Generic find algorithm</entry>
<entry>
<functionname>find()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Erase/Replace</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry>replace/erase_first</entry>
<entry>Replace/Erase the first occurrence of a string in the input</entry>
<entry>
<functionname>replace_first()</functionname>
<sbr/>
<functionname>replace_first_copy()</functionname>
<sbr/>
<functionname>ireplace_first()</functionname>
<sbr/>
<functionname>ireplace_first_copy()</functionname>
<sbr/>
<functionname>erase_first()</functionname>
<sbr/>
<functionname>erase_first_copy()</functionname>
<sbr/>
<functionname>ierase_first()</functionname>
<sbr/>
<functionname>ierase_first_copy()</functionname>
</entry>
</row>
<row>
<entry>replace/erase_last</entry>
<entry>Replace/Erase the last occurrence of a string in the input</entry>
<entry>
<functionname>replace_last()</functionname>
<sbr/>
<functionname>replace_last_copy()</functionname>
<sbr/>
<functionname>ireplace_last()</functionname>
<sbr/>
<functionname>ireplace_last_copy()</functionname>
<sbr/>
<functionname>erase_last()</functionname>
<sbr/>
<functionname>erase_last_copy()</functionname>
<sbr/>
<functionname>ierase_last()</functionname>
<sbr/>
<functionname>ierase_last_copy()</functionname>
</entry>
</row>
<row>
<entry>replace/erase_nth</entry>
<entry>Replace/Erase the nth (zero-indexed) occurrence of a string in the input</entry>
<entry>
<functionname>replace_nth()</functionname>
<sbr/>
<functionname>replace_nth_copy()</functionname>
<sbr/>
<functionname>ireplace_nth()</functionname>
<sbr/>
<functionname>ireplace_nth_copy()</functionname>
<sbr/>
<functionname>erase_nth()</functionname>
<sbr/>
<functionname>erase_nth_copy()</functionname>
<sbr/>
<functionname>ierase_nth()</functionname>
<sbr/>
<functionname>ierase_nth_copy()</functionname>
</entry>
</row>
<row>
<entry>replace/erase_all</entry>
<entry>Replace/Erase the all occurrences of a string in the input</entry>
<entry>
<functionname>replace_all()</functionname>
<sbr/>
<functionname>replace_all_copy()</functionname>
<sbr/>
<functionname>ireplace_all()</functionname>
<sbr/>
<functionname>ireplace_all_copy()</functionname>
<sbr/>
<functionname>erase_all()</functionname>
<sbr/>
<functionname>erase_all_copy()</functionname>
<sbr/>
<functionname>ierase_all()</functionname>
<sbr/>
<functionname>ierase_all_copy()</functionname>
</entry>
</row>
<row>
<entry>replace/erase_head</entry>
<entry>Replace/Erase the head of a input</entry>
<entry>
<functionname>replace_head()</functionname>
<sbr/>
<functionname>replace_head_copy()</functionname>
<sbr/>
<functionname>erase_head()</functionname>
<sbr/>
<functionname>erase_head_copy()</functionname>
<sbr/>
</entry>
</row>
<row>
<entry>replace/erase_tail</entry>
<entry>Replace/Erase the tail of a input</entry>
<entry>
<functionname>replace_tail()</functionname>
<sbr/>
<functionname>replace_tail_copy()</functionname>
<sbr/>
<functionname>erase_tail()</functionname>
<sbr/>
<functionname>erase_tail_copy()</functionname>
<sbr/>
</entry>
</row>
<row>
<entry>replace/erase_regex</entry>
<entry>Replace/Erase a substring matching the the given regular expression</entry>
<entry>
<functionname>replace_regex()</functionname>
<sbr/>
<functionname>replace_regex_copy()</functionname>
<sbr/>
<functionname>erase_regex()</functionname>
<sbr/>
<functionname>erase_regex_copy()</functionname>
<sbr/>
</entry>
</row>
<row>
<entry>replace/erase_regex_all</entry>
<entry>Replace/Erase all substrings matching the the given regular expression</entry>
<entry>
<functionname>replace_all_regex()</functionname>
<sbr/>
<functionname>replace_all_regex_copy()</functionname>
<sbr/>
<functionname>erase_all_regex()</functionname>
<sbr/>
<functionname>erase_all_regex_copy()</functionname>
<sbr/>
</entry>
</row>
<row>
<entry>find_format</entry>
<entry>Generic replace algorithm</entry>
<entry>
<functionname>find_format()</functionname>
<sbr/>
<functionname>find_format_copy()</functionname>
<sbr/>
<functionname>find_format_all()</functionname>
<sbr/>
<functionname>find_format_all_copy()()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Split</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Algorithm name</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry>find_all</entry>
<entry>Find/Extract all matching substrings in hte input</entry>
<entry>
<functionname>find_all()</functionname>
<sbr/>
<functionname>ifind_all()</functionname>
<sbr/>
<functionname>find_all_regex()</functionname>
</entry>
</row>
<row>
<entry>split</entry>
<entry>Split input into parts</entry>
<entry>
<functionname>split()</functionname>
<sbr/>
<functionname>split_regex()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Finders and Formatters</title>
<table>
<title>Finders</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Finder</entry>
<entry>Description</entry>
<entry>Generators</entry>
</row>
</thead>
<tbody>
<row>
<entry>first_finder</entry>
<entry>Search for the first match of the string in an input</entry>
<entry>
<functionname>first_finder()</functionname>
</entry>
</row>
<row>
<entry>last_finder</entry>
<entry>Search for the last match of the string in an input</entry>
<entry>
<functionname>last_finder()</functionname>
</entry>
</row>
<row>
<entry>nth_finder</entry>
<entry>Search for the nth (zero-indexed) match of the string in an input</entry>
<entry>
<functionname>nth_finder()</functionname>
</entry>
</row>
<row>
<entry>head_finder</entry>
<entry>Retrieve the head of an input</entry>
<entry>
<functionname>head_finder()</functionname>
</entry>
</row>
<row>
<entry>tail_finder</entry>
<entry>Retrieve the tail of an input</entry>
<entry>
<functionname>tail_finder()</functionname>
</entry>
</row>
<row>
<entry>token_finder</entry>
<entry>Search for a matching token in an input</entry>
<entry>
<functionname>token_finder()</functionname>
</entry>
</row>
<row>
<entry>range_finder</entry>
<entry>Do no search, always returns the given range</entry>
<entry>
<functionname>range_finder()</functionname>
</entry>
</row>
<row>
<entry>regex_finder</entry>
<entry>Search for a substring matching the given regex</entry>
<entry>
<functionname>regex_finder()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Formatters</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Formatter</entry>
<entry>Description</entry>
<entry>Generators</entry>
</row>
</thead>
<tbody>
<row>
<entry>const_formatter</entry>
<entry>Constant formatter. Always return the specified string</entry>
<entry>
<functionname>const_formatter()</functionname>
</entry>
</row>
<row>
<entry>identity_formatter</entry>
<entry>Identity formatter. Return unmodified input input</entry>
<entry>
<functionname>identity_formatter()</functionname>
</entry>
</row>
<row>
<entry>empty_formatter</entry>
<entry>Null formatter. Always return an empty string</entry>
<entry>
<functionname>empty_formatter()</functionname>
</entry>
</row>
<row>
<entry>regex_formatter</entry>
<entry>Regex formatter. Format regex match using the specification in the format string</entry>
<entry>
<functionname>regex_formatter()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Iterators</title>
<table>
<title>Find Iterators</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Iterator name</entry>
<entry>Description</entry>
<entry>Iterator class</entry>
</row>
</thead>
<tbody>
<row>
<entry>find_iterator</entry>
<entry>Iterates through matching substrings in the input</entry>
<entry>
<classname>find_iterator</classname>
</entry>
</row>
<row>
<entry>split_iterator</entry>
<entry>Iterates through gasp between matching substrings in the input</entry>
<entry>
<classname>split_iterator</classname>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Classification</title>
<table>
<title>Predicates</title>
<tgroup cols="3" align="left">
<thead>
<row>
<entry>Predicate name</entry>
<entry>Description</entry>
<entry>Generator</entry>
</row>
</thead>
<tbody>
<row>
<entry>is_classified</entry>
<entry>Generic <code>ctype</code> mask based classification</entry>
<entry>
<functionname>is_classified()</functionname>
</entry>
</row>
<row>
<entry>is_space</entry>
<entry>Recognize spaces</entry>
<entry>
<functionname>is_space()</functionname>
</entry>
</row>
<row>
<entry>is_alnum</entry>
<entry>Recognize Classify alphanumeric characters</entry>
<entry>
<functionname>is_alnum()</functionname>
</entry>
</row>
<row>
<entry>is_alpha</entry>
<entry>Recognize letters</entry>
<entry>
<functionname>is_alpha()</functionname>
</entry>
</row>
<row>
<entry>is_cntrl</entry>
<entry>Recognize control characters</entry>
<entry>
<functionname>is_cntrl()</functionname>
</entry>
</row>
<row>
<entry>is_digit</entry>
<entry>Recognize decimal digits</entry>
<entry>
<functionname>is_digit()</functionname>
</entry>
</row>
<row>
<entry>is_graph</entry>
<entry>Recognize graphical characters</entry>
<entry>
<functionname>is_graph()</functionname>
</entry>
</row>
<row>
<entry>is_lower</entry>
<entry>Recognize lower case characters</entry>
<entry>
<functionname>is_lower()</functionname>
</entry>
</row>
<row>
<entry>is_print</entry>
<entry>Recognize printable characters</entry>
<entry>
<functionname>is_print()</functionname>
</entry>
</row>
<row>
<entry>is_punct</entry>
<entry>Recognize punctuation characters</entry>
<entry>
<functionname>is_punct()</functionname>
</entry>
</row>
<row>
<entry>is_upper</entry>
<entry>Recognize uppercase characters</entry>
<entry>
<functionname>is_upper()</functionname>
</entry>
</row>
<row>
<entry>is_xdigit</entry>
<entry>Recognize hexadecimal digits</entry>
<entry>
<functionname>is_xdigit()</functionname>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>

34
string/doc/rationale.xml
View File

@ -5,39 +5,9 @@
<title>Rationale</title>
<using-namespace name="boost"/>
<using-namespace name="boost::string_algo"/>
<using-namespace name="boost::algorithm"/>
<section id="string_algo.structure">
<title>Library structure</title>
<para>
When designing a library it is always a problem to find a balance between generalization
and usability. A generic utility can have a wider range of usage with more options for extensibility,
but it can also bring unwanted complexity for everyday usage.
</para>
<para>
Imagine a library for drawing geometric objects. It can contain one generic function <code>draw()</code>
with many parameters specifying what to draw, like size, number of edges, shape etc.
This would allow you to draw almost anything, but usually a user only needs to draw
only a triangle or a square and she will have to specify this simple request in a
very complicated way.For this purpose two functions, <code>draw_triangle()</code> and
<code>draw_square()</code>, would suit much better then a generic <code>draw()</code> function.
</para>
<para>
The String Algorithm Library solves this problem by dividing the interface into two layers.
The first layer (defined in the namespace boost) contains ready to use algorithms specialized
for common tasks. They are provided in multiple variants to better suit specific needs.
The second layer (defined in the namespace <code>boost::string_algo</code>), provides generic interfaces with
more options for extending and tunning.
<para>
</para>
For instance, a <functionname>boost::trim()</functionname> algorithm trims spaces from
an input string. When there is a need to trim something else, there is
<functionname>boost::string_algo::trim()</functionname> which interface allows one to specify a
predicate which selects the characters to be removed.
</para>
</section>
<section it="string_algo.locale">
<section it="string_algo.locale">
<title>Locales</title>
<para>

4
string/doc/string_algo.xml
View File

@ -12,6 +12,7 @@
<copyright>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<holder>Pavol Droba</holder>
</copyright>
@ -32,9 +33,10 @@
<title>Boost String Algorithms Library</title>
<xi:include href="intro.xml"/>
<xi:include href="usage.xml"/>
<xi:include href="quickref.xml"/>
<xi:include href="design.xml"/>
<xi:include href="concept.xml"/>
<xi:include href="reference.boostbook"/>
<xi:include href="autodoc.boostbook"/>
<xi:include href="rationale.xml"/>
<xi:include href="environment.xml"/>
<xi:include href="credits.xml"/>

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>