Good points raised. What version of Boost though? Thanks Shams -- "Martin Adrian" <adrianm@touchdown.se> wrote in message news:loom.20061031T102627-559@post.gmane.org...

I have used the string_algo library for a long time and is used to how it works. Recently I had to introduce a collegue to it and started to write a document but it wasn't easy.

Here is a few points:

1. The word predicate is used to describe anything which can return a boolean value. While this is technicly correct it creates confusion since there are many different predicates used in the library. Example: Both trim_if and starts_with takes a PredicateT argument but they are not the same predicate types.

I have found the following predicates: - Unary token predicate: These are all the classification predicates: is_space, is_from_range etc - Binary token predicate: These are the token comparison predicates: is_equal, is_iless etc - Unary string predicate: These are the string validation predicates: all, regex_match - Binary string predicate: These are the substring match predicates: starts_with, contains etc.

Note here that the "string predicates" are different from the "token predicates" since they don't return functors (and can't be used directly with standard algorithms).

My suggestion is to clear this up in such a way that all predicate types are given a name (e.g. UnaryTokenPredicateT) and that they are available as both a free function and a boolean functor. Naming will be tricky to get right.

is_space: functor: boost::is_space( Locale ) free function: std::is_space( Char, Locale ) is_iequal: functor: boost::is_iequal( Locale ) free function: ??(Char1, Char2, Locale) starts_with: functor: ??(String, String) free function: starts_with(String, String)

2. There are a number of suffixes used within the library. Here is my interpretation:

nosuffix: Mutable verision _copy: const version returning a copy _if: version using a (non-default) predicate _regex: version using a regex predicate _first, _last, _nth, _all, _head, _tail: for search/replace/erase algorithms _range: Not sure what this is supposed to mean

Most are fine but there are some inconsistances: - find/replace/erase algorithms can work with 2 different predicates (token predicate and Finder). The naming isn't consistant. find_all takes a token predicate while make_find_iterator uses a Finder. - trim taking a unary token predicate is called trim_if but find taking the same argument is called find_token - replace with predicate is called find_format - join taking a regex argument is called join_if - starts_with etc use overload instead of _if suffix

3. There are lot of (randomly) missing algorithms. - erase_if, erase_all_if, erase_copy_if, erase_all_copy_if taking a Finder argument (all these are availble as replace with _formatter suffix) - is_token, is_itoken, is_ianyof - ifirst_finder, ilast_finder, inth_finder - find_all and split taking a finder argument - make_split_iterator and make_find_iterator with token predicate

4. Other stuff - ilexicographical_compare is missing locale argument - range_finder seems odd. What is the purpose? - why is the predicate called not_greater instead of less_equal (compare to std::less_equal) - regex_search_result is derived from iterator_range but iterator_range doesn't have a virtual destructor. It might be safe but I couldn't verify it. - there is no special string_algo "regex_match" predicate. The regex version is limited to basic_string argument.

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Hi, Martin Adrian wrote:

I have used the string_algo library for a long time and is used to how it works. Recently I had to introduce a collegue to it and started to write a document but it wasn't easy.

First of all, thanks for comments. I'm glad that somebody takes so much attention to this library. And sorry for the delay. I'd like to start my reply with explanation of one misconception that I have seen in your mail. Many algorithms in this library use a user suplied functor. But not all functors are predicates as you incorrectly assumed. Finder and Formatter are typical examples of other functors used in the library. Now to you points.

Here is a few points:

1. The word predicate is used to describe anything which can return a boolean value. While this is technicly correct it creates confusion since there are many different predicates used in the library. Example: Both trim_if and starts_with takes a PredicateT argument but they are not the same predicate types.

I have found the following predicates: - Unary token predicate: These are all the classification predicates: is_space, is_from_range etc - Binary token predicate: These are the token comparison predicates: is_equal, is_iless etc - Unary string predicate: These are the string validation predicates: all, regex_match - Binary string predicate: These are the substring match predicates: starts_with, contains etc.

Note here that the "string predicates" are different from the "token predicates" since they don't return functors (and can't be used directly with standard algorithms).

My suggestion is to clear this up in such a way that all predicate types are given a name (e.g. UnaryTokenPredicateT) and that they are available as both a free function and a boolean functor. Naming will be tricky to get right.

is_space: functor: boost::is_space( Locale ) free function: std::is_space( Char, Locale ) is_iequal: functor: boost::is_iequal( Locale ) free function: ??(Char1, Char2, Locale) starts_with: functor: ??(String, String) free function: starts_with(String, String)

