Jonathan Turkanis wrote:
David Abrahams wrote:
Jonathan Turkanis wrote:
I would greatly prefer to use the namespace "boost::io" because:
(i) it is much shorter than "boost::iostreams"; while it is possible to use an alias to shorten it, I'd hate to make users do this when there is a perfectly suitable short name available.
(i) is particularly important, since the documentation will contain a lot of tutorial material in which the namespace qualification can't be omitted, e.g.,
template<typename Sink> void put(Sink& dest, int c) { if (c == '\n') col_no_ = 0; else { if (col_no_ >= line_length_) this->put(dest, '\n'); ++col_no_; } boost::io::put(dest, c); }
Pshaw.
Huzzah!
After a few pages C++ Template Metaprogramming has an example that begins with:
namespace mpl = boost::mpl; // namespace alias
which it then follows with a note that says
"Many examples in this book will use ``mpl::`` to indicate ``boost::mpl::``, but will omit the alias that makes it legal C++."
I know how I would explain the convention; I'm just afraid people won't notice it, and will copy and paste from the examples and find they don't work. It's a bit easier in a printed book, in which there's some expectation that the material will be read from the beginning, than in a heavily hyperlinked web document, where reader are known to skip immediately to somewhere in the middle.
Then use some automated processing to ensure that every one of your examples begins with the single line: namespace io = boost::iostreams; And then your examples will become much more readable: io::foo instead of boost::io::foo. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com