Crate zpaq_rs 

Safe Rust bindings for libzpaq — the ZPAQ compression library by Matt Mahoney.

This crate wraps a small C++ shim (zpaq_rs_ffi.cpp) that is compiled at build time via the cc crate. No dynamic libraries are required at runtime; everything is statically linked.

Compression method strings

Most functions accept a method parameter that controls the ZPAQ compression algorithm and level. Recognised values:

Value	Meaning
"1"	Fast (level 1)
"2"	Balanced (level 2)
"3"	Better (level 3)
"4"	Maximum (level 4)
"5"	Ultra (level 5)
"x4.3ci1"	Example explicit method string

Higher numeric levels compress better but are slower and use more memory. Explicit method strings (starting with x, s, i, 0–9) allow fine-grained control; see the zpaq specification for details.

Feature flags

• nojit — Compiles libzpaq with NOJIT defined, disabling the JIT x86 back-end. Required on platforms without a functional x86 JIT (NetBSD, OpenBSD). Enabled automatically by the CI for those targets.

Quick start

use zpaq_rs::{compress_to_vec, decompress_to_vec};

let original = b"hello zpaq";
let compressed = compress_to_vec(original, "1").unwrap();
let restored   = decompress_to_vec(&compressed).unwrap();
assert_eq!(restored, original);

For large data or streaming use cases prefer compress_stream / decompress_stream, which accept any std::io::Read / std::io::Write.

Use compress_size / compress_size_stream when you only need the compressed byte count and not the compressed data itself (avoids allocation).

Performance notes

• Rust LTO applies within Rust crates; C++ LTO applies within the C++ object files. Cross-language inlining (Rust ↔ C++) is toolchain-dependent.
• compress_size / compress_size_stream use a C++-side counting writer to avoid per-byte FFI round-trips and are the fastest way to obtain $C(x)$ for information-theoretic metrics.
• compress_size_parallel / compress_size_stream_parallel split the input into ZPAQ blocks and compress them in parallel, which can be faster on multi-core machines for large inputs.

Structs

ArchiveEntry

One in-archive file entry represented as raw bytes.

CountingWriter

A Write implementation that discards written bytes while counting them.

StreamingCompressor

Byte-at-a-time ZPAQ compressor that reports the running encoded bit count.

ZpaqCommandOutput

Captured output of an embedded zpaq command.

Enums

ZpaqError

Errors returned by this crate.

Functions

archive_append_entries_file

Appends raw byte entries to an archive file path without creating scratch files.

archive_from_entries

Creates a ZPAQ stream archive in memory from raw byte entries.

archive_read_file_bytes

Reads the newest segment whose stored filename matches path from an archive byte slice.

archive_read_file_bytes_from_file

Reads bytes for path from an archive file.

compress_size

Returns the compressed size of input in bytes without materialising the compressed data.

compress_size_parallel

Returns the compressed size of input in bytes using multiple threads.

compress_size_stream

Returns the compressed size of data from reader in bytes without materialising the compressed output.

compress_size_stream_parallel

Returns the compressed size of data from reader in bytes using multiple threads.

compress_stream

Compresses data from reader and writes the ZPAQ archive to writer.

compress_to_vec

Compresses input into a Vec<u8> using the given ZPAQ method string.

decompress_size

Returns the decompressed size of the ZPAQ stream in input without materialising the output.

decompress_size_stream

Returns the decompressed size of the ZPAQ stream from reader without materialising output.

decompress_stream

Decompresses a ZPAQ archive from reader and writes raw data to writer.

decompress_to_vec

Decompresses a complete ZPAQ stream held in input and returns the original data as a Vec<u8>.

random_bytes

Returns len cryptographically strong random bytes.

sha1

Computes the SHA-1 digest of bytes using the libzpaq implementation.

sha256

Computes the SHA-256 digest of bytes using the libzpaq implementation.

stretch_key

Derives a 32-byte key from key32 and salt32 using scrypt.

zpaq_add

Equivalent of zpaq add <archive> <inputs...> -method <method> -threads <threads>.

zpaq_add_archive_size_file

Returns the archive size (in bytes) that zpaq add would produce for a single file on disk.

zpaq_command

Runs an embedded zpaq command in-process and captures its output.

zpaq_extract

Equivalent of zpaq extract <archive> [files...].

zpaq_list

Equivalent of zpaq list <archive> [files...].

Type Aliases

Result

Convenience alias for std::result::Result<T, ZpaqError>.