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
> 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 ;-)
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) )[
string("\\") + val(repl_chars)[_c - &chars_to_escape]
> (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 http://www.boostpro.com Clang/LLVM/EDG Compilers C++ Boost
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk