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

Fixing grammar and typos

Browse Source 
[SVN r23605]
This commit is contained in:
Pavol Droba
2004-07-15 21:47:22 +00:00
parent ddd9baba60
commit d97ff92ae4
9 changed files with 135 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
string/doc/Jamfile.v2
View File

@ -3,15 +3,13 @@
# Copyright Pavol Droba 2002-2003. Use, modification and # Copyright Pavol Droba 2002-2003. Use, modification and
# distribution is subject to the Boost Software License, Version # distribution is subject to the Boost Software License, Version
# 1.0. (See accompanying file LICENSE_1_0.txt or copy at # 1.0. (See accompanying file LICENSE_1_0.txt or copy at
# htt../..//www.boost.org/LICENSE_1_0.txt) # http://www.boost.org/LICENSE_1_0.txt)
# #
# See htt../..//www.boost.org for updates, documentation, and revision history. # See http://www.boost.org for updates, documentation, and revision history.
import toolset ; import toolset ;
toolset.using doxygen ; toolset.using doxygen ;
import path ;
boostbook string_algo : string_algo.xml ; boostbook string_algo : string_algo.xml ;
doxygen autodoc doxygen autodoc

10
string/doc/concept.xml
View File

@ -75,9 +75,9 @@
</table> </table>
<para> <para>
Various algorithms need to perform a searching in a container and a Finder is a generalization of such Various algorithms need to perform a search in a container and a Finder is a generalization of such
search operations that allows algorithms to abstract from searching. For instance, generic replace search operations that allows algorithms to abstract from searching. For instance, generic replace
algorithms can replace any part of the input, and the finder is used to select the desired one. algorithms can replace any part of the input, and the Finder is used to select the desired one.
</para> </para>
<para> <para>
Note, that it is only required that the finder works with a particular iterator type. However, Note, that it is only required that the finder works with a particular iterator type. However,
@ -106,7 +106,7 @@ struct simple_finder
</programlisting> </programlisting>
</listitem> </listitem>
<listitem> <listitem>
Function Finder. Finder can be any function object. That means, an ordinary function with the Function Finder. Finder can be any function object. That is, any ordinary function with the
required signature can be used as well. However, such a function can be used only for required signature can be used as well. However, such a function can be used only for
a specific iterator type. a specific iterator type.
@ -165,8 +165,8 @@ boost::iterator_range&lt;std::string&gt; simple_finder(
<para> <para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
Formatter implemented as a class. This Formatter does not perform any formating and Formatter implemented as a class. This Formatter does not perform any formating and
returns repackaged match. <code>operator()</code> returns the match, repackaged. <code>operator()</code>
is templated, so that the Formatter can be used on any Finder type. is templated, so that the Formatter can be used on any Finder type.
<programlisting> <programlisting>

6
string/doc/credits.xml
View File

@ -6,8 +6,10 @@
<section id="string_algo.ack"> <section id="string_algo.ack">
<title>Acknowledgments</title> <title>Acknowledgments</title>
<para> <para>
Thanks for everybody who gave suggestions and comments. Especially to Thorsten Ottosen, Jeff Garland The author would like to thank everybody who gave suggestions and comments. Especially valuable
and the other boost members who participated. were the contributions of Thorsten Ottosen, Jeff Garland and the other boost members who participated
in the review process, namely David Abrahams, Daniel Frey, Beman Dawes, John Maddock, David B.Held, Pavel Vozenilek
and many other.
</para> </para>
</section> </section>
</section> </section>

118
string/doc/design.xml
View File

@ -25,24 +25,24 @@
First requirement of string-type is that it must accessible using 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 <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. the elements inside the string in a uniform iterator-based fashion.
This facility actually requires lessen requirements then collection concept. It implements This requirement is actually less stringent than that of collection concept. It implements
<ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection interface. an <ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection interface.
This is sufficient for our library This is sufficient for our library
</para> </para>
<para> <para>
Second requirement defines the way in which are the characters stored in the string. Algorithms in Second requirement defines the way in which the characters are stored in the string. Algorithms in
this library work with an assumption, that copying a character is cheaper then allocating an extra this library work with an assumption that copying a character is cheaper then allocating extra
storage to cache results. This is natural assumption for common character types. Algorithms will storage to cache results. This is a natural assumption for common character types. Algorithms will
work even if this requirement will not be satisfied, however at the cost of performance degradation. work even if this requirement is not satisfied, however at the cost of performance degradation.
<para> <para>
</para> </para>
In addition some algorithms have additional requirements on the string-type. Particularly, it is required, In addition some algorithms have additional requirements on the string-type. Particularly, it is required
that an algorithm can create a new string of the given type. In this case, it is required, that that an algorithm can create a new string of the given type. In this case, it is required that
the type satisfies the sequence (Std &sect;23.1.1) requirements. the type satisfies the sequence (Std &sect;23.1.1) requirements.
</para> </para>
<para> <para>
In the reference and also in the code, requirement on the string type is designated by the name of 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. template argument. <code>CollectionT</code> means that the basic collection requirements must hold.
<code>SequenceT</code> designates extended sequence requirements. <code>SequenceT</code> designates extended sequence requirements.
</para> </para>
</section> </section>
@ -61,29 +61,29 @@
</para> </para>
<para> <para>
It is possible to encapsulate a range in <code>std::pair&lt;&gt;</code>, but It is possible to encapsulate a range in <code>std::pair&lt;&gt;</code>, but
the <code>std::pair&lt;&gt;</code> is a too generic encapsulation, so it is not best match for a range. <code>std::pair&lt;&gt;</code> is an overly generic encapsulation, so it is not best match for a range.
For instance, it does not enforce that begin and end iterators are of the same type. For instance, it does not enforce that begin and end iterators be of the same type.
</para> </para>
<para> <para>
Naturally the range concept is heavily used also in this library. During the development of Naturally the range concept is heavily used also in this library. During the development of
the library, it was discovered, that there is a need for a reasonable encapsulation for it. the library, it was discovered, that there is a need for a reasonable encapsulation for it, since
A core part of the library deals with substring searching algorithms. Any such an algorithm, core part of the library deals with substring searching algorithms and any such algorithm
returns a range delimiting the result of the search. <code>std::pair&lt;&gt;</code> was considered as returns a range delimiting the result of the search. <code>std::pair&lt;&gt;</code> was deemed as
unsuitable. Therefore the <code>iterator_range</code> was defined. unsuitable. Therefore the <code>iterator_range</code> was defined.
</para> </para>
<para> <para>
The intention of the <code>iterator_range</code> class is to manage a range as a single value and provide 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 collection. a basic interface for common operations. Its interface is similar to that of a collection.
In addition of <code>begin()</code> In addition to <code>begin()</code>
and <code>end()</code> accessors, it has member functions for checking if the range is empty, and <code>end()</code> accessors, it has member functions for checking whether the range is empty,
or to determine the size of the range. It has also a set of member typedefs that extract or to determine the size of the range. It also has a set of member typedefs that extract
type information from the encapsulated iterators. As such, the interface is compatible with type information from the encapsulated iterators. As such, the interface is compatible with
the <link linkend="string_algo.collection_traits">collection traits</link> requirements so the <link linkend="string_algo.collection_traits">collection traits</link> requirements so
it is possible to use this class as a parameter to many algorithms in this library. it is possible to use this class as a parameter to many algorithms in this library.
</para> </para>
<para> <para>
<classname>iterator_range</classname> will be moved to Boost.Range library in the future <classname>iterator_range</classname> will be moved to Boost.Range library in the future
releases. Internal version will be deprecated then. releases. The internal version will be deprecated then.
</para> </para>
</section> </section>
@ -96,7 +96,7 @@
This functionality allows to write generic algorithms which work with several This functionality allows to write generic algorithms which work with several
different kinds of collections. 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>. many algorithms work with <code>std::string</code> as well as with <code>char[]</code>.
This facility implements This facility implements the
<ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection <ulink url="../../libs/algorithm/string/doc/external_concepts.html">external</ulink> collection
concept. concept.
</para> </para>
@ -118,8 +118,8 @@
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
Collection traits support a subset of container concept (Std &sect;23.1). This subset Collection traits support a subset of the container concept (Std &sect;23.1). This subset
can be described as an input container concept, e.g. a container with an immutable content. can be described as an input container concept, e.g. a container with immutable content.
Its definition can be found in the header <headername>boost/algorithm/string/collection_traits.hpp</headername>. Its definition can be found in the header <headername>boost/algorithm/string/collection_traits.hpp</headername>.
</para> </para>
<para> <para>
@ -206,15 +206,15 @@
<title>Sequence Traits</title> <title>Sequence Traits</title>
<para> <para>
Major difference between <code>std::list</code> and <code>std::vector</code> is not in the interfaces The major difference between <code>std::list</code> and <code>std::vector</code> is not in the interfaces
they provide, rather in the inner details of the class and the way how it performs they provide, but rather in the inner details of the class and the way how it performs
various operation. The problem is that it is not possible to infer this difference from the various operations. The problem is that it is not possible to infer this difference from the
definitions of classes without some special mechanism. definitions of classes without some special mechanism.
However some algorithms can run significantly faster with the knowledge of the properties However, some algorithms can run significantly faster with the knowledge of the properties
of a particular container. of a particular container.
</para> </para>
<para> <para>
Sequence traits allows one to specify additional properties of a sequence container (see Std.&sect;32.2). Sequence traits allow 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. These properties are then used by algorithms to select optimized handling for some operations.
The sequence traits are declared in the header The sequence traits are declared in the header
<headername>boost/algorithm/string/sequence_traits.hpp</headername>. <headername>boost/algorithm/string/sequence_traits.hpp</headername>.
@ -311,7 +311,7 @@
</para> </para>
<para> <para>
As usual, the implementation of the lower layer is designed to work with a generic sequence while As usual, the implementation of the lower layer is designed to work with a generic sequence while
taking an advantage of specific features if possible taking advantage of specific features if possible
(by using <link linkend="string_algo.sequence_traits">Sequence traits</link>) (by using <link linkend="string_algo.sequence_traits">Sequence traits</link>)
</para> </para>
</section> </section>
@ -319,10 +319,10 @@
<title>Find Iterators &amp; Split Algorithms</title> <title>Find Iterators &amp; Split Algorithms</title>
<para> <para>
Find iterators are a logical extension of <link linkend="string_algo.find">find facility</link>. Find iterators are a logical extension of the <link linkend="string_algo.find">find facility</link>.
Instead of searching for one match, the whole input can be iteratively searched for multiple matches. 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 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 are returned as the result. They can be the matching parts (<classname>find_iterator</classname>) of the parts in
between (<classname>split_iterator</classname>). between (<classname>split_iterator</classname>).
</para> </para>
<para> <para>
@ -334,26 +334,40 @@
<section id="string_algo.exception"> <section id="string_algo.exception">
<title>Exception Safety</title> <title>Exception Safety</title>
<para> <para>
The library provides some exceptions safety guaranties under following assumptions: The library requires that all operations on types used as template
<orderedlist numeration="arabic"> or function arguments provide the <emphasis>basic exception-safety guarantee</emphasis>.
<listitem> In turn, all functions and algorithms in this library, except where stated
<para> otherwise, will provide the <emphasis>basic exception-safety guarantee</emphasis>.
All types that are used as a template arguments or passed as arguments to the In other words:
facilities in this library provide <emphasis>basic exception guarantee</emphasis>. The library maintains its invariants and does not leak resources in
</para> the face of exceptions. Some library operations give stronger
</listitem> guarantees, which are documented on an individual basis.
<listitem> </para>
<para>
If the types mentioned in the first assumption can provide <para>
<emphasis>strong exception guarantee</emphasis> for their const operations, some algorithm Some functions can provide the <emphasis>strong exception-safety guarantee</emphasis>.
can provide stronger guaranties. That means that following statements are true:
</para> <itemizedlist>
</listitem> <listitem>
</orderedlist> If an exception is thrown, there are no effects other than those
</para> of the function
<para> </listitem>
Unless stated otherwise, all facilities and algorithms in this library have <emphasis>basic exception guarantee</emphasis>. <listitem>
</para> If an exception is thrown other than by the function, there are no effects
</section> </listitem>
</itemizedlist>
This guarantee can be provided under the condition that the operations
on the types used for arguments for these functions either
provide the strong exception guarantee or do not alter the global state .
</para>
<para>
In the reference, under the term <emphasis>strong exception-safety guarantee</emphasis>, we mean the
guarantee as defined above.
</para>
<para>
For more information about the exception safety topics, follow this
<ulink url="../../more/generic_exception_safety.html">link</ulink>
</para>
</section>
</section> </section>

2
string/doc/environment.xml
View File

@ -9,7 +9,7 @@
The whole library is provided in headers. Regex variants of some algorithms, 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 however, are dependent on the <libraryname>Boost.Regex</libraryname> library. All such algorithms are
separated in <headername>boost/algorithm/string_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> If this header is used, the application must be linked with the <libraryname>Boost.Regex</libraryname>
library. library.
</para> </para>
</section> </section>

8
string/doc/intro.xml
View File

@ -13,7 +13,7 @@
</para> </para>
<para> <para>
The implementation is not restricted to work with a particular container The implementation is not restricted to work with a particular container
(like a <code>std::basic_string</code>), rather it is as generic as (like <code>std::basic_string</code>), rather it is as generic as
possible. This generalization is not compromising the performance since possible. This generalization is not compromising the performance since
algorithms are using container specific features when it means a performance algorithms are using container specific features when it means a performance
gain. gain.
@ -26,12 +26,12 @@
<emphasis>character</emphasis> does not have to be <code>char</code> or <code>wchar_t</code>, <emphasis>character</emphasis> does not have to be <code>char</code> or <code>wchar_t</code>,
although these are most common candidates. although these are most common candidates.
</emphasis> </emphasis>
Consult <link linkend="string_algo.design">design chapter</link> to see precise specification of Consult the <link linkend="string_algo.design">design chapter</link> to see precise specification of
supported string types. supported string types.
</para> </para>
<para> <para>
The library interface functions and classes are defined in the namespace <code>boost::algorithm</code>, and The library interface functions and classes are defined in namespace <code>boost::algorithm</code>, and
they are lift into namespace <code>boost</code> via using declaration. they are lifted into namespace <code>boost</code> via using declaration.
</para> </para>
<para> <para>
The documentation is divided into several sections. For a quick start read the The documentation is divided into several sections. For a quick start read the

22
string/doc/quickref.xml
View File

@ -25,9 +25,9 @@
<entry><code>to_upper</code></entry> <entry><code>to_upper</code></entry>
<entry>Convert a string to upper case</entry> <entry>Convert a string to upper case</entry>
<entry> <entry>
<functionname>to_upper_copy()()</functionname> <functionname>to_upper_copy()</functionname>
<sbr/> <sbr/>
<functionname>to_upper()()</functionname> <functionname>to_upper()</functionname>
</entry> </entry>
</row> </row>
<row> <row>
@ -136,7 +136,7 @@
</row> </row>
<row> <row>
<entry><code>equals</code></entry> <entry><code>equals</code></entry>
<entry>Check if a two strings are equal</entry> <entry>Check if two strings are equal</entry>
<entry> <entry>
<functionname>equals()</functionname> <functionname>equals()</functionname>
<sbr/> <sbr/>
@ -200,7 +200,7 @@
</row> </row>
<row> <row>
<entry>find_tail</entry> <entry>find_tail</entry>
<entry>Retrieve the fail of a string</entry> <entry>Retrieve the tail of a string</entry>
<entry> <entry>
<functionname>find_tail()</functionname> <functionname>find_tail()</functionname>
</entry> </entry>
@ -326,7 +326,7 @@
</row> </row>
<row> <row>
<entry>replace/erase_head</entry> <entry>replace/erase_head</entry>
<entry>Replace/Erase the head of a input</entry> <entry>Replace/Erase the head of the input</entry>
<entry> <entry>
<functionname>replace_head()</functionname> <functionname>replace_head()</functionname>
<sbr/> <sbr/>
@ -340,7 +340,7 @@
</row> </row>
<row> <row>
<entry>replace/erase_tail</entry> <entry>replace/erase_tail</entry>
<entry>Replace/Erase the tail of a input</entry> <entry>Replace/Erase the tail of the input</entry>
<entry> <entry>
<functionname>replace_tail()</functionname> <functionname>replace_tail()</functionname>
<sbr/> <sbr/>
@ -354,7 +354,7 @@
</row> </row>
<row> <row>
<entry>replace/erase_regex</entry> <entry>replace/erase_regex</entry>
<entry>Replace/Erase a substring matching the the given regular expression</entry> <entry>Replace/Erase a substring matching the given regular expression</entry>
<entry> <entry>
<functionname>replace_regex()</functionname> <functionname>replace_regex()</functionname>
<sbr/> <sbr/>
@ -368,7 +368,7 @@
</row> </row>
<row> <row>
<entry>replace/erase_regex_all</entry> <entry>replace/erase_regex_all</entry>
<entry>Replace/Erase all substrings matching the the given regular expression</entry> <entry>Replace/Erase all substrings matching the given regular expression</entry>
<entry> <entry>
<functionname>replace_all_regex()</functionname> <functionname>replace_all_regex()</functionname>
<sbr/> <sbr/>
@ -571,7 +571,7 @@
</row> </row>
<row> <row>
<entry>split_iterator</entry> <entry>split_iterator</entry>
<entry>Iterates through gasp between matching substrings in the input</entry> <entry>Iterates through gaps between matching substrings in the input</entry>
<entry> <entry>
<classname>split_iterator</classname> <classname>split_iterator</classname>
</entry> </entry>
@ -611,7 +611,7 @@
</row> </row>
<row> <row>
<entry>is_alnum</entry> <entry>is_alnum</entry>
<entry>Recognize Classify alphanumeric characters</entry> <entry>Recognize alphanumeric characters</entry>
<entry> <entry>
<functionname>is_alnum()</functionname> <functionname>is_alnum()</functionname>
</entry> </entry>
@ -650,7 +650,7 @@
<entry> <entry>
<functionname>is_lower()</functionname> <functionname>is_lower()</functionname>
</entry> </entry>
</row> </row>
<row> <row>
<entry>is_print</entry> <entry>is_print</entry>
<entry>Recognize printable characters</entry> <entry>Recognize printable characters</entry>

12
string/doc/rationale.xml
View File

@ -19,15 +19,15 @@
C++ allows to work with multiple different instances of locales at once. If an algorithm C++ allows to work with multiple different instances of locales at once. If an algorithm
manipulates some data in a way that requires the usage of locales, there must be a way manipulates some data in a way that requires the usage of locales, there must be a way
to specify them. However, one instance of locales is sufficient for most of the applications, to specify them. However, one instance of locales is sufficient for most of the applications,
and for a user it could be very tedious to specify which locales to use on every place and for a user it could be very tedious to specify which locales to use at every place
where it is needed. where it is needed.
</para> </para>
<para> <para>
Fortunately, the C++ standard allows to specify the <emphasis>global</emphasis> locales (using static member Fortunately, the C++ standard allows to specify the <emphasis>global</emphasis> locales (using static member
function <code>std:locale::global()</code>). When instantiating an function <code>std:locale::global()</code>). When instantiating an
<code>std::locale</code> class without explicit information, the instance will <code>std::locale</code> class without explicit information, the instance will
be initialized with the <emphasis>global</emphasis> locale. It means, that if an algorithm needs a locale, be initialized with the <emphasis>global</emphasis> locale. This implies, that if an algorithm needs a locale,
it should have an <code>std::locale</code> parameter with default value <code>std::locale()</code>. it should have an <code>std::locale</code> parameter defaulting to <code>std::locale()</code>.
If a user needs to specify locales explicitly, she can do so. Otherwise the <emphasis>global</emphasis> If a user needs to specify locales explicitly, she can do so. Otherwise the <emphasis>global</emphasis>
locales are used. locales are used.
</para> </para>
@ -37,9 +37,9 @@
<para> <para>
Regular expressions are an essential part of text processing. For this reason, the library Regular expressions are an essential part of text processing. For this reason, the library
provides also regex variants of some algorithms. The library does not try to replace also provides regex variants of some algorithms. The library does not attempt to replace
<libraryname>Boost.Regex</libraryname>, but it merely wraps its functionality in a new interface. <libraryname>Boost.Regex</libraryname>; it merely wraps its functionality in a new interface.
As a part of this library regex algorithms integrate smoothly with other components which As a part of this library, regex algorithms integrate smoothly with other components, which
brings additional value. brings additional value.
</para> </para>
</section> </section>

65
string/doc/usage.xml
View File

@ -23,7 +23,7 @@
string str1(" hello world! "); string str1(" hello world! ");
to_upper(str1); // str1 == " HELLO WORLD! " to_upper(str1); // str1 == " HELLO WORLD! "
trim(str1); // str1 == "HELLOW WORLD!" trim(str1); // str1 == "HELLO WORLD!"
string str2= string str2=
to_lower_copy( to_lower_copy(
@ -38,19 +38,19 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><emphasis role="bold">Container parameters:</emphasis> <para><emphasis role="bold">Container parameters:</emphasis>
Unlike the STL algorithms, parameters are not specified only in form Unlike in the STL algorithms, parameters are not specified only in the form
of iterators. The STL convention allows for great flexibility, of iterators. The STL convention allows for great flexibility,
but it has several limitation. It is not possible to <emphasis>stack</emphasis> algorithms together, but it has several limitations. It is not possible to <emphasis>stack</emphasis> algorithms together,
because a container is passed in two parameters, so it is not possible to use because a container is passed in two parameters. Therefore it is not possible to use
a return value from another algorithm. It is considerably easier to write a return value from another algorithm. It is considerably easier to write
<code>to_lower(str1)</code>, then <code>to_lower(str1.begin(), str1.end())</code>. <code>to_lower(str1)</code>, than <code>to_lower(str1.begin(), str1.end())</code>.
</para> </para>
<para> <para>
The magic of <link linkend="string_algo.collection_traits">collection_traits</link> The magic of <link linkend="string_algo.collection_traits">collection_traits</link>
provides a uniform way of handling different string types. provides a uniform way of handling different string types.
If there is a need to pass a pair of iterators, If there is a need to pass a pair of iterators,
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link> <link linkend="string_algo.iterator_range"><code>iterator_range</code></link>
can be used to package iterators into a structure with the compatible interface. can be used to package iterators into a structure with a compatible interface.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -72,9 +72,9 @@
<listitem> <listitem>
<para><emphasis role="bold">Naming:</emphasis> <para><emphasis role="bold">Naming:</emphasis>
Naming follows the conventions from the Standard C++ Library. If there is a Naming follows the conventions from the Standard C++ Library. If there is a
copy and mutable version of the same algorithm, the mutable version has no suffix copy and a mutable version of the same algorithm, the mutable version has no suffix
and the copy version has suffix <emphasis>_copy</emphasis>. and the copy version has the suffix <emphasis>_copy</emphasis>.
Some algorithms have prefix <emphasis>i</emphasis> Some algorithms have the prefix <emphasis>i</emphasis>
(e.g. <functionname>ifind_first()</functionname>). (e.g. <functionname>ifind_first()</functionname>).
This prefix identifies that the algorithm works in a case-insensitive manner. This prefix identifies that the algorithm works in a case-insensitive manner.
</para> </para>
@ -131,12 +131,12 @@
cout cout
&lt;&lt; text1 &lt;&lt; text1
&lt;&lt; all( text1, is_lower() )? "is": "is not" &lt;&lt; all( text1, is_lower() )? "is": "is not"
&lt;&lt; "written in the lower case" &lt;&lt; " written in the lower case"
&lt;&lt; endl; // prints "hello world! is written in the lower case" &lt;&lt; endl; // prints "hello world! is written in the lower case"
</programlisting> </programlisting>
<para> <para>
The predicates are resolving if a substring is contained in the input string The predicates determine whether if a substring is contained in the input string
under various conditions. The conditions are if a string starts with the substring, under various conditions. The conditions are: a string starts with the substring,
ends with the substring, ends with the substring,
simply contains the substring or if both strings are equal. See the reference for simply contains the substring or if both strings are equal. See the reference for
<headername>boost/algorithm/string/predicate.hpp</headername> for more details. <headername>boost/algorithm/string/predicate.hpp</headername> for more details.
@ -147,15 +147,15 @@
This predicate can be any unary predicate, but the library provides a bunch of This predicate can be any unary predicate, but the library provides a bunch of
useful string-related predicates and combinators ready for use. useful string-related predicates and combinators ready for use.
These are located in the <headername>boost/algorithm/string/classification.hpp</headername> header. These are located in the <headername>boost/algorithm/string/classification.hpp</headername> header.
Classification predicates can be combined using logical combinators for form Classification predicates can be combined using logical combinators to form
a more complicated expressions. For example: <code>is_from_range('a','z') || is_digit()</code> a more complex expressions. For example: <code>is_from_range('a','z') || is_digit()</code>
</para> </para>
</section> </section>
<section> <section>
<title>Trimming</title> <title>Trimming</title>
<para> <para>
When parsing the input of a user, strings usually have unwanted leading or trailing When parsing the input from a user, strings usually have unwanted leading or trailing
characters. To get rid of them, we need trim functions: characters. To get rid of them, we need trim functions:
</para> </para>
<programlisting> <programlisting>
@ -169,7 +169,7 @@
trim_left_if(phone,is_any_of("0")); // phone == "423333444" trim_left_if(phone,is_any_of("0")); // phone == "423333444"
</programlisting> </programlisting>
<para> <para>
It is possible to trim the spaces on the right, on the left or on the both sides of a string. It is possible to trim the spaces on the right, on the left or on both sides of a string.
And for those cases when there is a need to remove something else than blank space, there 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 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 select the <emphasis>space</emphasis> to be removed. It is possible to use classification
@ -190,7 +190,13 @@
transform( result.begin(), result.end(), result.begin(), bind2nd(plus&lt;char&gt;(), 1) ); transform( result.begin(), result.end(), result.begin(), bind2nd(plus&lt;char&gt;(), 1) );
// text = "hello dommy!" // text = "hello dommy!"
to_upper(result); // text == "hello doMMy!" to_upper(result); // text == "hello doMMy!"
// iterator_range is convertible to bool
if(find_first(text, "dolly"))
{
cout &lt;&lt; "Dolly is there" &lt;&lt; endl;
}
</programlisting> </programlisting>
<para> <para>
We have used <functionname>find_last()</functionname> to search the <code>text</code> for "ll". We have used <functionname>find_last()</functionname> to search the <code>text</code> for "ll".
@ -202,9 +208,10 @@
char[] because this type is supported by char[] because this type is supported by
<link linkend="string_algo.collection_traits">collection_traits</link>. <link linkend="string_algo.collection_traits">collection_traits</link>.
Following lines transform the result. Notice, that The following lines transform the result. Notice that
<link linkend="string_algo.iterator_range"><code>iterator_range</code></link> have familiar <link linkend="string_algo.iterator_range"><code>iterator_range</code></link> has familiar
<code>begin()</code> and <code>end()</code> methods, so it can be used like any other STL container. <code>begin()</code> and <code>end()</code> methods, so it can be used like any other STL container.
Also it is convertible to bool therefore it is easy to use find algorithms for a simple containment checking.
</para> </para>
<para> <para>
Find algorithms are located in <headername>boost/algorithm/string/find.hpp</headername>. Find algorithms are located in <headername>boost/algorithm/string/find.hpp</headername>.
@ -215,7 +222,7 @@
<para> <para>
Find algorithms can be used for searching for a specific part of string. 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 further. After a matching part is found, it is substituted with something else. The substitution is computed
from an original, using some transformation. from the original, using some transformation.
</para> </para>
<programlisting> <programlisting>
string str1="Hello Dolly, Hello World!" string str1="Hello Dolly, Hello World!"
@ -254,8 +261,8 @@
</para> </para>
<para> <para>
There are two iterators provided <classname>find_iterator</classname> and 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 <classname>split_iterator</classname>. The former iterates over substrings that are found using the specified
Finder. The second one iterates over the gasps between these substrings. Finder. The latter iterates over the gaps between these substrings.
</para> </para>
<programlisting> <programlisting>
string str1("abc-*-ABC-*-aBc"); string str1("abc-*-ABC-*-aBc");
@ -290,9 +297,9 @@
// aBC // aBC
</programlisting> </programlisting>
<para> <para>
Note that find iterators have only one template parameter. It is the base iterator type. Note that the 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 The Finder is specified at runtime. This allows us to typedef a find iterator for
a common string types and reuse it. Additionally make_*_iterator functions helps common string types and reuse it. Additionally make_*_iterator functions help
to construct a find iterator for a particular collection. to construct a find iterator for a particular collection.
</para> </para>
<para> <para>
@ -305,8 +312,8 @@
<para> <para>
Split algorithms are an extension to the find iterator for one common usage scenario. 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 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 container. This container must be able to hold copies (e.g. <code>std::string</code>) or
references (f.e. iterator_range) of the extracted substrings. references (e.g. <code>iterator_range</code>) of the extracted substrings.
</para> </para>
<para> <para>
Two algorithms are provided. <functionname>find_all()</functionname> finds all copies Two algorithms are provided. <functionname>find_all()</functionname> finds all copies
@ -321,7 +328,7 @@
find_vector_type FindVec; // #1: Search for separators find_vector_type FindVec; // #1: Search for separators
ifind_all( FindVec, str1, "abc" ); // FindVec == { [abc],[ABC],[aBc] } ifind_all( FindVec, str1, "abc" ); // FindVec == { [abc],[ABC],[aBc] }
typdef vector&lt; string &gt; split_vector_type; typedef vector&lt; string &gt; split_vector_type;
split_vector_type SplitVec; // #2: Search for tokens split_vector_type SplitVec; // #2: Search for tokens
split( SplitVec, str1, is_any_of&lt;char&gt;("-*") ); // SplitVec == { "hello abc","ABC","aBc goodbye" } split( SplitVec, str1, is_any_of&lt;char&gt;("-*") ); // SplitVec == { "hello abc","ABC","aBc goodbye" }