friends.#(last=="Murphy").first    >> "Dale"
friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
friends.#(age>45)#.last            >> ["Craig","Murphy"]
friends.#(first%"D*").last         >> "Murphy"
friends.#(first!%"D*").last        >> "Craig"
friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]

值类型

将 JSON 值转换为 Rust 类型

value.i8()
value.i16()
value.i32()
value.i64()
value.u8()
value.u16()
value.u32()
value.u64()
value.f32()
value.f64()
value.bool()
value.str()    // a string representation
value.json()   // the raw json

在值上工作的便捷函数

value.kind()             // String, Number, True, False, Null, Array, or Object
value.exists()           // returns true if value exists in JSON.
value.get(path: &str)    // get a child value
value.each(|key, value|) // iterate over child values

64 位整数

调用 value.i64() 和 value.u64() 可以读取所有 64 位，允许处理大整数。

value.i64() -> i64   // -9223372036854775808 to 9223372036854775807
value.u64() -> u64   // 0 to 18446744073709551615

修饰符和路径链接

修饰符是执行自定义处理的一个路径组件。

可以使用管道字符将多个路径 "链接" 在一起。这对于从修改后的查询中获取值很有用。

例如，在上述 JSON 文档中使用内置的 @reverse 修饰符，我们将获取 children 数组并反转其顺序

"children|@reverse"           >> ["Jack","Alex","Sara"]
"children|@reverse|0"         >> "Jack"

目前有以下内置修饰符

• @reverse：反转数组或对象的成员。
• @ugly：从 JSON 文档中删除所有空白。
• @pretty：使 JSON 文档更易于阅读。
• @this：返回当前元素。它可以用来检索根元素。
• @valid：确保 JSON 文档是有效的。
• @flatten：展平数组。
• @join：将多个对象合并成一个对象。

修饰符参数

修饰符可能接受一个可选参数。参数可以是有效的 JSON 文档或只是字符。

例如，@pretty 修饰符接受一个 JSON 对象作为参数。

@pretty:{"sortKeys":true} 

这使得 JSON 更美观并按顺序排列所有键。

{
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"age": 44, "first": "Dale", "last": "Murphy"},
    {"age": 68, "first": "Roger", "last": "Craig"},
    {"age": 47, "first": "Jane", "last": "Murphy"}
  ],
  "name": {"first": "Tom", "last": "Anderson"}
}

@pretty 的完整选项列表是 sortKeys、indent、prefix 和 width。有关更多信息，请参阅 美观选项。

JSON 行

支持使用 .. 前缀的 JSON Lines，它将多行文档视为一个数组。

例如：

{"name": "Gilbert", "age": 61}
{"name": "Alexa", "age": 34}
{"name": "May", "age": 57}
{"name": "Deloise", "age": 44}

..#                   >> 4
..1                   >> {"name": "Alexa", "age": 34}
..3                   >> {"name": "Deloise", "age": 44}
..#.name              >> ["Gilbert","Alexa","May","Deloise"]
..#(name="May").age   >> 57

获取嵌套数组值

假设你想要从以下 JSON 中获取所有姓氏

{
  "programmers": [
    {
      "firstName": "Janet", 
      "lastName": "McLaughlin", 
    }, {
      "firstName": "Elliotte", 
      "lastName": "Hunter", 
    }, {
      "firstName": "Jason", 
      "lastName": "Harold", 
    }
  ]
}

你可以使用路径 "programmers.#.lastName" 如此使用

value := gjson::get(json, "programmers.#.lastName");
for name in value.array() {
	println!("{}", name);
}

你还可以查询数组内的对象

let name = gjson::get(json, "programmers.#(lastName=Hunter).firstName");
println!("{}", name)  // prints "Elliotte"

遍历对象或数组

ForEach 函数允许快速遍历对象或数组。对于对象，键和值会被传递给迭代函数。对于数组，只传递值。从迭代器函数返回 false 将停止迭代。

let value := gjson::get(json, "programmers")
value::each(|key, value| {
	println!("{}", value);
	true // keep iterating
});

简单解析和获取

有一个 gjson::parse(json) 函数可以进行简单解析，以及 value.get(path) 可以搜索值。

例如，以下都会返回相同的值

gjson::parse(json).get("name").get("last");
gjson::get(json, "name").get("last");
gjson::get(json, "name.last");

检查值是否存在

有时你只想知道一个值是否存在。

let value = gjson::get(json, "name.last");
if !value.exists() {
	println!("no last name");
} else {
	println!("{}", value);
}

// Or as one step
if gjson::get(json, "name.last").exists() {
	println!("has a last name");
}

验证 JSON

Get* 和 Parse* 函数期望 JSON 是有效的。无效的 JSON 不会引发恐慌，但它可能返回意外的值。

if !gjson::valid(json) {
	return Err("invalid json");
}
let value = gjson::get(json, "name.last");