miniz

压缩归档

v1.0.0C 混编0 依赖ABI 1

miniz 轻量级 deflate 压缩 — 单文件 C 实现，兼容 zlib 格式，适合嵌入式与轻量集成场景。C 层内嵌 miniz 11.3.1，xlang 层提供二进制安全（统一 Buffer）、易用的 API：一次性内存压缩、文件级压缩、以及 update → drain → finish 增量流式处理。

典型场景

嵌入式压缩zlib 兼容轻量集成日志压缩缓存压缩进度回显传输

快速开始

quick_start.xl
import miniz

func main(...) as int
    Buffer packed = miniz.compress("hello miniz")
    println(miniz.decompressText(packed))   // hello miniz

    auto enc = miniz.compressor()
    enc.update("part1 ")
    enc.update("part2")
    enc.finish()
    Buffer blob = enc.drain()

    auto dec = miniz.decompressor()
    dec.update(blob)
    dec.finish()
    println(dec.drain().text())           // part1 part2
    return 0
end

核心特性

deflate 兼容 — 产出标准 zlib 格式，可与 gzip/zlib 生态互通
二进制安全 — 输入输出统一 Buffer
三种粒度 — 一次性内存、文件级、增量流式（MinizCompressor/MinizDecompressor）
真流式输出 — drain() 随时取走已产出字节
进度回显 — inputBytes/outputBytes 字节计数器
多成员流 — 解压器 finished/members
级别 1..10 — 1 最快、10 最高压缩率、6 默认平衡
文件原子写 — 临时文件 + 原子重命名

包信息

包名	miniz
版本	1.0.0
引擎	miniz 11.3.1（单文件 deflate 实现）
实现方式	C 混编（miniz 引擎 C，API 层 xlang）
依赖	无
ABI 版本	1
导出符号	compress(), decompress(), decompressText(), compressFile(), decompressFile(), compressor(), decompressor(), MinizCompressor, MinizDecompressor, MINIZ_* 常量
源文件	extlibs/miniz/src/miniz.xl

常量

export const int MINIZ_MIN_LEVEL = 1 export const int MINIZ_MAX_LEVEL = 10 export const int MINIZ_DEFAULT_LEVEL = 6

压缩级别常量。1 最快、10 压缩率最高、6 为默认平衡点。

一次性 / 文件 / 流式

export func compress(Buffer data, int level = 6, ...) as Buffer export func decompress(Buffer data, ...) as Buffer export func compressFile(...) / decompressFile(...) export func compressor(int level = 6, ...) as MinizCompressor export func decompressor(...) as MinizDecompressor

API 结构与 zlib/zstd 一致：一次性、文件级、增量流式三粒度。流式类提供 update/drain/finish + inputBytes/outputBytes/finished/members。

文件接口末尾支持可空 onProgress(inputBytes, totalBytes, outputBytes)。返回 false 删除临时输出并抛 CancelledError；回调异常原样传播。C 层对应 xrtprogressproc + void* userData。

level 越界抛 ValueError；数据损坏抛 CompressionError。

教学范例

完整源文件：examples/extlibs/miniz.xl

1. 一次性 + 流式

miniz.xl
import miniz

Buffer packed = miniz.compress("xlang miniz")
assert miniz.decompressText(packed) == "xlang miniz"
println("引擎版本: ", miniz.version())

auto encoder = miniz.compressor()
Buffer streamPacked = Buffer()
encoder.update("hello ")
streamPacked.append(encoder.drain())
encoder.update("stream")
streamPacked.append(encoder.drain())
encoder.finish()
streamPacked.append(encoder.drain())

auto decoder = miniz.decompressor()
decoder.update(streamPacked)
decoder.finish()
assert decoder.drain().text() == "hello stream"

2. 最高级别 L10

调优
auto tuned = miniz.compressor(miniz.MINIZ_MAX_LEVEL)
tuned.update("tune me")
tuned.finish()
assert miniz.decompress(tuned.drain()).text() == "tune me"

运行范例

终端
cd release
xl.exe run examples\extlibs\miniz.xl

测试覆盖

测试文件：test/cases/extlib_miniz.xl、test/cases/extlib_miniz_progress.xl

一次性二进制往返（含 NUL / 0xFF）
流式往返 + members 计数 + finished
分块收集 + inputBytes 计数器
最高级别 MINIZ_MAX_LEVEL（L10）往返
级别越界抛 ValueError
串联多成员流
损坏数据抛 CompressionError
文件级往返 + overwrite 拒绝

运行测试

终端
cd release
xl.exe run ..\test\cases\extlib_miniz.xl

← 返回扩展库列表