Re: [boost] [string_algo] Documentation Complaint

Subject: Re: [boost] [string_algo] Documentation Complaint
From: Dave Abrahams (dave_at_[hidden])
Date: 2012-11-02 13:13:22

on Thu Nov 01 2012, John Bytheway <jbytheway+boost-AT-gmail.com> wrote:

> 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.

Actually find_format_all_copy.  This took me hours to get right but it's
at least 75% phoenix's fault ;-)

#+begin_src c++
  using namespace boost::phoenix::placeholders;
  using namespace boost::phoenix;
  using namespace boost::phoenix::local_names;
  static const char chars_to_escape[] = "\\/\"\b\f\n\r\t";
  static const char repl_chars[] = "\\/\"bfnrt";

  boost::find_format_all_copy(
      rep,
      boost::token_finder(boost::is_any_of(chars_to_escape)),
      let ( _c = find(boost::as_array(chars_to_escape), arg1[0]) )[
          string("\\") + val(repl_chars)[_c - &chars_to_escape[0]]
      ]
  )
#+end_src

> (And, to add to your complaints: I
> wish the docs for that function linked to the docs for the Finder and
> Formatter concepts!).

Yes!  Everywhere they're mentioned, they should be links!

>> 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?  

Not until long after I wrote the email.

> 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.

Yeah, I eventually figured out how to use the docs.  When we write docs,
we should do more to help people who are working under pressure,
though.  Accessibility is really important.

-- 
Dave Abrahams
BoostPro Computing                  Software Development        Training
http://www.boostpro.com             Clang/LLVM/EDG Compilers  C++  Boost