Boost logo

Boost :

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-29 02:55:53


Jonathan Turkanis wrote:
> David Abrahams wrote:
>> Jonathan Turkanis wrote:
>>> Jonathan Turkanis wrote:
>>>
>>>> Okay, if there are no objections, this is what I'll do.
>>>
>>> This didn't come out quite right -- I know that Daryle has objected.
>>>
>>> I guess I mean: given the fact that the namespace-directory
>>> convention has already been widely violated, if there are no further
>>> objections I'll keep the library in the iostreams directory but use
>>> the io namespace.
>>
>> I didn't see the whole thread, but we ought to try to avoid violating
>> the convention any more than it has been. As Boost grows, this
>> becomes more important. What's wrong with a namespace
>> boost::iostreams? You can always introduce an alias for backward
>> compatibility.
>
> Since you didn't see the whole thread, let me quote myself:
>
> 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.
>> (ii) there currently are not many declarations in the namespace
> "boost::io",
>> so there is not much chance of collisions
>> (iii) it is a more accurate discription of the library, since the core
>> infrastructure is independent of the standard iostreams library and might be
>> used without streams, e.g., for async i/o.
>
> (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. 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++."

> 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; }

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

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

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