Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mateidavid/zstr

A C++ header-only ZLib wrapper
https://github.com/mateidavid/zstr

Last synced: 3 months ago
JSON representation

A C++ header-only ZLib wrapper

Awesome Lists containing this project

README 

        
# -*- 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 and want to use the `fs.open()` function, you need to deploy at least GCC version 5.1.



**** License



Released under the [[file:LICENSE][MIT license]].