普贤教程 › 包参考

bson 包

BSON 编解码（基础类型子集）

项	值
包名	`bson`
版本	`0.2.0`
可用版本	`0.1.0 / 0.2.0`
入口	`bson.px`
分类	`数据格式与编解码`
文件数 / 行数	`1 / 229`

安装与引入

bash

pxpkg init          # 首次
pxpkg add bson@0.2.0
pxpkg install

import bson

所属分类教程：数据格式与编解码

公开接口

函数	参数
`bson_encode`	`doc`
`bson_decode`	`data`

其余 16 个 def（内部与辅助，可直接调用但不属稳定接口）

函数	参数
`o_le32`	`v`
`o_le64`	`v`
`o_rd_i32`	`b, off`
`o_rd_i64`	`b, off`
`o_rd_u8`	`b, off`
`o_read_cstr`	`b, off`
`o_enc_doc`	`d`
`o_enc_elem`	`name, v`
`o_build`	`items, is_array`
`o_dec_doc`	`b, off, is_array`
`o_dec_value`	`b, off, ty`
`bson_encode_int`	`name, v`
`bson_encode_str`	`name, v`
`bson_doc_keys`	`doc`
`bson_doc_has`	`doc, key`
`bson_doc_get`	`doc, key`

包内说明（源码头注释）

text

============================================================
普贤生态库：registry/bson —— BSON 编解码（基础类型子集）
------------------------------------------------------------
纯函数库（无 IO、无状态），编译（px build）与解释（px run）双模式一致。
bson_encode(doc) → Ok(bytes) | Err   # dict→document；list→array（可嵌套）
bson_decode(data) → Ok(value) | Err  # 须恰好消费整段（含 4 字节长度 + 终止 0x00）
支持类型：
0x01 double · 0x02 string（长度=字节数）· 0x03 doc · 0x04 array ·
0x05 binary（subtype 0；其他 subtype 解码为 {subtype,data}）·
0x07 ObjectId（编: 24 位 hex/12 字节；解: hex 串）· 0x08 bool · 0x09 datetime(int64 ms) ·
0x0A null · 0x10 int32 · 0x12 int64（int 编码按范围自动选 32/64）
说明：
- 未知类型字节在解码时报 Err（响亮，不静默跳过）。
- 文档长度/字符串长度一律按 **字节数**（str 的 len() 是码点数，须 bytes_len）。
- 与 Python bson 双向互操作：编码字节逐段对齐（见测试）。
============================================================
---- 内部：小端读写 ----