Re: [boost] string_algo Formal Review

From: Pavol Droba (droba_at_[hidden])
Date: 2003-10-22 02:33:59

Hi,

First of all, I'd like to thank you for your review.
I'm very glad to see, that somebody find this library usable.

On Tue, Oct 21, 2003 at 11:12:34PM -0700, Jeff Garland wrote:

[snip]
 
> To review the library I read the docs and wrote several test programs using
> gcc 3.2 on Linux. I also skimmed through several of the implementation headers
> and looked through the examples and tests. I also tried to compile,
> unsuccessfully, the examples and tests.  However, I believe these compilation
> issues are more related to the current state of my boost tree than the library
> (mostly regex stuff and regex isn't compiling for me at this moment).  I
> believe this to be my own issue and not a problem with the library.  Also, it
> allowed me to test directly that the Regex library is only needed if Regex
> features are used.  Overall I found the library easy to use and the
> documentation and examples to be quite good.  The overall design of the
> library seems sound and the source is quite readable.  The test suite appears
> to be extensive and should facilitate porting to additional platforms.  

The best thing, you can do, to make the library compile, is to get a fresh snapshot
from CVS and put the string_algo there. For GCC there should not be any problem.

[snip]
 
> Now for a few new issues:
> 1) Any reason why we can't put all functions in namespace boost::string_algo
> (or boost::algorithm::string)?  I found it a little tricky to figure out which
> things were boost versus string_algo.

There are more resons for separation of functions in different namespaces.

- First is a logical decomposition. 
  Ordinary user should be able to find all functionality
  in the namespace boost. The selection of algorithms in this layer was designed
  to cover most of common needs.
  string_algo namespace, on the other hand, contains more generic variants, mostly targeted
  for advanced user who want to experiment and gain more power from the lib.

- Second resons is syntactical. If all functions would be in one namespace, there is
  a big probablility of name clashes. Because the majority of arguments in the algorithms 
  is templated, the only distintion between different variants of the same algorithm
  is the number of paramters.
  So putting everything into one namespace would most probably imply the need to rename
  some functions.

The need for the simple table in docs, showing the list of algorithms and their variants,
was already identified. Such a table would simplify the orientation in namespaces.

> 2) On a related front, I don't really care for the find.hpp, find2.hpp,
> replace.hpp, replace2.hpp dichotomy.  As a user I think of using find. There
> are several variations, some more complex than others.  But 'find2' doesn't
> give me any clues as to when I need to include find2.hpp version find.hpp.
> Perhaps find_generic.hpp instead?  Or maybe everything in find.hpp? (Note that
> in my reading of the source it appears that all of the zzzz2.hpp headers are
> always included in the zzzz.hpp header anyway).

This separation follows the idea of namespaces. xxx2.hpp contains string_algo layer stuff.
It is always included by the xxx.hpp headers. boost namespace algorithms are mostly
only a simple wrapper of a generic siblings.

If you don't want to bother, simply include <boost/string_algo.hpp> (or string_algo.regex.hpp) and 
you have all the functionality available.

> 3) There are a number of grammer issues in the docs.  Too many to list here,
> but I'll try to help you with some of these offline.  I realize English can be
> a challange -- for both native and non-native speakers...
> 
Well, grammar is always a challenge for me, and I'm not talking just about the english one :)
And there is a problem to find enough voulenteers to check the spelling. 

Best Regards,

Pavol