# 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"
```