zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
# Streaming API

**License:** **GPL-3.0-only** — see [`../LICENSE`](../LICENSE).

## Why streaming?

Large files (or pipes) should not require loading the entire input into RAM.
ZEX streaming processes **one block at a time** (default 256 KiB).

## Encoder (`StreamEncoder`)

Implements `std::io::Write`.

```rust
use std::io::Write;
use zexc::{StreamEncoder, CompressOptions, CompressionMode};

let out = std::fs::File::create("big.zex")?;
let mut enc = StreamEncoder::new(
    out,
    CompressOptions::default()
        .mode(CompressionMode::Turbo)
        .level(1)
        .block_size(256 * 1024),
);
// from any Read:
std::io::copy(&mut std::fs::File::open("big.bin")?, &mut enc)?;
let file = enc.finish()?; // required!
```

### Lifecycle

1. First write → emit `ZexHeader` (`content_size = unknown`)  
2. Each full `block_size` of input → compress + write one block  
3. `finish()` → last partial block, `End`, CRC32  
4. Drop without `finish()` → **incomplete frame** (don’t do that)

### Not supported

- AEAD encryption (use one-shot `compress` + password)  
- Dependent blocks / sliding window across blocks  

## Decoder (`StreamDecoder`)

Implements `std::io::Read`.

```rust
use std::io::Read;
use zexc::StreamDecoder;

let inp = std::fs::File::open("big.zex")?;
let mut dec = StreamDecoder::new(inp);
let mut out = std::fs::File::create("big.bin")?;
std::io::copy(&mut dec, &mut out)?;
```

### Lifecycle

1. First read → parse header  
2. Pull next block when output buffer empty  
3. On `End` → verify CRC if present  
4. Encrypted frames → error (use one-shot)  

## Pipes

```bash
# compress stdin → stdout
cat data.bin | zex compress - -o - > data.zex   # if CLI supports stdin

# library style
# StreamEncoder::new(stdout, opts) ...
```

CLI currently focuses on files; library streaming is the full pipe solution.

## Memory

| Structure | Approx size |
|-----------|-------------|
| Encoder input buffer | 1 × `block_size` |
| Decoder output buffer | 1 × last block |
| Match tables (encode) | ~`2^hash_log` × 4 bytes per block |

## Errors

Streaming maps `zexc::Error` → `std::io::Error` with `ErrorKind::InvalidData`
or `Other`. Checksum failures surface on the final `read` that hits End.