pub def Kind: u8
pub val NULL: Kind = 0
pub val BOOL: Kind = 1
pub val NUMBER: Kind = 2
pub val STRING: Kind = 3
pub val ARRAY: Kind = 4
pub val OBJECT: Kind = 5
pub rec Value;
解析后的 JSON 值
kind:类型判别式(NULL、BOOL、NUMBER、STRING、ARRAY、OBJECT) bool_val:当 kind == BOOL 时的布尔值(1 = true,0 = false) is_float:对于 NUMBER,如果是作为浮点数解析的则为 1(具有小数部分或指数),否则为 0(整数);用于选择 num_val 还是 float_val num_val:当 kind == NUMBER 且 is_float == 0 时的整数值 float_val:当 kind == NUMBER 且 is_float == 1 时的浮点值 str_val:当 kind == STRING 时指向原始输入的指针;保留转义的线上传输原始字节(逻辑字节请使用 value_string_decode) str_len:字符串的字节长度(不含空终止符) children:堆分配的子 Value 数组(ARRAY 或 OBJECT) keys:堆分配的键字符串数组(仅限 OBJECT,与 children 平行;指向原始输入的指针,不含空终止符) keys_len:键字节长度的堆分配数组(与 keys 平行) count:子项/键的数量 cap:children/keys 数组的已分配容量
pub fun parse(src: *u8, src_len: usize, alloc: *allocator.Allocator) Result[Value, str];
将 JSON 文本解析为 Value 树
src:指向 JSON 源字节的指针 src_len:源字节的长度 alloc:用于数组/对象存储的分配器 ret:成功时返回根 Value,或返回错误消息
pub fun value_is_null(v: *Value) bool;
检查值是否为 null
pub fun value_is_bool(v: *Value) bool;
检查值是否为布尔值
pub fun value_is_number(v: *Value) bool;
检查值是否为数字
pub fun value_is_string(v: *Value) bool;
检查值是否为字符串
pub fun value_is_array(v: *Value) bool;
检查值是否为数组
pub fun value_is_object(v: *Value) bool;
检查值是否为对象
pub fun value_bool(v: *Value) bool;
获取布尔值
ret:如果 bool_val 非零则为 true
pub fun value_is_float(v: *Value) bool;
NUMBER 值是否被解析为浮点数
对于带有小数或指数的数字为 true,对于看起来像整数的数字为 false;用于选择是通过 value_float 还是 value_number 读取它。
pub fun value_number(v: *Value) i64;
获取整数 NUMBER 的整数值
当数字被解析为整数时有意义(value_is_float 为 false);请使用 value_float 读取浮点数。
pub fun value_float(v: *Value) f64;
将 NUMBER 的值获取为 64 位浮点数
为解析为浮点数的数字返回浮点值,或将整数数字拓宽为 f64 返回,因此它对任何 NUMBER 都有定义。
pub fun value_string(v: *Value, len: *usize) *u8;
获取原始字符串指针和长度
对于解析后的值,这些是引号之间的线上传输原始字节,保留了转义并且是到输入的零拷贝(解析 "a\nb" 产生 4 个字节 a \ n b);使用 value_string_decode 将转义解析为逻辑字节。
len:接收字符串的字节长度 ret:指向原始字符串内容第一个字节的指针
pub fun value_string_decode(v: *Value, buf: *u8, len: usize) Result[usize, str];
将字符串值的原始线上传输字节解码为逻辑字节,将 JSON 转义解析到调用者缓冲区中。
作为 emit 转义的反向操作:'\"'、 '\\'、 '\/' 变为 '"'、 '\\'、 '/','\b'、 '\f'、 '\n'、 '\r'、 '\t' 变为它们的控制字节,而 '\uXXXX' 解码为 UTF-8(高低代理对组合为一个星体码点)。未转义的字节(包括原始 UTF-8)原样通过。解析器存储原始线上传输字节(参见 value_string),因此这就是解析后的字符串成为逻辑文本的地方。
字节被写入 buf 直到 len;总是返回完整解码的长度,因此调用者可以通过传递长度 0(或短缓冲区)并一旦 buf 足够大时再次调用来确定缓冲区大小(与 emit 类似)。
v:要解码其原始字符串字节的值(str_val/str_len) buf:解码后字节的目标缓冲区 len:buf 的容量(以字节为单位) ret:成功时解码的字节长度(可能超过 len),如果字节包含格式错误的转义(未知转义、没有四个十六进制数字的 '\u'、或格式错误的代理对)则返回错误消息
pub fun value_count(v: *Value) usize;
获取子项数量(数组元素或对象条目)
pub fun value_get(v: *Value, index: usize) *Value;
通过索引获取数组元素或对象值
index:从 0 开始的索引 ret:指向子 Value 的指针,如果越界则为 nil
pub fun value_key(v: *Value, index: usize) str;
通过索引获取对象键
该键指向原始输入且不以空字符结尾;其字节长度来自 value_key_len。
index:从 0 开始的索引 ret:键字符串,如果越界则为 nil
pub fun value_key_len(v: *Value, index: usize) usize;
通过索引获取对象键的字节长度
index:从 0 开始的索引 ret:键的字节长度,如果越界则为 0
pub fun value_find(v: *Value, key: str) *Value;
通过键名查找对象值(线性搜索)
key:要搜索的以空字符结尾的键 ret:指向 Value 的指针,如果未找到则为 nil
pub fun emit(v: *Value, buf: *u8, len: usize) usize;
将 Value 作为 JSON 文本发出到缓冲区中
字符串和对象键在 ESCAPE_VERBATIM 下转义:'"'、 '\\' 以及控制字节 0x00-0x1F 被转义(短转义 \b \t \n \f \r,否则为 \u00xx);其他字节(包括有效的 UTF-8)原样写入。str_val 和键被视为逻辑字节,因此发出解析后的树会对源包含的任何转义进行双重转义 —— 参见文件头(mach-std#340)。
v:要发出的值 buf:目标缓冲区 len:目标缓冲区的大小(以字节为单位) ret:已写入的字节数(如果缓冲区太小可能超过 len)
pub rec Object;
流式 NDJSON 发射器中的一个开放 JSON 对象,跟踪其成员之间的逗号边界。
w:发出该对象的写入器(借用) first:尚未向对象发出任何成员
pub rec Array;
流式 NDJSON 发射器中的一个开放 JSON 数组,跟踪其元素之间的逗号边界。
w:发出该数组的写入器(借用) first:尚未向数组发出任何元素
pub fun object_begin(w: *writer.Writer, o: *Object);
开始一个 JSON 对象,写入 { 并武装第一成员状态。
w:用于发出的写入器(必须比对象活得更久) o:要初始化的对象状态
pub fun object_end(o: *Object);
结束一个 JSON 对象,写入 } 和终止 NDJSON 行的换行符。
o:要关闭的对象
pub fun object_end_value(o: *Object);
关闭嵌套对象,写入 } 但不带 NDJSON 行终止符。
用于作为成员值或数组元素的对象,其中封闭的容器(而不是此对象)拥有行边界。
o:要关闭的对象
pub fun field_object_begin(o: *Object, key: *u8, child: *Object);
打开对象类型的成员:键引入,然后是 {,在父写入器之上武装 child。
用 field_* 辅助函数填充 child 并用 object_end_value 关闭它;父对象保持打开状态并随后接受更多成员。
o:开放的父对象 key:成员键 child:要初始化的嵌套对象状态
pub fun field_array_begin(o: *Object, key: *u8, arr: *Array);
打开数组类型的成员:键引入,然后是 [, 在父写入器之上武装 arr。用 array_end 关闭它。
o:开放的父对象 key:成员键 arr:要初始化的数组状态
pub fun array_end(arr: *Array);
关闭一个数组,写入 ]
arr:要关闭的数组
pub fun array_object_begin(arr: *Array, child: *Object);
打开 arr 的对象元素:元素分隔符,然后是 {, 在数组写入器之上武装 child。
用 field_* 辅助函数填充 child 并用 object_end_value 关闭它。
arr:开放的数组 child:要初始化的元素对象状态
pub fun field_str(o: *Object, key: *u8, v: *u8);
发出字符串类型的成员(值带引号且经过 ASCII 转义)
o:开放的对象 key:成员键(ASCII,在引号之间原样发出) v:以空字符结尾的值,经过转义;nil 发出空字符串
pub fun field_str_or_null(o: *Object, key: *u8, v: *u8);
发出字符串或 null 成员:转义的值,当 v 为 nil 时发出 JSON null。
o:开放的对象 key:成员键 v:以空字符结尾的值,或对于 JSON null 为 nil
pub fun field_null(o: *Object, key: *u8);
发出一个 JSON null 类型的成员
o:开放的对象 key:成员键
pub fun field_i64(o: *Object, key: *u8, v: i64);
发出整数类型的成员
o:开放的对象 key:成员键 v:整数值
pub fun field_f64(o: *Object, key: *u8, v: f64);
发出浮点类型的成员
该值被写入为通过解析器往返的最短十进制数(value_float)。整数值的浮点数发出时不带小数部分,因此解析器会将其读回为整数数字(value_is_float 为 false);在这种情况下请使用 value_number 读取它。
o:开放的对象 key:成员键 v:浮点值
pub fun field_bool(o: *Object, key: *u8, v: bool);
发出布尔类型的成员
o:开放的对象 key:成员键 v:布尔值
pub fun value_f64(w: *writer.Writer, v: f64);
通过写入器写入一个裸的 JSON 浮点数字
发出通过解析器往返的最短十进制数(value_float),没有键或周围的容器 —— 相当于浮点数的 write_json_string,用于数组元素或独立的值。整数值的浮点数发出时不带小数部分。
w:用于发出的写入器 v:浮点值
pub fun write_json_string(w: *writer.Writer, s: *u8);
在 ESCAPE_ENSURE_ASCII 下写入一个 JSON 字符串字面量:值带引号,每个字节都转义为可打印的 ASCII。
w:用于发出的写入器 s:以空字符结尾的值,或对于空字符串为 nil