zstr
zstr copied to clipboard
A C++ header-only ZLib wrapper
-- mode:org; mode:visual-line; coding:utf-8; --
** A C++ ZLib wrapper
[[http://travis-ci.org/mateidavid/zstr][http://travis-ci.org/mateidavid/zstr.svg?branch=master]] [[https://tldrlegal.com/license/mit-license][http://img.shields.io/:license-mit-blue.svg]]
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 [[http://www.zlib.net/][ZLib]], through its [[http://www.zlib.net/manual.html][C API]]. This does not interact nicely with C++ iostreams.
-
The [[http://www.cs.unc.edu/Research/compgeom/gzstream/][GZStream]] library. This library does not auto-detect input compression, and it cannot wrap streams (only files).
-
The [[http://www.boost.org/doc/libs/release/libs/iostreams/][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.
-
The [[https://github.com/tmaklin/bxzstr][bxzstr]] library, if you want support for BZ2 and/or LZMA as well.
For an example usage, see [[examples/ztxtpipe.cpp]] and [[examples/zc.cpp]].
It is compatible with [[https://github.com/richgel999/miniz][miniz]] in case you don't want to get frustrated with zlib e. g. on Windows.
**** 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 [[http://en.wikipedia.org/wiki/Gzip][GZip format]].
-
ZLib header, when stream starts with =78 01=, =78 9C=, and =78 DA=. See [[http://stackoverflow.com/a/17176881][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 exception mask is turned on in order to propagate exceptions.
**** CMake
There are three simple ways to add zstr to a CMake project.
Method 1. Add zstr as a subdirectory and link to the =zstr::zstr= target
#+BEGIN_SRC cmake add_subdirectory(zstr) # defines INTERFACE target 'zstr::zstr'
add_executable(YourTarget main.cpp)
target_link_libraries(YourTarget PRIVATE zstr::zstr)
# if using cmake < 3.13 you may also need the following line
# target_include_directories(YourTarget PRIVATE ${ZSTR_INCLUDE_DIRS})
#+END_SRC
Method 2. Fetch a copy of zstr from an external repository and link to the =zstr::zstr= target
/NOTE: The FetchContent functions shown here were introduced in CMake 3.14/
#+BEGIN_SRC cmake include(FetchContent) FetchContent_Declare(ZStrGitRepo GIT_REPOSITORY "https://github.com/mateidavid/zstr" # can also be a local filesystem path! GIT_TAG "master" ) FetchContent_MakeAvailable(ZStrGitRepo) # defines INTERFACE target 'zstr::zstr'
add_executable(YourTarget main.cpp)
target_link_libraries(YourTarget PRIVATE zstr::zstr)
#+END_SRC
Method 3. Add path containing 'zstr.hpp' to your target's include directories
/NOTE: With this method you're responsible for finding and linking to ZLIB !/
#+BEGIN_SRC cmake find_package(ZLIB REQUIRED) add_executable(YourTarget main.cpp) target_link_libraries(YourTarget PRIVATE ZLIB::ZLIB) target_include_directories(YourTarget PRIVATE /path/to/zstr/src) #+END_SRC
**** Requisites
If you use GCC, you need to deploy at least version 5.1.
**** License
Released under the [[file:LICENSE][MIT license]].