diff --git a/string/doc/Jamfile.v2 b/string/doc/Jamfile.v2 index 6c3f232..5e99ba7 100644 --- a/string/doc/Jamfile.v2 +++ b/string/doc/Jamfile.v2 @@ -3,15 +3,13 @@ # Copyright Pavol Droba 2002-2003. Use, modification and # distribution is subject to the Boost Software License, Version # 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 ; toolset.using doxygen ; -import path ; - boostbook string_algo : string_algo.xml ; doxygen autodoc diff --git a/string/doc/concept.xml b/string/doc/concept.xml index bf22a54..91e52af 100644 --- a/string/doc/concept.xml +++ b/string/doc/concept.xml @@ -75,9 +75,9 @@ - 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 - 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. Note, that it is only required that the finder works with a particular iterator type. However, @@ -106,7 +106,7 @@ struct simple_finder - 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 a specific iterator type. @@ -165,8 +165,8 @@ boost::iterator_range<std::string> simple_finder( - Formatter implemented as a class. This Formatter does not perform any formating and - returns repackaged match. operator() + Formatter implemented as a class. This Formatter does not perform any formating and + returns the match, repackaged. operator() is templated, so that the Formatter can be used on any Finder type. diff --git a/string/doc/credits.xml b/string/doc/credits.xml index 77b24a2..39f3c3c 100644 --- a/string/doc/credits.xml +++ b/string/doc/credits.xml @@ -6,8 +6,10 @@
Acknowledgments - Thanks for everybody who gave suggestions and comments. Especially to Thorsten Ottosen, Jeff Garland - and the other boost members who participated. + The author would like to thank everybody who gave suggestions and comments. Especially valuable + 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.
diff --git a/string/doc/design.xml b/string/doc/design.xml index ac10a0b..de34ebc 100644 --- a/string/doc/design.xml +++ b/string/doc/design.xml @@ -25,24 +25,24 @@ 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 actually requires lessen requirements then collection concept. It implements - external collection interface. + This requirement is actually less stringent than that of collection concept. It implements + an 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. + 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 extra + storage to cache results. This is a natural assumption for common character types. Algorithms will + work even if this requirement is not satisfied, however at the cost of performance degradation. - 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 + 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 the type satisfies 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. + template argument. CollectionT means that the basic collection requirements must hold. SequenceT designates extended sequence requirements. @@ -61,29 +61,29 @@ It is possible to encapsulate a range in std::pair<>, but - the std::pair<> is a too 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. + std::pair<> 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 be of the same type. 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. - A core part of the library deals with substring searching algorithms. Any such an algorithm, - returns a range delimiting the result of the search. std::pair<> was considered as + the library, it was discovered, that there is a need for a reasonable encapsulation for it, since + core part of the library deals with substring searching algorithms and any such algorithm + returns a range delimiting the result of the search. std::pair<> was deemed as unsuitable. Therefore the iterator_range was defined. 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 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 + a basic interface for common operations. Its interface is similar to that of a collection. + In addition to begin() + and end() accessors, it has member functions for checking whether the range is empty, + 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 the collection 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. + releases. The internal version will be deprecated then. @@ -96,7 +96,7 @@ This functionality allows to write generic algorithms which work with several 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 + This facility implements the external collection concept. @@ -118,8 +118,8 @@ - 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. + Collection traits support a subset of the container concept (Std §23.1). This subset + can be described as an input container concept, e.g. a container with immutable content. Its definition can be found in the header boost/algorithm/string/collection_traits.hpp. @@ -206,15 +206,15 @@ Sequence Traits - Major difference between std::list and std::vector is not in the interfaces - they provide, 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 + The major difference between std::list and std::vector is not in the interfaces + they provide, but rather in the inner details of the class and the way how it performs + various operations. The problem is that it is not possible to infer this difference from the 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. - Sequence traits allows one to specify additional properties of a sequence container (see Std.§32.2). + Sequence traits allow 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/algorithm/string/sequence_traits.hpp. @@ -311,7 +311,7 @@ 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 Sequence traits) @@ -319,10 +319,10 @@ Find Iterators & Split Algorithms - Find iterators are a logical extension of find facility. + Find iterators are a logical extension of the 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 + are returned as the result. They can be the matching parts (find_iterator) of the parts in between (split_iterator). @@ -334,26 +334,40 @@
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 guarantee. - - - - - If the types mentioned in the first assumption can provide - strong exception guarantee for their const operations, some algorithm - can provide stronger guaranties. - - - - - - Unless stated otherwise, all facilities and algorithms in this library have basic exception guarantee. - -
+ + The library requires that all operations on types used as template + or function arguments provide the basic exception-safety guarantee. + In turn, all functions and algorithms in this library, except where stated + otherwise, will provide the basic exception-safety guarantee. + In other words: + The library maintains its invariants and does not leak resources in + the face of exceptions. Some library operations give stronger + guarantees, which are documented on an individual basis. + + + + Some functions can provide the strong exception-safety guarantee. + That means that following statements are true: + + + If an exception is thrown, there are no effects other than those + of the function + + + If an exception is thrown other than by the function, there are no effects + + + 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 . + + + In the reference, under the term strong exception-safety guarantee, we mean the + guarantee as defined above. + + + For more information about the exception safety topics, follow this + link + + diff --git a/string/doc/environment.xml b/string/doc/environment.xml index 9cfa3ec..aec08e4 100644 --- a/string/doc/environment.xml +++ b/string/doc/environment.xml @@ -9,7 +9,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/algorithm/string_regex.hpp. - If this header is used, an application must be linked with the Boost.Regex + If this header is used, the application must be linked with the Boost.Regex library. diff --git a/string/doc/intro.xml b/string/doc/intro.xml index 44bd4dd..f59cd2f 100644 --- a/string/doc/intro.xml +++ b/string/doc/intro.xml @@ -13,7 +13,7 @@ The implementation is not restricted to work with a particular container - (like a std::basic_string), rather it is as generic as + (like std::basic_string), rather it is as generic as possible. This generalization is not compromising the performance since algorithms are using container specific features when it means a performance gain. @@ -26,12 +26,12 @@ character does not have to be char or wchar_t, although these are most common candidates. - Consult design chapter to see precise specification of + Consult the design chapter to see precise specification of supported string types. - The library interface functions and classes are defined in the namespace boost::algorithm, and - they are lift into namespace boost via using declaration. + The library interface functions and classes are defined in namespace boost::algorithm, and + they are lifted into namespace boost via using declaration. The documentation is divided into several sections. For a quick start read the diff --git a/string/doc/quickref.xml b/string/doc/quickref.xml index af71d47..ad64715 100644 --- a/string/doc/quickref.xml +++ b/string/doc/quickref.xml @@ -25,9 +25,9 @@ to_upper Convert a string to upper case - to_upper_copy()() + to_upper_copy() - to_upper()() + to_upper() @@ -136,7 +136,7 @@ equals - Check if a two strings are equal + Check if two strings are equal equals() @@ -200,7 +200,7 @@ find_tail - Retrieve the fail of a string + Retrieve the tail of a string find_tail() @@ -326,7 +326,7 @@ replace/erase_head - Replace/Erase the head of a input + Replace/Erase the head of the input replace_head() @@ -340,7 +340,7 @@ replace/erase_tail - Replace/Erase the tail of a input + Replace/Erase the tail of the input replace_tail() @@ -354,7 +354,7 @@ replace/erase_regex - Replace/Erase a substring matching the the given regular expression + Replace/Erase a substring matching the given regular expression replace_regex() @@ -368,7 +368,7 @@ replace/erase_regex_all - Replace/Erase all substrings matching the the given regular expression + Replace/Erase all substrings matching the given regular expression replace_all_regex() @@ -571,7 +571,7 @@ split_iterator - Iterates through gasp between matching substrings in the input + Iterates through gaps between matching substrings in the input split_iterator @@ -611,7 +611,7 @@ is_alnum - Recognize Classify alphanumeric characters + Recognize alphanumeric characters is_alnum() @@ -650,7 +650,7 @@ is_lower() - + is_print Recognize printable characters diff --git a/string/doc/rationale.xml b/string/doc/rationale.xml index 55282b4..4df7246 100644 --- a/string/doc/rationale.xml +++ b/string/doc/rationale.xml @@ -19,15 +19,15 @@ 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 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. Fortunately, the C++ standard allows to specify the global locales (using static member function std:locale::global()). When instantiating an std::locale class without explicit information, the instance will - be initialized with the global locale. It means, that if an algorithm needs a locale, - it should have an std::locale parameter with default value std::locale(). + be initialized with the global locale. This implies, that if an algorithm needs a locale, + it should have an std::locale parameter defaulting to std::locale(). If a user needs to specify locales explicitly, she can do so. Otherwise the global locales are used. @@ -37,9 +37,9 @@ 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 - Boost.Regex, but it merely wraps its functionality in a new interface. - As a part of this library regex algorithms integrate smoothly with other components which + also provides regex variants of some algorithms. The library does not attempt to replace + Boost.Regex; it merely wraps its functionality in a new interface. + As a part of this library, regex algorithms integrate smoothly with other components, which brings additional value. diff --git a/string/doc/usage.xml b/string/doc/usage.xml index a2204aa..d86e362 100644 --- a/string/doc/usage.xml +++ b/string/doc/usage.xml @@ -23,7 +23,7 @@ string str1(" hello world! "); to_upper(str1); // str1 == " HELLO WORLD! " - trim(str1); // str1 == "HELLOW WORLD!" + trim(str1); // str1 == "HELLO WORLD!" string str2= to_lower_copy( @@ -38,19 +38,19 @@ Container parameters: - 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, - but it has several limitation. It is not possible to stack algorithms together, - because a container is passed in two parameters, so it is not possible to use + but it has several limitations. It is not possible to stack algorithms together, + 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 - to_lower(str1), then to_lower(str1.begin(), str1.end()). + to_lower(str1), than to_lower(str1.begin(), str1.end()). 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 compatible interface. + can be used to package iterators into a structure with a compatible interface. @@ -72,9 +72,9 @@ Naming: 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 - and the copy version has suffix _copy. - Some algorithms have prefix i + copy and a mutable version of the same algorithm, the mutable version has no suffix + and the copy version has the suffix _copy. + Some algorithms have the prefix i (e.g. ifind_first()). This prefix identifies that the algorithm works in a case-insensitive manner. @@ -131,12 +131,12 @@ cout << text1 << all( text1, is_lower() )? "is": "is not" - << "written in the lower case" + << " written in the lower case" << endl; // prints "hello world! is written in the lower case" - The predicates are resolving if a substring is contained in the input string - under various conditions. The conditions are if a string starts with the substring, + The predicates determine whether if a substring is contained in the input string + under various conditions. The conditions are: 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/algorithm/string/predicate.hpp for more details. @@ -147,15 +147,15 @@ This predicate can be any unary predicate, but the library provides a bunch of 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() + Classification predicates can be combined using logical combinators to form + a more complex expressions. For example: is_from_range('a','z') || is_digit()
Trimming - 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: @@ -169,7 +169,7 @@ 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. + 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 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 @@ -190,7 +190,13 @@ transform( result.begin(), result.end(), result.begin(), bind2nd(plus<char>(), 1) ); // 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 << "Dolly is there" << endl; + } We have used find_last() to search the text for "ll". @@ -202,9 +208,10 @@ char[] because this type is supported by 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. + The following lines transform the result. Notice that + iterator_range has familiar + begin() and end() 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. Find algorithms are located in boost/algorithm/string/find.hpp. @@ -215,7 +222,7 @@ 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. + from the original, using some transformation. string str1="Hello Dolly, Hello World!" @@ -254,8 +261,8 @@ 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. + split_iterator. The former iterates over substrings that are found using the specified + Finder. The latter iterates over the gaps between these substrings. string str1("abc-*-ABC-*-aBc"); @@ -290,9 +297,9 @@ // 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. Additionally make_*_iterator functions helps + Note that the find iterators have only one template parameter. It is the base iterator type. + The Finder is specified at runtime. This allows us to typedef a find iterator for + common string types and reuse it. Additionally make_*_iterator functions help to construct a find iterator for a particular collection. @@ -305,8 +312,8 @@ 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. + container. This container must be able to hold copies (e.g. std::string) or + references (e.g. iterator_range) of the extracted substrings. Two algorithms are provided. find_all() finds all copies @@ -321,7 +328,7 @@ find_vector_type FindVec; // #1: Search for separators ifind_all( FindVec, str1, "abc" ); // FindVec == { [abc],[ABC],[aBc] } - typdef vector< string > split_vector_type; + typedef vector< string > split_vector_type; split_vector_type SplitVec; // #2: Search for tokens split( SplitVec, str1, is_any_of<char>("-*") ); // SplitVec == { "hello abc","ABC","aBc goodbye" }