David Abrahams wrote:

"Jonathan Turkanis" <technews@kangaroologic.com> writes:

...

Here are the candidates:

1. streambuf_facade / stream_facade 2. generic_streambuf / generic_stream 3. streambuf / stream 4. xstreambuf / xstream 5. device_streambuf / device_stream 6. devbuf / devstream

Please let me know what you think.

The even numbered choices look bad to me.

Sort of like Beethoven's symphonies, I guess :-P

I don't know enough about the library to judge about the others.

Thanks for your input. Jonathan

Gennadiy Rozental wrote:

...

Hi,

I'm trying to pick good names for the fundamental iostreams components streambuf_facade and stream_facade:

template<typename Device ... > class streambuf_facade : public basic_streambuf< > { // Peform i/o using an instance of Device };

template<typename Device ... > class stream_facade : public basic_[i][o]stream< > { // Peform i/o using an instance of Device };

Here are the candidates:

1. streambuf_facade / stream_facade

If this components indeed follow Facade pattern this would be my choice of name.

Thanks. Strictly speaking it's a facade, but it would probably be better characterized as an adapter. I don't like streambuf_adapter, however, because it's not clear from the name whether the adapter produces a streambuf or turns a streambuf into something else. I think what makes me most reluctant to use "facade" or "adapter" in this case is that the classes being turned into streambufs are typically designed for the sole purpose of being adapted in this way. I usually think of facades or adapters as proving a new interface for some useful pre-existing facility.

Gennadiy

Jonathan

Arkadiy Vertleyb wrote:

"Jonathan Turkanis" wrote

...

Here are the candidates:

1. streambuf_facade / stream_facade 2. generic_streambuf / generic_stream 3. streambuf / stream 4. xstreambuf / xstream

I don't like any of those. I don't think they tell much about what they name. OTOH, I may lack some background. I don't even understand what rationale for such a name as xstreambuf/xstream is :-(

It was supposed to mean "extended."

...

5. device_streambuf / device_stream 6. devbuf / devstream

These both are much better, IMO. Being a minimalist, I would probably prefer number 6.

Thanks. Rob Stewart pointed out that dev is sometimes an abbreviation for "development" or "developer." The reason I'm not too excited about "device_streambuf" and "device_stream" is that they're hard to pronounce without running the final consonant of "device" into the initial consonant of "stream" or "streambuf."

Regards, Arkadiy

Jonathan

Scott Woods wrote:

----- Original Message ----- From: "Jonathan Turkanis" <technews@kangaroologic.com> To: <boost@lists.boost.org> Sent: Wednesday, July 13, 2005 9:08 AM Subject: Re: [boost] [iostreams] please vote on template names

[snip]

I have no understanding of the work your facades/adapters/? may be doing. In pure ignorance;

...

Rob Stewart pointed out that dev is sometimes an abbreviation for "development" or "developer."

The reason I'm not too excited about "device_streambuf" and

"device_stream" is

...

that they're hard to pronounce without running the final consonant of "device" into the initial consonant of "stream" or "streambuf."

They read better than "dev".

Thanks for your input. I've eliminated te "dev" variants, but am still considering the others. Jonathan

Larry Evans wrote:

On 07/11/2005 05:02 PM, Jonathan Turkanis wrote: [snip]

...

Here are the candidates:

1. streambuf_facade / stream_facade 2. generic_streambuf / generic_stream 3. streambuf / stream 4. xstreambuf / xstream 5. device_streambuf / device_stream 6. devbuf / devstream

Jonathan, I just looked at:

libs/iostreams/doc/index.html

where, in section with title:

Policy-Based Streams and Stream Buffers

there's:

streambuf_facade and stream_facade implement standard stream buffers and streams which perform i/o by delegating to a contained Filter or Device.

so I was thinking maybe:

{stream,streambuf}_delegator

would be better, or at least it would reflect the above wording in the documentation ;)

Reflecting that wording isn't a high priority. ;-) In fact, I think the wording is a bit awkward. (Also, there's already a template delegating_streambuf which implements a streambuf that delegates to a second streambuf.) Jonathan

