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.
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
, and78 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.
The package provides 6 classes for accessing ZLib streams:
zstr::istreambuf
is the core decompression class. This is constructed from an existingstd::streambuf
that contains source data. Thezstr::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 existingstd::streambuf
that contains sink data. Thezstr::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 azstr::istreambuf
that accesses an externalstd::streambuf
. It can be constructed from an existingstd::istream
(such asstd::cin
) orstd::streambuf
.zstr::ostream
is a wrapper for azstr::ostreambuf
that accesses an externalstd::streambuf
. It can be constructed from an existingstd::ostream
(such asstd::cout
) orstd::streambuf
.zstr::ifstream
is a wrapper for azstr::istreambuf
that accesses an internalstd::ifstream
. This can be used to open a file and read decompressed data from it.zstr::ofstream
is a wrapper for azstr::ostreambuf
that accesses an internalstd::ofstream
. This can be used to open a file and write compressed data to it.
All stream objects the badbit
of the expection mask is turned on in order to propagate exceptions.