freddierice / zstr

A C++ header-only ZLib wrapper

A C++ ZLib wrapper

This C++ header-only library enables the use of C++ standard iostreams to access ZLib-compressed streams.

For input access (decompression), the compression format is auto-detected, and multiple concatenated compressed streams are decompressed seamlessly.

For output access (compression), the only parameter exposed by this API is the compression level.

Alternatives to this library include:

• The original ZLib, through its C API. This does not interact nicely with C++ iostreams.
• The GZStream library. This library does not auto-detect input compression, and it cannot wrap streams (only files).
• The Boost IOStreams library. The library does not auto-detect input compression (by default, though that can be easily implemented with filters), and more importantly, it is not a header-only Boost library.

For an example usage, see examples/ztxtpipe.cpp and examples/zc.cpp.

Input Auto-detection

For input access, the library seamlessly auto-detects whether the source stream is compressed or not. The following compressed streams are detected:

• GZip header, when stream starts with 1F 8B. See GZip format.
• ZLib header, when stream starts with 78 01, 78 9C, and 78 DA. See answer here.

If none of these formats are detected, the library assumes the input is not compressed, and it produces a plain copy of the source stream.

Classes

The package provides 6 classes for accessing ZLib streams:

• zstr::istreambuf is the core decompression class. This is constructed from an existing std::streambuf that contains source data. The zstr::istreambuf constructor accepts explicit settings for the internal buffer size (default: 1 MB) and the auto-detection option (default: on). ZLib errors cause exceptions to be thrown.
• zstr::ostreambuf is the core compression class. This is constructed from an existing std::streambuf that contains sink data. The zstr::ostreambuf constructor accepts explicit settings for the internal buffer size (default: 1 MB) and the compression option (default: ZLib default). ZLib errors cause exceptions to be thrown.
• zstr::istream is a wrapper for a zstr::istreambuf that accesses an external std::streambuf. It can be constructed from an existing std::istream (such as std::cin) or std::streambuf.
• zstr::ostream is a wrapper for a zstr::ostreambuf that accesses an external std::streambuf. It can be constructed from an existing std::ostream (such as std::cout) or std::streambuf.
• zstr::ifstream is a wrapper for a zstr::istreambuf that accesses an internal std::ifstream. This can be used to open a file and read decompressed data from it.
• zstr::ofstream is a wrapper for a zstr::ostreambuf that accesses an internal std::ofstream. This can be used to open a file and write compressed data to it.

For all stream objects, the badbit of their expection mask is turned on in order to propagate exceptions.

License

Released under the MIT license.