xxhash

非密码哈希

XXH32 与 XXH64，面向数据分布、去重与快速指纹。内嵌 C 后端，不需要额外 xxHash DLL；不用于口令、签名或防恶意篡改。

函数

函数	参数与返回
`version()`	返回固定后端版本 0.8.3。
`hash32(data, seed=0)`	Buffer 或 string，种子 uint32，返回 uint32。
`hash64(data, seed=0)`	Buffer 或 string，种子 uint64，返回 uint64。
`hash32Hex / hash64Hex`	相同输入，分别返回 8/16 个小写 hex 字符。
`hashFile64(path, seed, maxInput, onProgress)`	返回 uint64；默认 seed=0、maxInput=268435456、onProgress=null。
`hashFile64Hex(...)`	相同参数，返回 16 个小写 hex 字符。
`hasher(seed=0, maxInput=268435456)`	返回 Xxhash64Hasher。

文本按 UTF-8 字节计算，不先复制为 Buffer。二进制 Buffer 可含零字节；空输入合法。整数摘要保留所有无符号位，负数种子和越界值不会隐式截断。

增量对象

import xxhash

auto h = xxhash.hasher()
h.update("a")
h.update("bc")
assert h.digestHex() == "44bc2cf5ad770999"
assert h.digest() == xxhash.hash64("abc")
h.reset()

update(Buffer|string) 追加输入；digest() 和 digestHex() 是可重复读取的快照，之后仍可追加。inputBytes 是 uint64 字节计数， valid 只检查句柄非空。超限或非法 update 使状态失败，reset 清除输入和失败状态、保留种子与预算。不同对象可独立并发，同一可变对象须串行操作。

文件与回调

auto sum = xxhash.hashFile64("data.bin",
    onProgress = func(int current, int total, int output) as bool
        return true
    end)

每块最多 64 KiB，EOF 再通知一次，空文件也通知。参数为已读、总长、输出字节；未知总长为 0，输出恒为 0。末次计数可能重复。回调返回 false 抛 CancelledError，用户异常保留类别和消息，允许嵌套另一次文件哈希。

maxInput 必须为正；非法参数为 ValueError、超限为 RangeError、分配失败为 MemoryError。文件路径通过 XRT UTF-8 API 处理，打开失败沿用 FileError；不修改输入、不返回部分摘要。预算不代表 CPU 限制或并发写入下的文件快照。

C 与验证

include/xrt_xxhash.h 提供核心 xrtXxhash32/64、OptionsInit/ErrorInit、 HasherCreate/Update/Digest/Reset/InputBytes/Error/Destroy 和 File64。 File64 借用 Reader，从当前游标读取，成功才写输出，保留 C 进度帧的 FINAL/TOTAL_KNOWN 标志。

核心 C 配置经过初始化后的零输入预算表示不设业务上限，仍检查溢出；薄绑定的 maximum=0 表示默认预算。原生 ABI 头为 include/xxhash_native.h，hex 借用 XRT 临时区，清理或回退后失效。

双语范例：examples/extlibs/xxhash_basic.xl 和 extlibs/xxhash/examples/basic.c，对照同一固定输出；完整教学见 examples/extlibs/xxhash.xl。

2026-09-27 的限定专项：37 项 Windows 检查、19 个生成原型、124 条独立向量，以及 Unicode、Reader/回调、分配故障、四线程、JIT/AOT 与双语固定输出对照。负数或超宽种子在语义阶段拒绝；TCC 的系统头包含顺序也有回归检查。入口为 tools/check_extlib_xxhash.ps1 与 tools/check_extlib_xxhash.sh。 Linux 仅独立 C sanitizer，不等同于 Linux xlang 或全平台认证。当前不公开 XXH3/128 语言 API、 XXH32 流式对象，不宣称共享可变对象并发或性能已认证。

后端固定为 v0.8.3 commit e626a72bc2321cd320e953a0ccf1584cad60f363， BSD-2-Clause；来源、适配层和独立向量见包内 VENDOR.md。