cbor

以 XRT 值模型读写紧凑二进制数据，同时提供字节串和十六进制辅助入口。

版本 1.0.0 · C / xlang · 无扩展库依赖

快速开始

import cbor

var source = {"name": "甲", "count": 2}
Buffer wire = cbor.encode(source)
var value = cbor.decode(wire)
assert value["name"] == "甲"
assert cbor.decode(cbor.fromHex("f6")) == null

合法 CBOR null 会返回 xlang 的 null，畸形数据抛 ValueError，两者不会混淆。

接口与边界

入口	用途
`encode(value) / decode(Buffer)`	在 var 值和 CBOR 二进制之间转换。
`encodeBytes(Buffer) / decodeBytes(Buffer)`	直接处理 CBOR 字节串，不经文本转换。
`toHex(Buffer) / fromHex(text)`	用于查看或输入 CBOR 十六进制字节；含 NUL 文本拒绝，C 文本入口按 128 MiB 限界扫描。

支持 null、布尔、有符号 int64 与无符号 uint64 整数、float64、UTF-8 文本、字节串、数组、文本键字典及时间标签 0/1。正整数支持到 2^64-1；解码不超过 INT64_MAX 的值沿用 int，超过时用 uint64，线格式不保留较小正整数原本的有符号类型。文本键和字符串值均按真实字节长度处理，可完整往返内嵌 NUL；这不同于上表中拒绝 NUL 的十六进制文本入口。解码还接受半精度/单精度浮点和不定长容器。超出 int64 的负整数、非文本映射键、未知标签和未建模简单值不受支持；重复键、坏 UTF-8、截断及尾随数据报错。二进制数据上限 64 MiB，调试用 HEX 文本上限 128 MiB；C 入口将缺失输入报为参数错误、资源超限报为范围错误，XLang 中畸形数据抛 ValueError，深度超限可捕获 RangeError，分配故障抛 MemoryError。整份文档累计 100 万数组元素/字典条目和 64 层嵌套，时间 tag 0 的载荷额外占一层；解码不定长字符串分块也计入总预算。编解码使用同一累计上限，定长头部的极大长度报范围错误，不会误当作不定长。编码不承诺确定性形式，不应直接用输出字节做跨实现签名。

C 对照

#define XRT_MODULE_ALL
#include "xrt.h"
#include "cbor_native.h"

int main(void)
{
    const unsigned char wire[] = {0xf6};
    xvalue* value = xcbor_decode(wire, sizeof(wire));
    if (value == NULL) return 1;
    int ok = xrtValueType(value) == XVALUE_NULL;
    xrtValueRelease(value);
    return ok ? 0 : 2;
}

C 解码失败返回 NULL，合法 CBOR null 返回拥有型 XVALUE_NULL。其他拥有型结果按类型使用 xrtValueRelease、xrtBufferDestroy 或 xrtFree。完整双语范例见 extlibs/cbor/examples/cbor.xl 与 cbor_c.c；从发布目录运行 ./xl run extlibs/cbor/examples/cbor_c.c 即可执行 C 范例。单文件范例包含原生实现，正式包仍独立编译。

验证状态

2026-10-29：修复非法 1f 被当成最大uint64、3f/df 与保留 f8 00..1f 诊断不准确，以及分块预算超限误报值错误。新增2,591项线格式/上下文/释放检查、全部65,536种半精度位形的Python标准库独立对照，以及七行黄金输出的 examples/validate_wire.xl / validate_wire_c.c 双语报文范例。完整门禁仍要求语言容器编码通过，未把既有M1阻断移为预期失败或宣称已签收。

2026-10-25 Windows 发布版复验：严格 C、C 边界/分配故障与 C 范例通过；首个 XLang 边界在语言数组传入 encode(var) 时报告不支持的动态类型，JIT 与独立 EXE 最小复现均失败。问题属于共享 foreign var 容器投影边界，完整语言与 AOT 门禁尚未签收；不能沿用早期 C/XLang 全绿的结果。

C/XLang 成对范例覆盖六个公开入口；含 NUL 与 0xFF 的字节样本固定编码为 4300ff41。既有双语黄金输出仍保留，待共享边界修复后重跑两平台完整门禁。

2026-10-21 XLang 六个公开入口的分配故障用例改为逐入口扫描到首次成功，并在每次失败后立即清除故障、重试。Windows/Linux 正式运行器均通过；包实现未改，完整 AOT 的共享阻断未变。

powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/cbor/test/check.ps1 -SkipAot
wsl bash release/extlibs/cbor/test/check.sh

2026-10-16 历史发布物：Windows 严格 GCC、C/XLang 边界、随机输入与双语输出对照通过；Linux 包级 C smoke、边界与范例通过 ASan/UBSan，同次脚本还验证 XLang 边界及 C/XLang 范例逐字节同输出。六个公开入口新增逐点分配故障扫描，C 保留 XERR_MEMORY、XLang 捕获 MemoryError，失败清除后可重试；解码故障覆盖嵌套数组、字典和字节串。整份文档累计项数的恰好达限/超限红绿回归通过。当时完整 AOT 在首个核心构建缺少 xl6NativeHandleTraceLeaf，这一诊断不代表当前发布物的首个阻断。