json

std.data.json

def Kind

pub def Kind: u8

val NULL

pub val NULL:   Kind = 0

val BOOL

pub val BOOL:   Kind = 1

val NUMBER

pub val NUMBER: Kind = 2

val STRING

pub val STRING: Kind = 3

val ARRAY

pub val ARRAY:  Kind = 4

val OBJECT

pub val OBJECT: Kind = 5

rec Value

pub rec Value;

解析后的 JSON 值

kind:类型判别式(NULLBOOLNUMBERSTRINGARRAYOBJECTbool_val:当 kind == BOOL 时的布尔值(1 = true,0 = false) is_float:对于 NUMBER,如果是作为浮点数解析的则为 1(具有小数部分或指数),否则为 0(整数);用于选择 num_val 还是 float_val num_val:当 kind == NUMBERis_float == 0 时的整数值 float_val:当 kind == NUMBERis_float == 1 时的浮点值 str_val:当 kind == STRING 时指向原始输入的指针;保留转义的线上传输原始字节(逻辑字节请使用 value_string_decodestr_len:字符串的字节长度(不含空终止符) children:堆分配的子 Value 数组(ARRAYOBJECTkeys:堆分配的键字符串数组(仅限 OBJECT,与 children 平行;指向原始输入的指针,不含空终止符) keys_len:键字节长度的堆分配数组(与 keys 平行) count:子项/键的数量 capchildren/keys 数组的已分配容量

fun parse

pub fun parse(src: *u8, src_len: usize, alloc: *allocator.Allocator) Result[Value, str];

将 JSON 文本解析为 Value 树

src:指向 JSON 源字节的指针 src_len:源字节的长度 alloc:用于数组/对象存储的分配器 ret:成功时返回根 Value,或返回错误消息

fun value_is_null

pub fun value_is_null(v: *Value) bool;

检查值是否为 null

fun value_is_bool

pub fun value_is_bool(v: *Value) bool;

检查值是否为布尔值

fun value_is_number

pub fun value_is_number(v: *Value) bool;

检查值是否为数字

fun value_is_string

pub fun value_is_string(v: *Value) bool;

检查值是否为字符串

fun value_is_array

pub fun value_is_array(v: *Value) bool;

检查值是否为数组

fun value_is_object

pub fun value_is_object(v: *Value) bool;

检查值是否为对象

fun value_bool

pub fun value_bool(v: *Value) bool;

获取布尔值

ret:如果 bool_val 非零则为 true

fun value_is_float

pub fun value_is_float(v: *Value) bool;

NUMBER 值是否被解析为浮点数

对于带有小数或指数的数字为 true,对于看起来像整数的数字为 false;用于选择是通过 value_float 还是 value_number 读取它。

fun value_number

pub fun value_number(v: *Value) i64;

获取整数 NUMBER 的整数值

当数字被解析为整数时有意义(value_is_floatfalse);请使用 value_float 读取浮点数。

fun value_float

pub fun value_float(v: *Value) f64;

NUMBER 的值获取为 64 位浮点数

为解析为浮点数的数字返回浮点值,或将整数数字拓宽为 f64 返回,因此它对任何 NUMBER 都有定义。

fun value_string

pub fun value_string(v: *Value, len: *usize) *u8;

获取原始字符串指针和长度

对于解析后的值,这些是引号之间的线上传输原始字节,保留了转义并且是到输入的零拷贝(解析 "a\nb" 产生 4 个字节 a \ n b);使用 value_string_decode 将转义解析为逻辑字节。

len:接收字符串的字节长度 ret:指向原始字符串内容第一个字节的指针

fun value_string_decode

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_lenbuf:解码后字节的目标缓冲区 lenbuf 的容量(以字节为单位) ret:成功时解码的字节长度(可能超过 len),如果字节包含格式错误的转义(未知转义、没有四个十六进制数字的 '\u'、或格式错误的代理对)则返回错误消息

fun value_count

pub fun value_count(v: *Value) usize;

获取子项数量(数组元素或对象条目)

fun value_get

pub fun value_get(v: *Value, index: usize) *Value;

通过索引获取数组元素或对象值

index:从 0 开始的索引 ret:指向子 Value 的指针,如果越界则为 nil

fun value_key

pub fun value_key(v: *Value, index: usize) str;

通过索引获取对象键

该键指向原始输入且以空字符结尾;其字节长度来自 value_key_len

index:从 0 开始的索引 ret:键字符串,如果越界则为 nil

fun value_key_len

pub fun value_key_len(v: *Value, index: usize) usize;

通过索引获取对象键的字节长度

index:从 0 开始的索引 ret:键的字节长度,如果越界则为 0

fun value_find

pub fun value_find(v: *Value, key: str) *Value;

通过键名查找对象值(线性搜索)

key:要搜索的以空字符结尾的键 ret:指向 Value 的指针,如果未找到则为 nil

fun emit

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

rec Object

pub rec Object;

流式 NDJSON 发射器中的一个开放 JSON 对象,跟踪其成员之间的逗号边界。

w:发出该对象的写入器(借用) first:尚未向对象发出任何成员

rec Array

pub rec Array;

流式 NDJSON 发射器中的一个开放 JSON 数组,跟踪其元素之间的逗号边界。

w:发出该数组的写入器(借用) first:尚未向数组发出任何元素

fun object_begin

pub fun object_begin(w: *writer.Writer, o: *Object);

开始一个 JSON 对象,写入 { 并武装第一成员状态。

w:用于发出的写入器(必须比对象活得更久) o:要初始化的对象状态

fun object_end

pub fun object_end(o: *Object);

结束一个 JSON 对象,写入 } 和终止 NDJSON 行的换行符。

o:要关闭的对象

fun object_end_value

pub fun object_end_value(o: *Object);

关闭嵌套对象,写入 } 但不带 NDJSON 行终止符。

用于作为成员值或数组元素的对象,其中封闭的容器(而不是此对象)拥有行边界。

o:要关闭的对象

fun field_object_begin

pub fun field_object_begin(o: *Object, key: *u8, child: *Object);

打开对象类型的成员:键引入,然后是 {,在父写入器之上武装 child

field_* 辅助函数填充 child 并用 object_end_value 关闭它;父对象保持打开状态并随后接受更多成员。

o:开放的父对象 key:成员键 child:要初始化的嵌套对象状态

fun field_array_begin

pub fun field_array_begin(o: *Object, key: *u8, arr: *Array);

打开数组类型的成员:键引入,然后是 [, 在父写入器之上武装 arr。用 array_end 关闭它。

o:开放的父对象 key:成员键 arr:要初始化的数组状态

fun array_end

pub fun array_end(arr: *Array);

关闭一个数组,写入 ]

arr:要关闭的数组

fun array_object_begin

pub fun array_object_begin(arr: *Array, child: *Object);

打开 arr 的对象元素:元素分隔符,然后是 {, 在数组写入器之上武装 child

field_* 辅助函数填充 child 并用 object_end_value 关闭它。

arr:开放的数组 child:要初始化的元素对象状态

fun field_str

pub fun field_str(o: *Object, key: *u8, v: *u8);

发出字符串类型的成员(值带引号且经过 ASCII 转义)

o:开放的对象 key:成员键(ASCII,在引号之间原样发出) v:以空字符结尾的值,经过转义;nil 发出空字符串

fun field_str_or_null

pub fun field_str_or_null(o: *Object, key: *u8, v: *u8);

发出字符串或 null 成员:转义的值,当 vnil 时发出 JSON null

o:开放的对象 key:成员键 v:以空字符结尾的值,或对于 JSON null 为 nil

fun field_null

pub fun field_null(o: *Object, key: *u8);

发出一个 JSON null 类型的成员

o:开放的对象 key:成员键

fun field_i64

pub fun field_i64(o: *Object, key: *u8, v: i64);

发出整数类型的成员

o:开放的对象 key:成员键 v:整数值

fun field_f64

pub fun field_f64(o: *Object, key: *u8, v: f64);

发出浮点类型的成员

该值被写入为通过解析器往返的最短十进制数(value_float)。整数值的浮点数发出时不带小数部分,因此解析器会将其读回为整数数字(value_is_float 为 false);在这种情况下请使用 value_number 读取它。

o:开放的对象 key:成员键 v:浮点值

fun field_bool

pub fun field_bool(o: *Object, key: *u8, v: bool);

发出布尔类型的成员

o:开放的对象 key:成员键 v:布尔值

fun value_f64

pub fun value_f64(w: *writer.Writer, v: f64);

通过写入器写入一个裸的 JSON 浮点数字

发出通过解析器往返的最短十进制数(value_float),没有键或周围的容器 —— 相当于浮点数的 write_json_string,用于数组元素或独立的值。整数值的浮点数发出时不带小数部分。

w:用于发出的写入器 v:浮点值

fun write_json_string

pub fun write_json_string(w: *writer.Writer, s: *u8);

ESCAPE_ENSURE_ASCII 下写入一个 JSON 字符串字面量:值带引号,每个字节都转义为可打印的 ASCII。

w:用于发出的写入器 s:以空字符结尾的值,或对于空字符串为 nil