Metadata-Version: 2.4
Name: zlib-zero
Version: 1.0.11
Summary: High-Performance Modernized C++20 zlib Compression Engine
Home-page: https://github.com/Suprath/zlib-zero
Author: Suprath
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: summary

# zlib-zero

**zlib-zero** is a modern C++20, high-performance, memory-optimized, multi-threaded drop-in replacement for standard `zlib` and `zlib-ng`.

Designed for high-throughput cloud microservices, data pipelines, and embedded applications, `zlib-zero` achieves multi-core parallel speedups via adaptive chunking while reducing dynamic decode memory footprint by ~98.5% (from 524 KB down to 8 KB per block) to fit entirely within L1 data cache.

---

## Key Features & Architecture

- **Adaptive Parallel Compression**: Automatically divides streams $\ge 128\text{ KB}$ into 64 KB chunks compressed concurrently across available CPU cores, while producing output fully compliant with standard DEFLATE decoders.
- **L1-Cacheable 2-Tier Decode Table (`DynTable`)**: Replaces flat lookup arrays with a 1,024-entry 10-bit fast-path table (~4 KB) and an overflow vector, reducing RAM usage per stream by ~98.5%.
- **Full RFC Compliance**:
  - **RFC 1950** (zlib framing & Adler-32 trailer)
  - **RFC 1951** (DEFLATE payload & LZ77 back-referencing)
  - **RFC 1952** (GZIP framing, CRC32, ISIZE trailer, `FNAME` / `FEXTRA` flag parsing)
- **C-ABI Drop-In Compatibility**: Implements standard `zlib.h` symbols (`deflateInit`, `deflate`, `deflateEnd`, `inflateInit`, `inflate`, `inflateEnd`, `adler32`, `crc32`). Legacy C applications can link `libz_zero` with zero code changes.
- **SIMD Accelerated Checksums**:
  - **Adler-32**: 4-way SIMD vectorization & division-free modulo arithmetic ($>3.7\text{ GB/s}$).
  - **CRC32**: Hardware ARM64 `crc32x` & x86_64 SSE4.2 / Slice-by-8 fallback ($>10\text{ GB/s}$).
- **C++20 Memory Safety**: Strong type safety, RAII lifetime management, bounds-checked bitwriters, and absolute LZ77 position indexing (`pos`) to prevent stream loops and circular wrap bugs.

---

## Comparison Matrix

| Dimension | Standard `zlib` (madler) | `zlib-ng` | `zlib-zero` |
| :--- | :--- | :--- | :--- |
| **Language Standard** | C89 / C99 | C99 | **Modern C++20** |
| **Multi-Core Parallelism** | Single-threaded | Single-threaded | **Built-in (`ParallelDeflateCompressor`)** |
| **Decode RAM per Stream** | ~524 KB | ~524 KB | **8 KB (L1 Cache Optimized)** |
| **GZIP (RFC 1952) Support** | Built-in | Built-in | **Native (`compress_gzip` / `decompress_gzip`)** |
| **Header-Only Mode** | No | No | **Yes (`modernized_zlib_deflate.hpp`)** |
| **C ABI Drop-In** | Native | Native | **Full Drop-in (`libz_zero`)** |

---

## Installation & Usage

### Option 1: Python (`pip install`)

Install directly via `pip` from PyPI:
```bash
pip install zlib-zero
```

Or install directly from GitHub:
```bash
pip install git+https://github.com/Suprath/zlib-zero.git
```

Usage in Python:
```python
import zlib_zero

# Fast C++20 compression
compressed = zlib_zero.compress_zlib(b"Data to compress " * 1000)
```

### Option 2: CMake Integration (`FetchContent`)
Add directly into your project's `CMakeLists.txt`:
```cmake
include(FetchContent)
FetchContent_Declare(
    zlib_zero
    GIT_REPOSITORY https://github.com/Suprath/zlib-zero.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(zlib_zero)

target_link_libraries(your_target PRIVATE zlib_zero_static)
```

### Option 3: Header-Only Integration (C++20)
Include the header directly in C++ compilation units:
```cpp
#include "modernized_zlib_deflate.hpp"

// Single-call zlib compression
auto compressed = ModernizedZlib::compress_zlib(data.data(), data.size());

// Single-call gzip compression
auto gz_compressed = ModernizedZlib::compress_gzip(data.data(), data.size(), "output.txt");
```

### Option 4: Build Shared & Static Libraries from Source
```bash
git clone https://github.com/Suprath/zlib-zero.git
cd zlib-zero
mkdir build && cd build
cmake ..
make
```
Build outputs:
- `libzlib_zero.a` (Static Library)
- `libz_zero.dylib` / `libz_zero.so` / `zlib_zero.dll` (Shared Drop-In Library)

---

## Running Tests

Verify correctness and standards compliance using the test suite:
```bash
python3 -m unittest discover -s tests -p "test_*.py"
```

---

## License

This project is licensed under the [MIT License](LICENSE).
