Boost logo

Boost :

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2004-12-29 13:54:42


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.

>> The occurence of boost::io::put in the above example has to be
>> qualified, since otherwise it will refer to the member function
>> being defined. I worry that having to use a long namespace name or
>> to introduce a namespace alias in a high percentage of the examples
>> will make the documentation harder to follow, and the library harder
>> to learn.
>
> So use the technique described above. And if you really can't stand
> that, do as I suggested originally and introduce the alias in Boost:
>
> namespace boost { namespace iostreams{} namespace io = iostreams; }

Sorry, I didn't read your first post carefully enough. I though you were saying
that users should perform the aliasing.

>> If I have to choose, then, I would much rather use the namespace io
>> and move the library back to boost/io than use the namespace
>> iostreams.
>
> You don't _have_ to choose, but then you could do better than the
> status quo.

Okay, I'll hold off adding iostreams to CVS while I think about it some more.

Jonathan


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk