Re: [boost] [string_algo] Documentation Complaint

Subject: Re: [boost] [string_algo] Documentation Complaint
From: John Bytheway (jbytheway+boost_at_[hidden])
Date: 2012-11-01 19:02:36

On 01/11/12 15:33, Dave Abrahams wrote:
> 
> Wow, I found this documentation hard to use!
> 
> I wanted to translate various 1-character substrings into new strings,
> e.g. translate the TAB character ('\t') to its textual escaped
> representation "\\t", and I went looking for an algorithm to do it.
> 
> After 5 minutes of searching, I *think* the algorithm isn't there, but
> I'm still not sure.

I think replace_all_copy will do it
<http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/replace_all_copy.html>
but it's not specifically targeted at replacing single characters, so
may perform worse and/or be more cumbersome to use than something that was.

Also, it only replaces one thing at a time.  If you wanted to replace
many different characters in one pass then you can use
<http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/find_format_copy.html>,
but it will be quite cumbersome.  (And, to add to your complaints: I
wish the docs for that function linked to the docs for the Finder and
Formatter concepts!).

> I nearly went blind (well, not really, but it felt that way) looking at
> http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/reference.html#header.boost.algorithm.string.replace_hpp
> because there's no vertical whitespace. More importantly, there's *no
> description of what any of these algorithms actually do*!

Did you notice that you can click on the function names to get more
detailed info?  This isn't wonderful for finding the algorithm you want,
but there *is* a description of the algorithms, and the quick reference
is there for browsing purposes.

> .... calming down ... 
> 
> Heh, very terse descriptions are in the "Quick Reference":
> http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/quickref.html
> These might be good enough for me, but I always figure I'm going to get
> complete detail from the non-quick reference, and this one is just a
> dump of all the declarations, so I had to go around in a big circle and
> begin writing this documentation complaint before I found it.
> 
> Can this situation be improved?
>