ciborium-ll

底层CBOR解析工具

本crate包含用于在CBOR中编码和解码项的低级别类型。本crate可在no_std和no_alloc环境中使用。要了解此crate的工作原理，我们首先将查看线上的CBOR项的结构。

CBOR项的解剖结构

这是线上CBOR项的简要解剖结构。

+------------+-----------+
|            |           |
|   Major    |   Minor   |
|  (3bits)   |  (5bits)  |
|            |           |
+------------+-----------+
^                        ^
|                        |
+-----+            +-----+
      |            |
      |            |
      +----------------------------+--------------+
      |            |               |              |
      |   Prefix   |     Affix     |    Suffix    |
      |  (1 byte)  |  (0-8 bytes)  |  (0+ bytes)  |
      |            |               |              |
      +------------+---------------+--------------+

      |                            |              |
      +------------+---------------+--------------+
                   |                       |
                   v                       v

                 Header                   Body

ciborium crate通过提供Decoder和Encoder类型，这些类型为CBOR头（见：Header）提供输入和输出。从那里，你可以自己处理主体或使用提供的实用函数。

有关CBOR格式的更多信息，请参阅RFC 7049。

解码

为了解码CBOR，你需要从一个读取器创建一个Decoder。解码实例将允许你从输入中提取Header实例。

大多数CBOR项完全包含在其头中，因此没有主体。这些项可以直接从Header实例中进行评估。

字节和文本项有主体但不含子项。由于字节和文本值都可能是分段，因此解析它们可能有点复杂。因此，我们提供了解析这些类型的辅助函数。有关更多详细信息，请参阅Decoder::bytes()和Decoder::text()。

数组和映射项包含子项的正文。这些可以通过简单地执行 Decoder::pull() 来解析子项。

示例

use ciborium_ll::{Decoder, Header};
use ciborium_io::Read as _;

let input = b"\x6dHello, World!";
let mut decoder = Decoder::from(&input[..]);
let mut chunks = 0;

match decoder.pull().unwrap() {
    Header::Text(len) => {
        let mut segments = decoder.text(len);
        while let Some(mut segment) = segments.pull().unwrap() {
            let mut buffer = [0u8; 7];
            while let Some(chunk) = segment.pull(&mut buffer[..]).unwrap() {
                 match chunk {
                     "Hello, " if chunks == 0 => chunks = 1,
                     "World!" if chunks == 1 => chunks = 2,
                     _ => panic!("received unexpected chunk"),
                 }
            }
        }
    }

    _ => panic!("received unexpected value"),
}

assert_eq!(chunks, 2);

编码

要将值编码为CBOR，从一个写入器创建一个 Encoder。编码器实例提供了一个 Encoder::push() 方法来将 Header 值写入线。CBOR项的正文可以直接写入。

对于字节和文本，有 Encoder::bytes() 和 Encoder::text() 工具函数，分别用于正确地分割输出。

示例

use ciborium_ll::{Encoder, Header};
use ciborium_io::Write as _;

let mut buffer = [0u8; 19];
let mut encoder = Encoder::from(&mut buffer[..]);

// Write the structure
encoder.push(Header::Map(Some(1))).unwrap();
encoder.push(Header::Positive(7)).unwrap();
encoder.text("Hello, World!", 7).unwrap();

// Validate our output
encoder.flush().unwrap();
assert_eq!(b"\xa1\x07\x7f\x67Hello, \x66World!\xff", &buffer[..]);

许可证：Apache-2.0