Larry Evans wrote:

I suggest:

device_filter_{streambuf,stream}

instead of:

device_{streambuf,stream}

because the following:

libs/iostreams/doc/policy_based_streams.html

contains:

which performs i/o by delegating to a contained instance of a policy class. The policy class must model one of the various Filter or Device concepts.

Actually, I've decided not to document the fact that you can specify a filter here rather than a device; it's only needed by the implementation. Thanks for pointing out that passage; I've fixed it locally. Jonathan

Paul A Bristow wrote:

...

...

5. device_streambuf / device_stream

This is reasonably meaningful given the use of a Device and serves to distinguish the names from those in std.

Without any enthusiam I vote for this one. But I wish I could think of something better.

Okay, thanks. Jonathan

On Tue, Jul 12, 2005 at 03:13:07PM -0600, Jonathan Turkanis wrote:

...

The "x" was to convey "extended," not "eXperimental."

I kinda liked the 'x' versions, but not enough to express a preference.

...

...

5. device_streambuf / device_stream

This is reasonably meaningful given the use of a Device and serves to distinguish the names from those in std.

They're hard to pronounce properly, though. I just realized that this is why I don't like them.

Yeah, it's too close to "dev ice cream" which is just silly :-)

But speaking of "buf/stream," how about using "buf" and "stream"? E.g.,

typedef stream<file> filestream; typedef buf<file> filebuf;

typedef stream<array> arraystream; typedef buf<array> arraybuf;

Not only are these better than the other choices, I think these are actually quite good names. My only reservation is that a streambuf doesn't necessarily do any buffering (that's true for std::streambufs, anyway, I assume it's the case for yours as well), so taking the "buf" part of the name "streambuf" emphasises the misleading part of the name, but that's not a big deal. jon

Jonathan Wakely wrote:

...

But speaking of "buf/stream," how about using "buf" and "stream"? E.g.,

typedef stream<file> filestream; typedef buf<file> filebuf;

typedef stream<array> arraystream; typedef buf<array> arraybuf;

Not only are these better than the other choices, I think these are actually quite good names.

Thanks.

My only reservation is that a streambuf doesn't necessarily do any buffering (that's true for std::streambufs, anyway, I assume it's the case for yours as well),

right.

so taking the "buf" part of the name "streambuf" emphasises the misleading part of the name, but that's not a big deal.

Good point, but I think it's a shortcoming of the standard library's naming conventions; e.g., basic_stringbuf performs unbuffered i/o.

jon

Jonathan

| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of Jeff Flinn | Sent: 13 July 2005 13:47 | To: boost@lists.boost.org | Subject: Re: [boost] [iostreams] please vote on template names | | | "Jonathan Turkanis" <technews@kangaroologic.com> wrote in message | news:db1bn4$gad$1@sea.gmane.org... | > Rob Stewart wrote: | >> From: "Jonathan Turkanis" <technews@kangaroologic.com> | > | > But speaking of "buf/stream," how about using "buf" and | "stream"? E.g., | > | > typedef stream<file> filestream; | > typedef buf<file> filebuf; | > | > typedef stream<array> arraystream; | > typedef buf<array> arraybuf; | | I like these the best so far, particularly 'stream'. Thinking | about seeing | 'buf' appearing in code some time in the future without all | of the context | in this thread is a little unsettling. Perhaps 'buf' should be | un-abbreviated to 'buffer'? Although this fly's in the face | of JW's thoughts | on the non-buffer nature of streambuf. | | After a quick re-read of your docs ( from a few months ago ), | this comes to | mind: | | resource_stream | resource_streambuf | | based on: | | <quotation> | Concepts | The fundamental building blocks of the library are the | concepts of a Source, | which provides read access to a sequence of characters, a Sink, which | provides write access to a sequence of characters, an | InputFilter, which | filters input read from a Source, and an OutputFilter, which | filters output | written to a Sink. Sources, Sinks and their refinements are called | resources. InputFilters, OutputFilters and their refinements | are called | filters. | </quotation> Would this suggest source_stream source_streambuf rather than REsource? Paul Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539 561830 +44 7714 330204 mailto: pbristow@hetp.u-net.com

