Examples Overview
The examples/ directory contains standalone, compiling example programs showcasing real-world usage of xz.zig across container compression, integrity checks, filter pipelines, caller buffers, and streaming I/O.
Every example file can be compiled and executed directly via zig build:
zig build run-basic_compression
zig build run-caller_buffer
zig build run-checksum_types
zig build run-filter_chains
zig build run-streaming_pipeline
zig build run-error_handling
zig build run-all-examplesExample Directory
| Example Guide | Source File | Features Covered | Memory Model |
|---|---|---|---|
| Basic Compression | examples/basic_compression.zig | One-shot XZ stream compression and decompression | Dynamic allocation |
| Caller Buffers | examples/caller_buffer.zig | compressInto, decompressInto | Zero-allocation (Stack / fixed buffers) |
| Checksum Types | examples/checksum_types.zig | None, CRC32, CRC64, and SHA-256 block check algorithms | Dynamic allocation |
| Filter Chains | examples/filter_chains.zig | x86 BCJ branch filter and Delta byte-stride filter | Dynamic allocation |
| Streaming Pipeline | examples/streaming_pipeline.zig | compressStream, decompressStream reader/writer pipelines | Bounded-memory streaming |
| Error Handling | examples/error_handling.zig | Corrupt magic, checksum mismatch, buffer bounds | Defensive error verification |
What Each Example Covers
1. Basic Compression
Demonstrates standard heap-allocated XZ file compression and decompression using xz.compress and xz.decompress.
2. Caller-Provided Buffers
Demonstrates zero-allocation operations using pre-allocated stack buffers via xz.compressInto and xz.decompressInto.
3. Checksum Types
Demonstrates configuring block integrity checks across all standard algorithms: None (0B), CRC32 (4B), CRC64 (8B, standard default), and SHA-256 (32B).
4. Filter Chains
Demonstrates pre-processing filters before LZMA2 compression:
- x86 BCJ branch address normalization for native binary executables
- Delta byte-stride filtering for multi-channel audio or numeric tables
5. Streaming Pipeline
Demonstrates incremental processing of unbounded streams using standard reader/writer interfaces with xz.compressStream and xz.decompressStream.
6. Error Handling & Defense
Demonstrates robust handling of invalid container magic, corrupted block payloads (checksum mismatch), and undersized buffers.