Expand description
§zxc-compress
Safe Rust bindings to ZXC, a lossless compressor that trades compression speed for maximum decode throughput.
§Installation
cargo add zxc-compressThe package is zxc-compress, but the library it exports is named zxc:
import it with use zxc::.... The C library is vendored and built by
zxc-compress-sys; a C compiler
is the only requirement.
§Quick Start
use zxc::{compress, decompress, Level};
fn main() -> Result<(), zxc::Error> {
let data = b"Hello, ZXC! This is some data to compress.";
// Compress (no checksum for maximum speed)
let compressed = compress(data, Level::Default, None)?;
println!("Compressed {} -> {} bytes", data.len(), compressed.len());
// Decompress
let decompressed = decompress(&compressed)?;
assert_eq!(&decompressed[..], &data[..]);
Ok(())
}§Compression Levels
| Level | Speed | Ratio | Use Case |
|---|---|---|---|
Level::Fastest | ★★★★★ | ★★☆☆☆ | Real-time, gaming |
Level::Fast | ★★★★☆ | ★★★☆☆ | Network, streaming |
Level::Default | ★★★☆☆ | ★★★★☆ | General purpose |
Level::Balanced | ★★☆☆☆ | ★★★★☆ | Archives |
Level::Compact | ★☆☆☆☆ | ★★★★★ | Storage, firmware |
Level::Density | ★☆☆☆☆ | ★★★★★ | High density (Huffman literals + optimal parser) |
Level::Ultra | ★☆☆☆☆ | ★★★★★ | Maximum density (Huffman literals + tokens, deep parse) |
§Features
- Fast decompression: Optimized for read-heavy workloads
- 7 compression levels: Trade off speed vs ratio
- Optional checksums: Not written by default; verified by default when an archive carries them
- File streaming: Multi-threaded compression/decompression for large files
- Zero-allocation API:
compress_toanddecompress_tofor buffer reuse - Pure Rust API: Safe, idiomatic interface over the C library
Streaming (CStream/DStream), std::io adapters (Encoder/Decoder),
seekable archives, dictionaries and block-level contexts are covered in the
API documentation.
§Advanced Usage
§Pre-allocated Buffers
use zxc::{compress_bound, compress_to, decompress_to, CompressOptions, DecompressOptions};
fn main() -> Result<(), zxc::Error> {
let data = b"Hello, world!";
// Compression
let mut output = vec![0u8; compress_bound(data.len())];
let size = compress_to(data, &mut output, &CompressOptions::default())?;
output.truncate(size);
// Decompression
let mut decompressed = vec![0u8; data.len()];
decompress_to(&output, &mut decompressed, &DecompressOptions::default())?;
assert_eq!(&decompressed[..], &data[..]);
Ok(())
}§Checksums
Compression writes none unless asked. Decompression verifies them whenever the archive carries them, unless told not to. The block API is the exception: a bare block cannot say whether it carries one, so verification there is off unless requested, and both sides must agree.
use zxc::{compress_with_options, decompress, decompress_with_options, CompressOptions, DecompressOptions, Level};
fn main() -> Result<(), zxc::Error> {
let data = b"Hello, world!";
let opts = CompressOptions::with_level(Level::Fastest).with_checksum();
let compressed = compress_with_options(data, &opts)?;
// Verified.
assert_eq!(&decompress(&compressed)?[..], &data[..]);
// Not verified.
let decompressed = decompress_with_options(&compressed, &DecompressOptions::skip_checksum())?;
assert_eq!(&decompressed[..], &data[..]);
Ok(())
}§Query Decompressed Size
use zxc::{compress, decompress_to, decompressed_size, DecompressOptions, Level};
fn main() -> Result<(), zxc::Error> {
let compressed = compress(b"Hello, world!", Level::Default, None)?;
let size = decompressed_size(&compressed).expect("valid ZXC frame");
let mut buffer = vec![0u8; size as usize];
decompress_to(&compressed, &mut buffer, &DecompressOptions::default())?;
Ok(())
}§License
BSD-3-Clause - see LICENSE for details.
Re-exports§
pub use seekable::Seekable;pub use seekable::seek_table_size;pub use seekable::write_seek_table;
Modules§
- seekable
- Seekable API: random-access decompression (single-threaded).
Structs§
- CStream
- Push compression stream — the safe Rust counterpart of
zxc_cstream. - CStream
Progress - Reports how a single
CStream::compress/CStream::endcall progressed. - Cctx
- Reusable compression context for the Block API.
- Compress
Options - Options for compression operations.
- DStream
- Push decompression stream — the safe Rust counterpart of
zxc_dstream. - DStream
Progress - Reports how a single
DStream::decompresscall progressed. - Dctx
- Reusable decompression context for the Block API.
- Decoder
- Streaming decompressor implementing
std::io::Read. - Decompress
Options - Options for decompression operations.
- Dictionary
- A trained dictionary: the LZ-window content and its shared literal Huffman table, bundled as one object so callers never juggle the pair by hand.
- Encoder
- Streaming compressor implementing
std::io::Write. - Frame
Info - What a frame’s header and footer declare, read by
frame_info. - Stream
Compress Options - Options for streaming compression operations.
- Stream
Decompress Options - Options for streaming decompression operations.
Enums§
- Error
- Errors that can occur during ZXC operations.
- Level
- Compression level presets.
- Stream
Error - Errors specific to the streaming file API.
Constants§
- ZXC_
DICT_ SIZE_ MAX - Maximum dictionary content size in bytes (65535).
- ZXC_
ERROR_ BAD_ BLOCK_ SIZE - Invalid block size
- ZXC_
ERROR_ BAD_ BLOCK_ TYPE - Unknown or unexpected block type
- ZXC_
ERROR_ BAD_ CHECKSUM - A block’s decoded bytes fail its checksum, or the archive digest mismatches
- ZXC_
ERROR_ BAD_ HEADER - Corrupted or invalid header (checksum mismatch)
- ZXC_
ERROR_ BAD_ MAGIC - Invalid magic word in file header
- ZXC_
ERROR_ BAD_ OFFSET - Invalid match offset during decompression
- ZXC_
ERROR_ BAD_ VERSION - Unsupported file format version
- ZXC_
ERROR_ CORRUPT_ DATA - Corrupted compressed data
- ZXC_
ERROR_ DST_ TOO_ SMALL - Destination buffer too small
- ZXC_
ERROR_ IO - Read/write/seek failure on file
- ZXC_
ERROR_ MEMORY - Memory allocation failure
- ZXC_
ERROR_ NULL_ INPUT - Required input pointer is NULL
- ZXC_
ERROR_ OVERFLOW - Buffer overflow detected during processing
- ZXC_
ERROR_ SRC_ TOO_ SMALL - Source buffer too small or truncated input
- ZXC_
HUF_ TABLE_ SIZE - Size in bytes of the shared literal Huffman table carried by a
.zxdfile (packed 4-bit code lengths for 256 symbols). - ZXC_
LEVEL_ BALANCED - Good ratio, good decode speed
- ZXC_
LEVEL_ COMPACT - High density. Best for storage/firmware/assets.
- ZXC_
LEVEL_ DEFAULT - Recommended: ratio > LZ4, decode speed > LZ4
- ZXC_
LEVEL_ DENSITY - High density: Huffman-coded literals on top of COMPACT, price-based optimal LZ77 parser.
- ZXC_
LEVEL_ FAST - Fast compression, good for real-time applications
- ZXC_
LEVEL_ FASTEST - Fastest compression, best for real-time applications
- ZXC_
LEVEL_ ULTRA - Maximum density: Huffman-coded literals and sequence tokens, deep parse. Slowest compression, best ratio (level 7 / ULTRA).
- ZXC_OK
- Success (no error)
- ZXC_
VERSION_ MAJOR - ZXC_
VERSION_ MINOR - ZXC_
VERSION_ PATCH
Functions§
- compress
- Compresses data with the specified level.
- compress_
block_ bound - Returns the maximum compressed size for a single block of
input_sizebytes (no file framing). - compress_
bound - Returns the maximum compressed size for an input of the given size.
- compress_
file - Compresses a file using multi-threaded streaming.
- compress_
file_ with_ options - Compresses a file using multi-threaded streaming, honouring
opts. - compress_
to - Compresses data into a pre-allocated buffer.
- compress_
with_ options - Compresses data with full options control.
- decompress
- Decompresses ZXC-compressed data.
- decompress_
block_ bound - Returns the minimum destination buffer size required by
Dctx::decompress_blockfor a block ofuncompressed_sizebytes. - decompress_
file - Decompresses a file using multi-threaded streaming.
- decompress_
file_ with_ options - Decompresses a file using multi-threaded streaming, honouring
opts. - decompress_
to - Decompresses data into a pre-allocated buffer.
- decompress_
with_ options - Decompresses data with full options control.
- decompressed_
size - Returns the original uncompressed size from compressed data, summed over concatenated archives.
- default_
level - Returns the default compression level (currently
3). - detect_
zxc - Reports whether
datastarts with the ZXC file magic word. - dict_
get_ id - Returns the dictionary ID stored in a
.zxdfile buffer. - dict_
huf - Returns an owned copy of the shared Huffman table stored in a
.zxdbuffer, orNoneif the buffer is not a valid.zxdfile. - dict_id
- Computes the deterministic 32-bit dictionary ID for raw content.
- dict_
load - Parses a
.zxdfile buffer, returning owned dictionary content and its ID. - dict_
save - Serializes dictionary content and its shared Huffman table to the
.zxdfile format. - file_
decompressed_ size - Returns the decompressed size stored in a compressed file.
- frame_
info - Reads a frame’s header and footer, without decoding.
- get_
dict_ id - Returns the dictionary ID a ZXC
.zxcarchive requires. - max_
level - Returns the maximum supported compression level (currently
7). - min_
level - Returns the minimum supported compression level (currently
1). - runtime_
codename - Returns the release code name reported by the linked native library
(e.g.
"Hydrogen"). Informational only; compare versions withruntime_version. - runtime_
version - Returns the version string reported by the linked native library
(e.g.
"0.10.0"). Useful for verifying that the dynamically-linked libzxc matches the versionzxc-syswas built against. - train_
dict - Trains a dictionary from a corpus of samples.
- train_
dict_ huf - Trains the shared literal Huffman table for an already-trained dictionary.
- version
- Returns the library version as a tuple (major, minor, patch).
- version_
string - Returns the library version as a string.
Type Aliases§
- Result
- Result type for ZXC operations.
- Stream
Result - Result type for streaming operations.