This is a valid claim. However, it is always quite clear from the algorithm description, what predicate can be used. In addition, not all predicates in the library are just utilities for other algorithms. Even in the algorithms that accept a predicate, user is free to use her own version, not necessary something from the string_algo library. If you look through documentation, you will see, that there are no algorithm that use "string predicates". Actualy, only two kind of paremetric predicates are used: "Character classification" and "Character comparison". I think, that it is quite clear which predicate to use with a given algorithm. Even if a confusion would appear, compiler will issue an error imediately, since these two categories have different signatures.

2. There are a number of suffixes used within the library. Here is my interpretation:

Let me correct this:

nosuffix: Mutable verision

no suffix means a "default". Not all algorithms perform some transformation (like afordmentioned predicates). However, as you correctly stated, in transformation algorithms, mutable version is default

_copy: const version returning a copy

this is correct

_if: version using a (non-default) predicate

_if suffix is used only when it is impossible to use standard overloading rules to distinguish between algorithms. Currently there are only two cases: trim and join.

_regex: version using a regex predicate

This is not correct. _regex suffix designates a regex variant of algorithm. There is nothing like "a regex predicate".

_first, _last, _nth, _all, _head, _tail: for search/replace/erase algorithms _range: Not sure what this is supposed to mean

All these suffixes define what kind of search operation is used. Or in other words, what part of the string will be affected. _range suffix means, that an algorithm will now perform an actual searching, rather the 'working range' will be specified explicitly by the user. This is usefull, for instance, if you have a special algorithm that performs a "search" and you just want to use string-algo to perform replace .

Most are fine but there are some inconsistances: - find/replace/erase algorithms can work with 2 different predicates (token predicate and Finder). The naming isn't consistant. find_all takes a token predicate while make_find_iterator uses a Finder. - trim taking a unary token predicate is called trim_if but find taking the same argument is called find_token - replace with predicate is called find_format - join taking a regex argument is called join_if - starts_with etc use overload instead of _if suffix

Whole this paragraph is very confusing. As I stateed at the beginnig, you are mixing together functors with predicates. They are not the same. Finder does not even return bool. join exists in the variants. plain 'join' simply concatenates all elemets from the input container. 'join_if' excludes those that do not satisfy the given condition. There are actualy two variants of 'join_if' One that takes an arbitrary predicate and the other, that accepts a regular expression.

3. There are lot of (randomly) missing algorithms. - erase_if, erase_all_if, erase_copy_if, erase_all_copy_if taking a Finder argument (all these are availble as replace with _formatter suffix)

erase* and replace* algorithms are specializations of find_format provided for convenience. They simply construct a finder and a formatter from the input paremeters and forward the call to the find_format. There is already quite large number of algorithm and I see no reason why to provide additional variants that are easily accesible. No we have: replace_first(input, str,str) erase_first(input, str) that both forward to find_format(input, finder, formatter) If you want erase_if (btw. _if is totaly incosistent here, since there is no predicate here), you can simply use find_format(input, finder, empty_formatter(input)).

- is_token, is_itoken, is_ianyof

What is is_token supposed to do? is_ianyof might be usefull.

- ifirst_finder, ilast_finder, inth_finder

finder constructors are considered to be "advanced stuff" therefore they are limitided to basic functionality. I don't mean to bloat interface with additional "convenience" wrappers.

- find_all and split taking a finder argument

These algorithms actually exists. They are called iter_find and iter_split. Currently they are held as an implementation layer, but due to several requests from users, I will move them higher. This meas, that they will be also documented.

- make_split_iterator and make_find_iterator with token predicate

Use token_finder here. Convenience layer for find_iterators is presented in the form of find_all and split algorithms. This might change in the future, but I don't have concrete plans for this.

4. Other stuff - ilexicographical_compare is missing locale argument

This is obviosly a bug. Thans for report.

- range_finder seems odd. What is the purpose?

See above.

- why is the predicate called not_greater instead of less_equal (compare to std::less_equal)

Not sure. I think, that both namings are equaly good.

- regex_search_result is derived from iterator_range but iterator_range doesn't have a virtual destructor. It might be safe but I couldn't verify it.

Due to templated nature of the implementation, regex_search_result is never use indirectly as iterator_range. Therefore there is no problem that I'm aware of.

- there is no special string_algo "regex_match" predicate. The regex version is limited to basic_string argument.

Regex part of string-algo library was never considered to be a full replacement of Boost.Regex. So it is natural, that some parts of functionality are missing. There were already some requests to add regex awareness to string predicates, so a kind "regex_match" predicate migh appear there. Best Regards, Pavol