Skip to main content

Crate zxc

Crate zxc 

Source
Expand description

§zxc-compress

Safe Rust bindings to ZXC, a lossless compressor that trades compression speed for maximum decode throughput.

Crates.io Documentation License

§Installation

cargo add zxc-compress

The 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

LevelSpeedRatioUse 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_to and decompress_to for 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.
CStreamProgress
Reports how a single CStream::compress / CStream::end call progressed.
Cctx
Reusable compression context for the Block API.
CompressOptions
Options for compression operations.
DStream
Push decompression stream — the safe Rust counterpart of zxc_dstream.
DStreamProgress
Reports how a single DStream::decompress call progressed.
Dctx
Reusable decompression context for the Block API.
Decoder
Streaming decompressor implementing std::io::Read.
DecompressOptions
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.
FrameInfo
What a frame’s header and footer declare, read by frame_info.
StreamCompressOptions
Options for streaming compression operations.
StreamDecompressOptions
Options for streaming decompression operations.

Enums§

Error
Errors that can occur during ZXC operations.
Level
Compression level presets.
StreamError
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 .zxd file (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_size bytes (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_block for a block of uncompressed_size bytes.
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 data starts with the ZXC file magic word.
dict_get_id
Returns the dictionary ID stored in a .zxd file buffer.
dict_huf
Returns an owned copy of the shared Huffman table stored in a .zxd buffer, or None if the buffer is not a valid .zxd file.
dict_id
Computes the deterministic 32-bit dictionary ID for raw content.
dict_load
Parses a .zxd file buffer, returning owned dictionary content and its ID.
dict_save
Serializes dictionary content and its shared Huffman table to the .zxd file 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 .zxc archive 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 with runtime_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 version zxc-sys was 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.
StreamResult
Result type for streaming operations.