David Abrahams wrote:

"Jeff Flinn" writes:

...

"Jonathan Turkanis" wrote in message

...

...

But speaking of "buf/stream," how about using "buf" and "stream"? E.g.,

...

I like these the best so far, particularly 'stream'. Thinking about seeing 'buf' appearing in code some time in the future without all of the context in this thread is a little unsettling. Perhaps 'buf' should be un-abbreviated to 'buffer'? Although this fly's in the face of JW's thoughts on the non-buffer nature of streambuf.

Sounds like stream<X> and streambuf<X> might be a good choice.

I'm afraid that readers of library documentation and user code will get boost::iostreams::streambuf and std::streambuf mixed up. Otherwise, it would be my first choice. Jonathan

David Abrahams wrote:

"Jonathan Turkanis" writes:

...

David Abrahams wrote:

...

...

Sounds like stream<X> and streambuf<X> might be a good choice.

I'm afraid that readers of library documentation and user code will get boost::iostreams::streambuf and std::streambuf mixed up. Otherwise, it would be my first choice.

No problem; just use qualification. you can also tell people there's a namespace alias in place for boost::iostreams

namespace io = boost::iostreams;

Okay, I've run out of time for renaming and it looks like this is the safest choice -- meaning I'm sure I won't end up hating these names, even if they cause some confusion. Thanks again. Jonathan

Jeff Flinn wrote:

"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:db1bn4$gad$1@sea.gmane.org...

...

Rob Stewart wrote:

...

From: "Jonathan Turkanis" <technews@kangaroologic.com>

But speaking of "buf/stream," how about using "buf" and "stream"? E.g.,

typedef stream<file> filestream; typedef buf<file> filebuf;

typedef stream<array> arraystream; typedef buf<array> arraybuf;

I like these the best so far, particularly 'stream'. Thinking about seeing 'buf' appearing in code some time in the future without all of the context in this thread is a little unsettling.

This is the only reason I'm still undecided.

Perhaps 'buf' should be un-abbreviated to 'buffer'?

There's already a pretty useful, but undocumented template called buffer. It implements ... a buffer. ;-)

Although this fly's in the face of JW's thoughts on the non-buffer nature of streambuf.

After a quick re-read of your docs ( from a few months ago ), this comes to mind:

resource_stream resource_streambuf

Unfortunately nobody but me liked the term "resource," so I switched to "device." Thanks for taking the time to write.

Jeff Flinn

Jonathan

From: "Jonathan Turkanis" <technews@kangaroologic.com>

Sylvester-Bradley, Gareth wrote (in private email):

...

Jonathan Turkanis wrote:

...

I guess streambuf_wrapper / stream_wrapper suffer from the same lack of to/from clarity as streambuf_adapter / stream_adapter?

To me they sound unambiguous, but with the wrong meaning.

I'm not sure which you were saying had the wrong meaning, but I thought about streambuf_adapter/stream_adapter, and I think those are great names. The class templates are adapting a Device type to be another type--a streambuf or stream--like those in namespace std.

...

Can I offer another suggestion, taking inspiration from several other Boost libraries, like enable_if, result_of, etc?

How about streambuf_from / stream_from (or _with, _of, _on, _over, ...)?

Iostreams also uses this type of name: category_of, char_type_of and mode_of.

streambuf_from / stream_from look pretty good when they are specialized:

streambuf_from<array> stream_from<socket>

That sounds a little weird, but it isn't terrible. Oh, I just came back to this part because I realized what didn't sound right: these are class templates, not function templates, yet "from" suggests a return value to me.

but I'm afraid they will look funny in documentation. E.g.,

The fundamental component provided by the Iostreams library is the class template streambuf_from, a derived class of std::basic_streambuf which performs i/o by delegating to a contained Device.

There are lots of names that don't flow well in a description like that. I don't think that should interfere too much with name selection. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;