<commit_before># -*- 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 expection mask is turned on in order to propagate exceptions.

**** CMake

There are two 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

**** License

Released under the [[file:LICENSE][MIT license]].<commit_msg>Add a third method for including in CMake<commit_after># -*- 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 expection 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

**** License

Released under the [[file:LICENSE][MIT license]].
{'fraction_non_alphanumeric': 0.10334674649131416, 'fraction_numerical': 0.006968299146137992, 'mean_word_length': 4.523035230352304, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6285559', 'n_tokens_mistral': 3140, 'n_tokens_neox': 3017, 'n_words': 1188}