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

修饰符和路径链式调用

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

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

例如，使用内置的@reverse修饰符对上面的 JSON 文档进行处理，我们将得到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 Lines

支持使用..前缀来使用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 不会引发恐慌，但它可能会返回意外的值。

如果你从不可预测的来源获取 JSON，那么在使用 GJSON 之前进行验证可能是一个好主意。

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