zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
# ZEX Library API Guide

Package and library crate: **`zexc`** (CLI binary also `zexc`).

**License:** **GPL-3.0-only** (GNU GPLv3 **strict** — not “or later”).  
See [`../LICENSE`](../LICENSE) and [README § License](../README.md#license).  
Using this crate as a dependency in a distributed binary generally requires  
your project to comply with GPLv3-only.

```toml
[dependencies]
zexc = "0.1"   # GPL-3.0-only
```

Import with `use zexc::…`.

## One-shot

```rust
use zexc::{compress, decompress, CompressOptions, CompressionMode};

let opts = CompressOptions::default()
    .mode(CompressionMode::Balanced)
    .level(3)
    .threads(true)
    .checksum(true);

let c = compress(b"hello", &opts)?;
let p = decompress(&c)?;
assert_eq!(p, b"hello");
```

### Profiles

```rust
CompressionMode::Turbo     // speed
CompressionMode::Balanced  // default
CompressionMode::Max       // ratio
```

### Secure caps

```rust
let opts = CompressOptions::default().secure();
```

### Encryption (feature `encryption`)

```rust
use zexc::{EncryptionKey, DecompressOptions, decompress_with_options};

let opts = CompressOptions::default()
    .encrypt(EncryptionKey::Password("secret".into()));
// or EncryptionKey::parse_cli("0124...ff") for 64 hex chars

let c = compress(data, &opts)?;

let d = decompress_with_options(&c, &DecompressOptions {
    encryption: Some(EncryptionKey::Password("secret".into())),
    ..Default::default()
})?;
```

## Streaming

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

// encode
let mut enc = StreamEncoder::new(writer, CompressOptions::default());
enc.write_all(chunk)?;
let writer = enc.finish()?;

// decode
let mut dec = StreamDecoder::new(reader);
dec.read_exact(&mut buf)?;
```

See [STREAMING.md](STREAMING.md).

## Inspection

```rust
use zexc::{ZexHeader, FrameReader};

let h = ZexHeader::from_bytes(&file_prefix)?;
println!("encrypted={} level={}", h.is_encrypted(), h.level);

let info = FrameReader::new(std::fs::File::open("a.zex")?).info()?;
println!("blocks={}", info.block_count);
```

## Dictionary history

Dictionary bytes are **prefix history** for the match finder (Zstd-style).
They are not embedded in the frame — both sides must use the same blob.

```rust
use zexc::{
    compress_with_dict, decompress_with_options,
    CompressOptions, DecompressOptions, Dictionary,
};

let dict = Dictionary::train_simple(&samples, 4096)?;
// or Dictionary::from_bytes(bytes)?

let c = compress_with_dict(msg, &opts, dict.clone())?;

let p = decompress_with_options(&c, &DecompressOptions {
    dictionary: Some(dict),
    ..Default::default()
})?;
```

Stream path: `CompressOptions::dictionary(...)` on `StreamEncoder`, and
`StreamDecoder::new(r).dictionary(dict)`.

## Errors

```rust
use zexc::{Error, Result};

match compress(data, &opts) {
    Ok(c) => { /* ... */ }
    Err(Error::ChecksumMismatch { expected, actual }) => { /* ... */ }
    Err(e) => eprintln!("{e}"),
}
```

## Feature flags

```toml
zex-compressor = { version = "0.1", default-features = false, features = ["std", "simd"] }
# disable encryption:
# features = ["std", "simd"]  # omit "encryption"
```