Rust 对消息数据交换格式的绑定

这是消息二进制数据交换格式的纯 Rust 实现。

最低支持的 Rust 版本

由于这个 crate 使用 fallible collection API 在反序列化值时预分配集合，因此最低要求的 Rust 版本是 1.57.0。

使用方法

将此添加到您的 Cargo.toml 文件中

[dependencies]
nachricht = "0.4.0"

然后您可以构建、编码和解码消息

use std::borrow::Cow;
use std::collections::BTreeMap;
use nachricht::*;

fn main() -> Result<(), Box<dyn Error>> {
    let mut buf = Vec::new();
    let nachricht = Value::Record(BTreeMap::from([(Cow::Borrowed("key"), Value::Str(Cow::Borrowed("value")))]));
    Encoder::encode(&nachricht, &mut buf)?;
    let decoded = Decoder::decode(&buf)?.0;
    assert_eq!(nachricht, decoded);
    Ok(())
}

lib.rs:

所有编码函数都接受 &self 和一个写入器，并返回写入的字节数。所有解码函数都接受一个缓冲区，并返回 Self 和消耗的字节数。

关于 usize 的说明

消息 在内部使用 64 位无符号整数来表示字段长度。然而，Rust 使用架构相关的 usize 用于切片索引。这意味着在 usize 小于 u64 的架构上（例如 32 位 i386），一些有效的 消息 消息无法解码，因为没有有效的方法来高效索引容器。在这种情况下将引发一个 DecodeError::Length。同样，在 usize 大于 u64 的架构上，一些有效的 Rust 数据结构无法编码，因为没有方法在线路格式中表示它们。在这种情况下将引发一个 EncodeError::Length。

关于 Map 的说明

这个变体 Value::Map 在内部使用了一个键值对数组 Vec，因为 Rust 的浮点数类型 f32 和 f64 既没有实现 Ord 也没有实现 Hash，因此 Value 不能用作标准库映射中的键。

同样地，Value::Record 使用的是 BTreeMap 而不是 HashMap，因为当确定具有相同布局的记录是否已经被编码以便可以重用时，字段名需要有一个稳定的顺序。

示例

use nachricht::*;
use std::borrow::Cow;
use std::collections::BTreeMap;

let mut buf = Vec::new();
let value = Value::Record(BTreeMap::from([(Cow::Borrowed("key"), Value::Str(Cow::Borrowed("value")))]));
Encoder::encode(&value, &mut buf);
assert_eq!(buf, [
    0xa1, // Record of length 1
    0x63, // Symbol of length 3
    0x6b, // 'k'
    0x65, // 'e'
    0x79, // 'y'
    0x45, // Str of length 5
    0x76, // 'v'
    0x61, // 'a'
    0x6c, // 'l'
    0x75, // 'u',
    0x65, // 'e'
]);
let decoded = Decoder::decode(&buf).unwrap();
assert_eq!(value, decoded.0);
assert_eq!(11, decoded.1);