json_dotpath

使用“点路径”访问嵌套JSON数组对象的成员。

变更记录

1.1.0

添加了 dot_has() 和 dot_has_checked()

1.0.3

将 failure 替换为 thiserror，并为错误类型实现 std::error::Error。

1.0.0

API已更改，现在返回 Result<Option<T>> 而不是在内部错误时引发恐慌。现在库的使用更加安全。

此外，所有逻辑都已调整，以使其更加健壮和一致。

数组附加和前缀操作符现在使用 << 和 >> 而不是重载 < 和 >，现在所有数组访问（获取第一个和最后一个元素）的方式都相同。

点路径

点路径表示从JSON对象的根到其节点之一的路径。这样的路径通过点连接对象和数组键来表示

考虑以下示例JSON

{
  "fruit": [
    {"name": "lemon", "color":  "yellow"},
    {"name": "apple", "color":  "green"},
    {"name": "cherry", "color":  "red"}
  ]
}

以下路径表示其部分

• "" ... 整个对象
• "fruit" ... 水果数组
• "fruit.0" ... 第一个水果对象，{"name": "lemon", "color": "yellow"}
• "fruit.1.name" ... 第二个（索引从0开始）水果的名称，"apple"

还可以使用特殊模式进行对象操作（见下文）。

对象操作

DotPaths 特性向 serde_json::Value、Vec<Value> 和 serde_json::Map<String, Value>（Value::Object 和 Value::Array 的内部结构）中添加了五个主要方法。

• dot_get(path) - 通过路径获取值
• dot_get_mut(path) - 获取JSON对象的元素的可变引用
• dot_set(path, value) - 设置新值，丢弃原始值（如果有）
• dot_replace(path, value) - 设置新值，返回原始值（如果有）
• dot_take(path) - 通过路径删除值，返回它（如果有）

dot_set() 支持其他方法中找不到的数组操作语法，即使用 >n 和 <n 模式在索引之前或之后插入元素，并移动其余 Vec

所有方法都是通用的，负责序列化和反序列化存储/检索的数据。《tt class="src-rs">dot_get_mut()是一个例外，返回&mut Value。

dot_set()和dot_remove()不反序列化原始对象，这使得它们在原始值不需要时比dot_replace()和dot_take()更高效。

错误报告

所有方法都返回Result<json_dotpath::Error, T>（别名json_dotpath::Result<T>），无论是作为json_dotpath::Result<()>，还是当期望一个值时，作为json_dotpath::Result<Option<T>>。

应谨慎处理这些结果，因为它们报告结构错误（意味着请求的操作无法执行），或提供的路径无效。

动态对象构建

当路径不存在但可以存在（例如附加的数组元素、新的对象键），并且使用了其中一个赋值方法或dot_get_mut()时，将自动创建此元素，包括所需的父元素。

这在某个单元测试中得到了很好的说明

let mut obj = Value::Null;
let _ = obj.dot_get_mut("foo.0").unwrap(); // get mut, here only for side effects
assert_eq!(json!({"foo": [null]}), obj);

在这种情况下，null可以灵活地变成数组或对象（见下文“null的特殊处理”）。

点路径语法

路径简单地是一系列由点（.）连接的路径段。

根据它们使用的方法，库为一些符号赋予了特殊的意义。所有符号（包括.）都可以使用反斜杠转义，如果它们的字面值需要作为路径的一部分。

数组模式

数组键必须是数字（整数），或者以下列出的特殊模式之一。

• < ... 第一个元素
• > ... 最后一个元素
• -或<< ... 预先添加
• +或>> ... 追加
• <n，例如<5 ... 在第n个元素之前插入
• >n，例如>5 ... 在第n个元素之后插入