diff --git a/string/doc/Jamfile.v2 b/string/doc/Jamfile.v2 index 8859c4c..6c3f232 100644 --- a/string/doc/Jamfile.v2 +++ b/string/doc/Jamfile.v2 @@ -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 ] : HIDE_UNDOC_MEMBERS=YES EXTRACT_PRIVATE=NO @@ -52,10 +50,6 @@ doxygen reference PREDEFINED="BOOST_STRING_TYPENAME=typename \"BOOST_STATIC_CONSTANT(type,var)=static const type var;\"" ; -boostbook string_algo - : - string_algo.xml - ; diff --git a/string/doc/concept.xml b/string/doc/concept.xml index 5b1fa81..bf22a54 100644 --- a/string/doc/concept.xml +++ b/string/doc/concept.xml @@ -5,7 +5,7 @@ Concepts - +
Definitions diff --git a/string/doc/design.xml b/string/doc/design.xml index 8240b4d..d055fa1 100644 --- a/string/doc/design.xml +++ b/string/doc/design.xml @@ -5,7 +5,48 @@ Design Topics - + + +
+ String Representation + + + 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 std::basic_string), + rather it is a concept. This allows the algorithms in this library to be reused for any string type, + that satisfies the given requirements. + + + Definition: A string is a + collection of characters accessible in sequential + ordered fashion. Character is any value type with "cheap" copying and assignment. + + + First requirement of string-type is that it must accessible using + collection traits. 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 + external collection interface. + This is sufficient for our library + + + 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. + + + 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 §23.1.1) requirements. + + + In the reference and also in the code, requirement on the string type is designated by the name of + template argument. CollectionT means that the basic collection requirements must be held. + SequenceT designates extended sequence requirements. + +
+
<code>iterator_range</code> class @@ -32,27 +73,35 @@ The intention of the iterator_range 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 begin() and end() 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 container traits requirements so + the collecion traits requirements so it is possible to use this class as a parameter to many algorithms in this library. + + iterator_range will be moved to Boost.Range library in the future + releases. Internal version will be deprecated then. +
-
- Container Traits +
+ Collection Traits - Container traits provide uniform access to different types of containers. + Collection traits provide uniform access to different types of + collections . 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 std::string as well as with char[]. + This facility implements + external collection + concept. - The following container types are supported: + The following collection types are supported: Standard containers @@ -69,78 +118,78 @@ - Container traits support a subset of container concept (Std §23.1). This subset + Collection traits support a subset of container concept (Std §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 boost/string_algo/container_traits.hpp. + Its definition can be found in the header boost/algorithm/string/collection_traits.hpp. In the table C denotes a container and c is an object of C. - Container Traits + Collection Traits Name - Standard container equivalent + Standard collection equivalent Description Maeterlinck - container_value_type<C>::type + value_type_of<C>::type C::value_type Type of contained values - container_difference_type<C>::type + difference_type_of<C>::type C::difference_type - difference type of the container + difference type of the collection - container_iterator<C>::type + iterator_of<C>::type C::iterator - iterator type of the container + iterator type of the collection - container_const_iterator<C>::type + const_iterator_of<C>::type C::const_iterator - const_iterator type of the container + const_iterator type of the collection - container_result_iterator<C>::type + result_iterator_of<C>::type - result_iterator type of the container. This type maps to C::iterator - for mutable container and C::const_iterator for const containers. + result_iterator type of the collection. This type maps to C::iterator + for mutable collection and C::const_iterator for const collection. begin(c) c.begin() - Gets the iterator pointing to the start of the container. + Gets the iterator pointing to the start of the collection. end(c) c.end() - Gets the iterator pointing to the end of the container. + Gets the iterator pointing to the end of the collection. size(c) c.size() - Gets the size of the container. + Gets the size of the collection. empty(c) c.empty() - Checks if the container is empty. + Checks if the collection is empty. @@ -148,9 +197,8 @@
- 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.
@@ -169,7 +217,7 @@ Sequence traits allows one to specify additional properties of a sequence container (see Std.§32.2). These properties are then used by algorithms to select optimized handling for some operations. The sequence traits are declared in the header - boost/string_algo/sequence_traits.hpp. + boost/algorithm/string/sequence_traits.hpp. @@ -186,11 +234,11 @@ - sequence_has_native_replace<C>::value + has_native_replace<C>::value Specifies that the sequence has std::string like replace method - sequence_has_stable_iterators<C>::value + has_stable_iterators<C>::value Specifies that the sequence has stable iterators. It means, that operations like insert/erase/replace @@ -198,14 +246,14 @@ - sequence_has_const_time_insert<C>::value + has_const_time_insert<C>::value Specifies that the insert method of the sequence has constant time complexity. - sequence_has_const_time_erase<C>::value + has_const_time_erase<C>::value Specifies that the erase method of the sequence has constant time complexity @@ -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 << n (m magnitued smaller than n) the current implementation + rather big. For small m << 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 @@
- Split Algorithms + Find Iterators & Split Algorithms - Split algorithms are a logical extension of find facility. - 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 (find_all()) of the parts in - between (split()). + Find iterators are a logical extension of find facility. + 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 (find_iterator) of the parts in + between (split_iterator). + + + In addition the split algorithms like find_all() and split() + 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. + +
+
+ Exception Safety + + + The library provides some exceptions safety guaranties under following assumptions: + + + + All types that are used as a template arguments or passed as arguments to the + facilities in this library provide basic exception guarantie. + + + + + If the types mentioned in the first assumption can provide + strong exception guarantie for their const operations, some algorithm + can provide stronger guaranties. + + + + + + Unless stated otherwise, all facilities and algorithms in this library have basic exception guarantie.
diff --git a/string/doc/environment.xml b/string/doc/environment.xml index 3364b97..9cfa3ec 100644 --- a/string/doc/environment.xml +++ b/string/doc/environment.xml @@ -8,7 +8,7 @@ The whole library is provided in headers. Regex variants of some algorithms, however, are dependent on the Boost.Regex library. All such algorithms are - separated in boost/string_algo/regex.hpp. + separated in boost/algorithm/string_regex.hpp. If this header is used, an application must be linked with the Boost.Regex library. @@ -17,7 +17,7 @@
Examples - 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 Boost.Regex library is required. @@ -27,7 +27,7 @@
Tests - 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 Boost.Regex library is required. @@ -44,12 +44,16 @@ GCC 3.2 GCC 3.3.1 + + See Boost regression tables + for additional info for a particular compiler. 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 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.
diff --git a/string/doc/external_concepts.html b/string/doc/external_concepts.html new file mode 100644 index 0000000..98ccf90 --- /dev/null +++ b/string/doc/external_concepts.html @@ -0,0 +1,38 @@ + Concepts and External Concepts

Concepts and External Concepts

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 concept. We say that a type + conforms to a concept or that it is a model of a concept 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.

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 as if + they fulfilled the concept. In this case we say that the concept has + been externalized or that the new requirements constitutes an external + concept . We say that a type conforms to an external concept + or that it is a model of an external concept . A concept may exist + without a corresponding external concept and conversely.

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 type-generator, that is, a type with a nested typedef + named type. The type-generator has the name as the nested typedef with + _of appended. + The converse relationship of an external concept and its corresponding concept + also holds.

Example:

A type T fulfills the FooConcept if it + has the follwing public members:

void T::foo( int ) const;
+ int T::bar();
+ typedef implementation defined foo_type;

The corresponding external concept is the ExternalFooConcept.

A type T fullfills the ExternalFooConcept if these + free-standing functions and type-generators exists:

void foo( const T&, int );
+ int bar( T& );
+ foo_type_of< T >::type;

Literature

© 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.































+ \ No newline at end of file diff --git a/string/doc/intro.xml b/string/doc/intro.xml index 882bfb7..44bd4dd 100644 --- a/string/doc/intro.xml +++ b/string/doc/intro.xml @@ -18,23 +18,25 @@ algorithms are using container specific features when it means a performance gain. + + + Important note: In this documentation we use term string to + designate a sequence of characters stored in an arbitrary container. + A string is not restricted to std::basic_string and + character does not have to be char or wchar_t, + although these are most common candidates. + + Consult design chapter to see precise specification of + supported string types. + - The library has layered structure to simplify the usage without sacrificing the - generalization. - - The easy-to-use interface, defined in the namespace boost, 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 boost::string_algo, 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 boost::algorithm, and + they are lift into namespace boost via using declaration. The documentation is divided into several sections. For a quick start read the - Usage section. + Usage section followed by + Quick Reference. The Design Topics, Concepts and Rationale provide some explanation about the library design and structure an explain how it should be used. diff --git a/string/doc/quickref.xml b/string/doc/quickref.xml new file mode 100644 index 0000000..75d04a3 --- /dev/null +++ b/string/doc/quickref.xml @@ -0,0 +1,686 @@ + + +
+ Quick Reference + + + + +
+ Algorithms + + + Case Conversion + + + + Algorithm name + Description + Functions + + + + + to_upper + Convert a string to upper case + + to_upper_copy()() + + to_upper()() + + + + to_lower + Convert a string to lower case + + to_lower_copy() + + to_lower() + + + + +
+ + Trimming + + + + Algorithm name + Description + Functions + + + + + trim_left + Remove leading spaces from a string + + trim_left_copy_if() + + trim_left_if() + + trim_left_copy() + + trim_left() + + + + trim_right + Remove trailing spaces from a string + + trim_right_copy_if() + + trim_right_if() + + trim_right_copy() + + trim_right() + + + + trim + Remove leading and trailing spaces from a string + + trim_copy_if() + + trim_if() + + trim_copy() + + trim() + + + + + +
+ + Predicates + + + + Algorithm name + Description + Functions + + + + + starts_with + Check if a string is a prefix of the other one + + starts_with() + + istarts_with() + + + + ends_with + Check if a string is a suffix of the other one + + ends_with() + + iends_with() + + + + contains + Check if a string is contained of the other one + + contains() + + icontains() + + + + equals + Check if a two strings are equal + + equals() + + iequals() + + + + all + Check if all elements of a string satisfy the given predicate + + all() + + + + +
+ + Find algorithms + + + + Algorithm name + Description + Functions + + + + + find_first + Find the first occurrence of a string in the input + + find_first() + + ifind_first() + + + + find_last + Find the last occurrence of a string in the input + + find_last() + + ifind_last() + + + + find_nth + Find the nth (zero-indexed) occurrence of a string in the input + + find_nth() + + ifind_nth() + + + + find_head + Retrieve the head of a string + + find_head() + + + + find_tail + Retrieve the fail of a string + + find_tail() + + + + find_token + Find first matching token in the string + + find_token() + + + + find_regex + Use the regular expression to search the string + + find_regex() + + + + find + Generic find algorithm + + find() + + + + +
+ + Erase/Replace + + + + Algorithm name + Description + Functions + + + + + replace/erase_first + Replace/Erase the first occurrence of a string in the input + + replace_first() + + replace_first_copy() + + ireplace_first() + + ireplace_first_copy() + + erase_first() + + erase_first_copy() + + ierase_first() + + ierase_first_copy() + + + + replace/erase_last + Replace/Erase the last occurrence of a string in the input + + replace_last() + + replace_last_copy() + + ireplace_last() + + ireplace_last_copy() + + erase_last() + + erase_last_copy() + + ierase_last() + + ierase_last_copy() + + + + replace/erase_nth + Replace/Erase the nth (zero-indexed) occurrence of a string in the input + + replace_nth() + + replace_nth_copy() + + ireplace_nth() + + ireplace_nth_copy() + + erase_nth() + + erase_nth_copy() + + ierase_nth() + + ierase_nth_copy() + + + + replace/erase_all + Replace/Erase the all occurrences of a string in the input + + replace_all() + + replace_all_copy() + + ireplace_all() + + ireplace_all_copy() + + erase_all() + + erase_all_copy() + + ierase_all() + + ierase_all_copy() + + + + replace/erase_head + Replace/Erase the head of a input + + replace_head() + + replace_head_copy() + + erase_head() + + erase_head_copy() + + + + + replace/erase_tail + Replace/Erase the tail of a input + + replace_tail() + + replace_tail_copy() + + erase_tail() + + erase_tail_copy() + + + + + replace/erase_regex + Replace/Erase a substring matching the the given regular expression + + replace_regex() + + replace_regex_copy() + + erase_regex() + + erase_regex_copy() + + + + + replace/erase_regex_all + Replace/Erase all substrings matching the the given regular expression + + replace_all_regex() + + replace_all_regex_copy() + + erase_all_regex() + + erase_all_regex_copy() + + + + + find_format + Generic replace algorithm + + find_format() + + find_format_copy() + + find_format_all() + + find_format_all_copy()() + + + + +
+ + Split + + + + Algorithm name + Description + Functions + + + + + find_all + Find/Extract all matching substrings in hte input + + find_all() + + ifind_all() + + find_all_regex() + + + + split + Split input into parts + + split() + + split_regex() + + + + +
+
+
+ Finders and Formatters + + + Finders + + + + Finder + Description + Generators + + + + + first_finder + Search for the first match of the string in an input + + first_finder() + + + + last_finder + Search for the last match of the string in an input + + last_finder() + + + + nth_finder + Search for the nth (zero-indexed) match of the string in an input + + nth_finder() + + + + head_finder + Retrieve the head of an input + + head_finder() + + + + tail_finder + Retrieve the tail of an input + + tail_finder() + + + + token_finder + Search for a matching token in an input + + token_finder() + + + + range_finder + Do no search, always returns the given range + + range_finder() + + + + regex_finder + Search for a substring matching the given regex + + regex_finder() + + + + +
+ + + Formatters + + + + Formatter + Description + Generators + + + + + const_formatter + Constant formatter. Always return the specified string + + const_formatter() + + + + identity_formatter + Identity formatter. Return unmodified input input + + identity_formatter() + + + + empty_formatter + Null formatter. Always return an empty string + + empty_formatter() + + + + regex_formatter + Regex formatter. Format regex match using the specification in the format string + + regex_formatter() + + + + +
+
+
+ Iterators + + + Find Iterators + + + + Iterator name + Description + Iterator class + + + + + find_iterator + Iterates through matching substrings in the input + + find_iterator + + + + split_iterator + Iterates through gasp between matching substrings in the input + + split_iterator + + + + +
+
+ +
+ Classification + + + Predicates + + + + Predicate name + Description + Generator + + + + + is_classified + Generic ctype mask based classification + + is_classified() + + + + is_space + Recognize spaces + + is_space() + + + + is_alnum + Recognize Classify alphanumeric characters + + is_alnum() + + + + is_alpha + Recognize letters + + is_alpha() + + + + is_cntrl + Recognize control characters + + is_cntrl() + + + + is_digit + Recognize decimal digits + + is_digit() + + + + is_graph + Recognize graphical characters + + is_graph() + + + + is_lower + Recognize lower case characters + + is_lower() + + + + is_print + Recognize printable characters + + is_print() + + + + is_punct + Recognize punctuation characters + + is_punct() + + + + is_upper + Recognize uppercase characters + + is_upper() + + + + is_xdigit + Recognize hexadecimal digits + + is_xdigit() + + + + +
+
+
diff --git a/string/doc/rationale.xml b/string/doc/rationale.xml index 4691d7b..55282b4 100644 --- a/string/doc/rationale.xml +++ b/string/doc/rationale.xml @@ -5,39 +5,9 @@ Rationale - + -
- Library structure - - - 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. - - - Imagine a library for drawing geometric objects. It can contain one generic function draw() - 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, draw_triangle() and - draw_square(), would suit much better then a generic draw() function. - - - 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 boost::string_algo), provides generic interfaces with - more options for extending and tunning. - - - For instance, a boost::trim() algorithm trims spaces from - an input string. When there is a need to trim something else, there is - boost::string_algo::trim() which interface allows one to specify a - predicate which selects the characters to be removed. - -
-
+
Locales diff --git a/string/doc/string_algo.xml b/string/doc/string_algo.xml index dae1eb2..c768e1d 100644 --- a/string/doc/string_algo.xml +++ b/string/doc/string_algo.xml @@ -12,6 +12,7 @@ 2002 2003 + 2004 Pavol Droba @@ -32,9 +33,10 @@ Boost String Algorithms Library + - + diff --git a/string/doc/usage.xml b/string/doc/usage.xml index df48827..1e658e9 100644 --- a/string/doc/usage.xml +++ b/string/doc/usage.xml @@ -5,7 +5,7 @@ Usage - +
@@ -18,14 +18,17 @@ #include <boost/string_algo.hpp> 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!" This example converts str1 to upper case and trims spaces from the start and the end @@ -43,11 +46,11 @@ to_lower(str1), then to_lower(str1.begin(), str1.end()). - The magic of container_traits - provides a uniform way of handling different containers. + The magic of collection_traits + provides a uniform way of handling different string types. If there is a need to pass a pair of iterators, iterator_range - 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. @@ -61,10 +64,9 @@ Algorithm stacking: - 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 - trim_copy(to_upper_copy(s)) as well as trim(to_upper(s))). + Copy versions return a transformed input as a result, thus allow a simple chaining of + transformations within one expression (i.e. one can write trim_copy(to_upper_copy(s))). + Mutable versions have void return, to avoid missuse. @@ -79,9 +81,9 @@ - To use the library, include the boost/string_algo.hpp header. + To use the library, include the boost/algorithm/string.hpp header. If the regex related functions are needed, include the - boost/string_algo_regex.hpp header. + boost/algorithm/string_regex.hpp header.
@@ -97,7 +99,10 @@ to_upper() and to_lower() convert the case of - characters in a container using a specified locale. + characters in a string using a specified locale. + + + For more information see the reference for boost/algorithm/string/case_conv.hpp.
@@ -125,7 +130,7 @@ char text1[]="hello world!"; cout << text1 - << all( text1, is_lower<char>() )? "is": "is not" + << all( text1, is_lower() )? "is": "is not" << "written in the lower case" << endl; // prints "hello world! is written in the lower case" @@ -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 - boost/string_algo/predicate.hpp for more details. + boost/algorithm/string/predicate.hpp for more details. + + In addition the algorithm all() 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 boost/string_algo/classification.hpp header. + useful string-related predicates and combinators ready for use. + These are located in the boost/algorithm/string/classification.hpp header. + Classification predicates can be combined using logical combinators for form + a more complicated expressions. For example: is_from_range('a','z') || is_digit()
@@ -157,15 +166,15 @@ string phone="00423333444"; // remove leading 0 from the phone number - sa::trim_left(phone,is_any_of<char>("0")); // phone == "423333444" + trim_left_if(phone,is_any_of("0")); // phone == "423333444" 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 - string_algo namespace contains generic versions of the trim algorithms. Using these, - a user can specify a functor which will select the space to be removed. It is possible to use - classification predicates like is_digit() mentioned in the previous paragraph. - See the reference for the boost/string_algo/trim.hpp. + And for those cases when there is a need to remove something else than blank space, there + are _if variants. Using these, a user can specify a functor which will + select the space to be removed. It is possible to use classification + predicates like is_digit() mentioned in the previous paragraph. + See the reference for the boost/algorithm/string/trim.hpp.
@@ -191,17 +200,20 @@ As we can see, input of the find_last() algorithm can be also char[] because this type is supported by - container_traits. + collection_traits. Following lines transform the result. Notice, that iterator_range have familiar begin() and end() methods, so it can be used like any other STL container. + + Find algorithms are located in boost/algorithm/string/find.hpp. +
Replace Algorithms - 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. @@ -216,7 +228,7 @@ For the complete list of replace and erase functions see the reference. There is a lot of predefined function for common usage, however, the library allows you to - define a custom replace() that suits a specific need. There is a generic replace() + define a custom replace() that suits a specific need. There is a generic find_format() function which takes two parameters. The first one is a Finder object, the second one is a Formatter 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. + + Check boost/algorithm/string/replace.hpp, boost/algorithm/string/erase.hpp and + boost/algorithm/string/find_format.hpp for reference. + +
+
+ Find Iterator + + + 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 Finder to incrementaly + search the string. + Dereferencing a find iterator yields an iterator_range + object, that delimits the current match. + + + There are two iterators provided find_iterator and + split_iterator. First one iterates over substrings that are found using the specified + Finder. The second one iterates over the gasps between these substrings. + + + string str1("abc-*-ABC-*-aBc"); + // Find all 'abc' substrings (ignoring the case) + // Create a find_iterator + typedef find_iterator<string::iterator> string_find_iterator; + for(string_find_iterator It= + make_find_iterator(str1, first_finder("abc", is_iequal())); + It!=string_find_iterator(); + ++It) + { + cout << copy_iterator_range<std::string>(*It) << endl; + } + + // Output will be: + // abc + // ABC + // aBC + + typedef split_iterator<string::iterator> string_split_iterator; + for(string_find_iterator It= + make_split_iterator(str1, first_finder("-*-", is_iequal())); + It!=string_find_iterator(); + ++It) + { + cout << copy_iterator_range<std::string>(*It) << endl; + } + + // Output will be: + // abc + // ABC + // aBC + + + 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. + + + See the reference in boost/algorithm/string/find_iterator.hpp. +
Split - Split algorithms allow one to divide a sequence into parts. Each part represents a - token and tokens are separated by separators. - 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. + + + Two algorithms are provided. find_all() finds all copies + of a string in the input. split() splits the input into parts. @@ -251,25 +330,17 @@ [hello] designates an iterator_range delimiting this substring. - The result of a split algorithm is a container of containers. 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 - iterator_range - instead of e.g. std::string. 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 ifind_all() puts into FindVec references + to all substrings that are in case-insensitive manner equal to "abc". - So to recap, there are two basic algorithms: find_all() - returns extracts the parts - matching the specification whereas split() uses the matching - parts as delimiters, and extracts the parts in between them. + Second example uses split() 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. - Generalizations of these two algorithms are called iter_find() and - iter_split(). They take a - Finder object, as an argument to search for - the substring. - -
+ More information can be found in the reference: boost/algorithm/string/split.hpp. + +