lzma

压缩归档

v1.0.0C 混编0 依赖ABI 1

LZMA 高压缩率无损压缩 — 7-Zip 核心算法，以 LZ77 + 范围编码实现极高压缩率，适合对体积极敏感的归档与分发场景。C 层内嵌 LZMA SDK 23.01，xlang 层提供二进制安全（统一 Buffer）、易用的 API：一次性内存压缩、文件级压缩、以及 update → drain → finish 增量流式处理。

典型场景

归档压缩固件 / 安装包分发冷存储大文件分块流式备份存储进度回显传输

快速开始

quick_start.xl
import lzma

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

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

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

核心特性

极高压缩率 — LZMA 在级别 9 下压缩率通常优于 gzip/bzip2
二进制安全 — 输入输出统一 Buffer
三种粒度 — 一次性内存、文件级、增量流式（LzmaCompressor/LzmaDecompressor）
真流式输出 — drain() 随时取走已产出字节
进度回显 — inputBytes/outputBytes 字节计数器
多成员流 — 解压器 finished/members
级别 0..9 — 0 最快、9 最高压缩率、5 默认平衡
文件原子写 — 临时文件 + 原子重命名

包信息

包名	lzma
版本	1.0.0
引擎	LZMA SDK 23.01
实现方式	C 混编（LZMA SDK C，API 层 xlang）
依赖	无
ABI 版本	1
导出符号	compress(), decompress(), decompressText(), compressFile(), decompressFile(), compressor(), decompressor(), LzmaCompressor, LzmaDecompressor, LZMA_* 常量
源文件	extlibs/lzma/src/lzma.xl

常量

export const int LZMA_MIN_LEVEL = 0 export const int LZMA_MAX_LEVEL = 9 export const int LZMA_DEFAULT_LEVEL = 5

压缩级别常量。0 最快、9 压缩率最高、5 为默认平衡点。

一次性 / 文件 / 流式

export func compress(Buffer data, int level = 5, ...) as Buffer export func decompress(Buffer data, ...) as Buffer export func compressFile(...) / decompressFile(...) export func compressor(int level = 5, ...) as LzmaCompressor export func decompressor(...) as LzmaDecompressor

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

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

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

教学范例

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

1. 一次性 + 流式

lzma.xl
import lzma

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

auto encoder = lzma.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 = lzma.decompressor()
decoder.update(streamPacked)
decoder.finish()
assert decoder.drain().text() == "hello stream"

2. 最高级别 L9

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

运行范例

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

测试覆盖

测试文件：test/cases/extlib_lzma.xl、test/cases/extlib_lzma_progress.xl

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

运行测试

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

← 返回扩展库列表