[boost] [string_algo] comments

From: Martin Adrian (adrianm_at_[hidden])
Date: 2006-10-31 04:56:43

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.