Compression API

This page documents all compression-related functions in compressionz.

compress

Compress data using the specified codec with default options.

pub fn compress(
    codec: Codec,
    input: []const u8,
    allocator: std.mem.Allocator,
) Error![]u8

Parameters

Parameter	Type	Description
codec	Codec	Compression algorithm to use
input	[]const u8	Data to compress
allocator	std.mem.Allocator	Allocator for output buffer

Returns

• []u8 — Compressed data. Caller owns and must free with allocator.
• Error — On failure (see Error Handling)

Example

const cz = @import("compressionz");

const compressed = try cz.compress(.zstd, data, allocator);
defer allocator.free(compressed);

---

compressWithOptions

Compress data with custom options.

pub fn compressWithOptions(
    codec: Codec,
    input: []const u8,
    allocator: std.mem.Allocator,
    options: CompressOptions,
) Error![]u8

Parameters

Parameter	Type	Description
codec	Codec	Compression algorithm
input	[]const u8	Data to compress
allocator	std.mem.Allocator	Allocator for output
options	CompressOptions	Compression options

CompressOptions

pub const CompressOptions = struct {
    /// Compression level
    level: Level = .default,

    /// Include content size in header (LZ4 frame)
    include_size: bool = true,

    /// Include checksum (LZ4 frame)
    include_checksum: bool = true,

    /// Dictionary for better small-data compression
    dictionary: ?[]const u8 = null,
};

Example

// Maximum compression
const compressed = try cz.compressWithOptions(.zstd, data, allocator, .{
    .level = .best,
});

// Fast compression
const fast = try cz.compressWithOptions(.zstd, data, allocator, .{
    .level = .fast,
});

// With dictionary
const dict_compressed = try cz.compressWithOptions(.zstd, data, allocator, .{
    .dictionary = my_dictionary,
});

---

compressInto

Compress into a pre-allocated buffer (zero-copy).

pub fn compressInto(
    codec: Codec,
    input: []const u8,
    output: []u8,
    options: CompressOptions,
) Error![]u8

Parameters

Parameter	Type	Description
codec	Codec	Compression algorithm
input	[]const u8	Data to compress
output	[]u8	Pre-allocated output buffer
options	CompressOptions	Compression options

Returns

• []u8 — Slice of output containing compressed data
• error.OutputTooSmall — If buffer is too small

Supported Codecs

Only available for: .lz4, .lz4_raw, .snappy

Example

var buffer: [65536]u8 = undefined;

const compressed = try cz.compressInto(.lz4, data, &buffer, .{});
// compressed is a slice of buffer, no allocation needed

---

maxCompressedSize

Calculate maximum possible compressed size for buffer allocation.

pub fn maxCompressedSize(codec: Codec, input_size: usize) usize

Parameters

Parameter	Type	Description
codec	Codec	Compression algorithm
input_size	usize	Size of uncompressed data

Returns

Maximum possible size of compressed output. Actual compressed size will usually be smaller.

Example

const max_size = cz.maxCompressedSize(.lz4, data.len);
const buffer = try allocator.alloc(u8, max_size);
defer allocator.free(buffer);

const compressed = try cz.compressInto(.lz4, data, buffer, .{});

---

Compression Levels

pub const Level = enum {
    fastest,  // Maximum speed, lower ratio
    fast,     // Good speed, good ratio
    default,  // Balanced (recommended)
    better,   // Better ratio, slower
    best,     // Maximum ratio, slowest
};

Level Comparison (Zstd, 1 MB data)

Level	Compress	Decompress	Ratio
fastest	12+ GB/s	11+ GB/s	99.8%
fast	12 GB/s	11+ GB/s	99.9%
default	12 GB/s	11+ GB/s	99.9%
better	5 GB/s	11+ GB/s	99.9%
best	1.3 GB/s	12 GB/s	99.9%

Recommendations

• Use default for most cases
• Use fast for real-time applications
• Use best only for archival or static content

---

Direct Codec Access

For fine-grained control, access codec implementations directly:

LZ4

const cz = @import("compressionz");

// LZ4 frame with all options
const compressed = try cz.lz4.frame.compress(data, allocator, .{
    .level = .fast,
    .content_checksum = true,
    .block_checksum = false,
    .content_size = data.len,
    .block_size = .max64KB,
});

// LZ4 raw block (maximum speed)
const block = try cz.lz4.block.compress(data, allocator);

Snappy

const compressed = try cz.snappy.compress(data, allocator);

Zstd

// With level
const compressed = try cz.zstd.compress(data, allocator, .fast);

// With dictionary
const dict_compressed = try cz.zstd.compressWithDict(data, allocator, .default, dictionary);

Gzip

const compressed = try cz.gzip.compress(data, allocator, .default);

Brotli

const compressed = try cz.brotli.compress(data, allocator, .best);

---

Codec Enum

pub const Codec = enum {
    lz4,      // LZ4 frame format
    lz4_raw,  // LZ4 block format (no framing)
    snappy,   // Snappy block format
    zstd,     // Zstandard
    gzip,     // Gzip (deflate + gzip headers)
    zlib,     // Zlib (deflate + zlib headers)
    deflate,  // Raw deflate
    brotli,   // Brotli
    none,     // No compression (passthrough)
};

Codec Methods

const codec: cz.Codec = .zstd;

codec.name();              // "Zstandard"
codec.extension();         // ".zst"
codec.supportsStreaming(); // true
codec.supportsDictionary(); // true
codec.hasBuiltinChecksum(); // true
codec.isFramed();          // true
codec.requiresExpectedSize(); // false

See Codec Detection for auto-detection.