Marc Viala Perso wrote:

...

You should never instantiate a filtering_streamboost::iostreams::dual_use. DualUse is not a real mode, it's a pseudo mode, provided as a convenience for filter implementors. I should put in a STATIC_ASSERT somewhere to prevent this.

[Marc Viala] Oups, sorry but maybe it will be very valuable to add some explanations on the Iostreams documentation to explain this type of restriction (and to add also the STATIC_ASSERT).

I certainly will. It never occurred to me that someone might try to instantiate filtering_stream, but in retrospect I see how it could easily happen.

More generally, my feelings after some days diving into the Iostream documentation, is that adding some use cases or examples would be relevant. Your library is very important/great in my sense and I'm sure that I'm not able to embrace all its features up to now, maybe due to the documentation.

That's a reasonable request. However, I did provide a large amount of documentation, including a tutorial, user guide, and reference. If something is not explained well, it's probably because it seems obvious to me, as the library author. So it would be very helpful for you to point out areas that need more examples.

...

If you need to use an external interface that expects an iostream, you could use a filtering_stream<bidirectional>, together with boost::iostreams::combination (http://tinyurl.com/24zwqy) to producing a bidirectional filter. Depending on your use case, which I don't fully understand, you could combine two compression filters to produce a bidirectional compression filter, or a compression filter with a dummy filter that always throws, to produce a bidirectional stream that at runtime can only be used for unidirectional i/o.

[Marc Viala] Ok, I've implemented your suggestion and its works fine. Just to be sure that I didn't miss anything, do you confirm the implementation hereafter?

class gzfstream: public boost::iostreams::filtering_streamboost::iostreams::bidirectional { public: template <class Path> gzfstream(const Path& file_path, std::ios_base::openmode mode): _file(file_path, mode) { namespace fs = boost::filesystem ; namespace io = boost::iostreams ;

const typename Path::string_type& ext = fs::extension(file_path) ; if( gz_extension_exists(ext) ) push(io::combine(io::gzip_decompressor(), io::gzip_compressor())) ; push(_file) ; }

~gzfstream() { reset() ; }

static bool gz_extension_exists(const std::string& ext) { return ext.size() == 3 && ext == ".gz" ; }

static bool gz_extension_exists(const std::wstring& ext) { return ext.size() == 3 && ext == L".gz" ; }

private: boost::filesystem::fstream _file ; } ;

Looks good. The call to reset() in the destructor is unnecessary, but harmless.

Jonathan thanks again for your library and your very quick help.

np

Best regards,

Marc VIALA

-- Jonathan Turkanis CodeRage http://www.coderage.com

...

That's a reasonable request. However, I did provide a large amount of documentation, including a tutorial, user guide, and reference. If something is not explained well, it's probably because it seems obvious to me, as the library author. So it would be very helpful for you to point out areas that need more examples.

I haven't posted to this list in a while, but I noticed this discussion going on. I actually made use of the boost::iostream stuff a few months back and I can confirm that, while the documentation is plentiful, and good for providing high level conceptual overview, it lacks some pretty important details. What I found most poignantly lacking was documentation of exactly what interfaces filters, source and sinks should implement to be used in the various streams. This was spread out throughout the docs, instead of being summarized in one place. I figured it out eventually, but it felt like a lot of guesswork, and piecing things together from various chunks of documentation and header files. Honestly, it made me reconsider template programming altogether, since it made me realize that the lack of an explicit interface can be seriously frustrating and we don't have a standardized way of documenting implicit interfaces yet. Also, I noticed some interesting behaviors. Calling sync on a stream, didn't seem to call flush on my filter, but the destructor did, causing some interesting side effects. - mike

bounces@lists.boost.org] De la part de Jonathan Turkanis

eg wrote:

...

I think a small section in the tutorial (with a simple example) on implementing symmetric_filters might be useful. I recall this has come up a few times on the list. It is hard for new users to tease out the nuances of the iostreams aspects of symmetric_filters by only looking at the supplied zlib and bzip2 filter implementations.

Michael Linck wrote:

...

I haven't posted to this list in a while, but I noticed this discussion going on. I actually made use of the boost::iostream stuff a few months back and I can confirm that, while the documentation is plentiful, and good for providing high level conceptual overview, it lacks some pretty important details. What I found most poignantly lacking was documentation of exactly what interfaces filters, source and sinks should implement to be used in the various streams. This was spread out throughout the docs, instead of being summarized in one place. I figured it out eventually, but it felt like a lot of guesswork, and piecing things together from various chunks of documentation and header files. Honestly, it made me reconsider template programming altogether, since it made me realize that the lack of an explicit interface can be seriously frustrating and we don't have a standardized way of documenting implicit interfaces yet. Also, I noticed some interesting behaviors. Calling sync on a stream, didn't seem to call flush on my filter, but the destructor did, causing some interesting side effects.

- mike

Thanks, guys. I will try to improve the docs to address these concerns.

[Marc Viala] This is a good new; just for giving a feedback about the documentation, I'm sharing the same feeling that Micheal. Marc