Boost logo

Boost :

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 <> 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
> <>
> 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
> <>,
> 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";

      let ( _c = find(boost::as_array(chars_to_escape), arg1[0]) )[
          string("\\") + val(repl_chars)[_c - &chars_to_escape[0]]

> (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
>> 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             Clang/LLVM/EDG Compilers  C++  Boost

Boost list run by bdawes at, gregod at, cpdaniel at, john at