zlib-bitexact-rs 0.131.1

Bit-exact pure-Rust port of stock zlib 1.3.1's deflate (byte-identical raw DEFLATE output).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# zlib-bitexact-rs

[![crates.io](https://img.shields.io/crates/v/zlib-bitexact-rs.svg)](https://crates.io/crates/zlib-bitexact-rs)
[![docs.rs](https://img.shields.io/docsrs/zlib-bitexact-rs)](https://docs.rs/zlib-bitexact-rs)
[![CI](https://github.com/danifunker/zlib-bitexact-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/danifunker/zlib-bitexact-rs/actions/workflows/ci.yml)

A pure-Rust, **bit-exact** port of **stock zlib 1.3.1's deflate**. Its raw DEFLATE output is
**byte-identical** to the C `deflate()` for the configuration used by MAME's CHD codec:
`deflateInit2(Z_BEST_COMPRESSION, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY)` + one
`deflate(Z_FINISH)`.

> ⚠️ This is **not** `zlib-rs` / `miniz_oxide` / `flate2`. Those are valid DEFLATE encoders, but
> their compressed *bytes* differ from stock zlib (zlib-ng-style improvements). This crate
> reproduces stock zlib **1.3.1** exactly — needed by consumers that must recreate the precise
> bytes zlib/chdman produce (e.g. [`chd-rs`](https://github.com/SnowflakePowered/chd-rs)
> reproducing MAME CHD hunks bit-for-bit).

Encode only — decode is unambiguous, so any zlib-compatible inflater reads this crate's output.

## Status

✅ **Published on [crates.io](https://crates.io/crates/zlib-bitexact-rs) (v0.131.1) — byte-exact.**
`deflate_raw` reproduces zlib 1.3.1 byte-for-byte. A pure-Rust golden-vector test (`cargo test`,
no C, no deps) guards every code path:

| Class | Cases |
|---|---|
| Tiny / boundary | empty, 1–8 bytes, `MIN_MATCH`/`MAX_MATCH`/`MIN_LOOKAHEAD` edges |
| Highly compressible | long zero/0xff runs, periodic patterns, byte ramps |
| Incompressible | xorshift random → stored blocks |
| Block type | dynamic / static / stored, plus multi-regime switches |
| Multi-block | inputs > 16383 symbols (forces `lit_bufsize` flush) |
| Window sliding | inputs > 64 KiB (`fill_window` slide + `slide_hash`) |
| Adversarial | skewed/geometric/Fibonacci frequencies (bit-length-overflow path) |
| CHD hunk sizes | 4096; 2448-multiples (CD subcode); 19584 |

The golden vectors in `tests/vectors/` were captured from stock zlib 1.3.1; to re-verify against a
live C oracle (or regenerate them), follow
[`docs/verifying-against-zlib.md`](docs/verifying-against-zlib.md). See [`ROADMAP.md`](ROADMAP.md)
for the build plan and [`CLAUDE.md`](CLAUDE.md) for the architecture and bit-exactness hazards.

## Usage

```rust
let data = b"the quick brown fox jumps over the lazy dog";
let raw = zlib_bitexact_rs::deflate_raw(data);
// == zlib 1.3.1 deflateInit2(9, Z_DEFLATED, -15, 8, Z_DEFAULT_STRATEGY) + deflate(Z_FINISH)
```

Pure Rust, `#![forbid(unsafe_code)]`, zero runtime dependencies.

## Versioning

`0.<zlib-digits>.<patch>` — the minor tracks the upstream zlib release this crate is bit-exact
with (`1.3.1` → `0.131.x`). zlib's deflate output is version-sensitive; this crate targets 1.3.1
exactly (the version MAME 0.288 bundles).

## License

BSD-3-Clause. A port of stock zlib 1.3.1, which is under the permissive zlib license
(© Jean-loup Gailly & Mark Adler) — see [`LICENSE`](LICENSE).