Crate cbor_event 

CBOR event library

cbor_event is a minimalist CBOR implementation of the CBOR binary serialisation format. It provides a simple yet efficient way to parse CBOR without the need for an intermediate type representation.

Here is the list of supported CBOR primary Type:

• Unsigned and Negative Integers;

• Bytes and UTF8 String (of finite and indefinite size);

• Array and Map (of finite and indefinite size);

• Tag;

• Specials (bool, null, floating points, …). The raw float readers accept any width (f16/f32/f64): Deserializer::float discards the head width, while the width-preserving pair Deserializer::float_sz/Serializer::write_float_sz round-trips any encoding byte-exactly (NaN payloads included). Special::Float serializes as f64.

  The Deserialize/Serialize impls for f32/f64 follow the integer impls: decoding accepts any float head and errors only when the value does not fit the type (Error::ExpectedF32 instead of rounding), and encoding writes the smallest width that preserves the value (RFC 8949 §4.1 preferred serialization). Use the width-preserving pair above to pin a width.

Round-trip guarantees

Round-trip means two different things here:

• value round-trip (value -> bytes -> value): what was serialized re-decodes bit-exactly, NaN payloads, map entry order and duplicate keys included. Every layer guarantees this: the typed Serialize/Deserialize impls, the raw Serializer/Deserializer methods, and Value.
• byte round-trip (bytes -> decoded form -> bytes): re-encoding reproduces the identical bytes for any well-formed input, including non-shortest heads and indefinite-length string chunking. Only the width-preserving _sz pairs guarantee this; every reader has one (Deserializer::unsigned_integer_sz, negative_integer_sz, Deserializer::float_sz, Deserializer::bytes_sz, Deserializer::text_sz, array_sz, map_sz, tag_sz, with their Serializer::write_*_sz counterparts), returning the head width (and for strings the chunk structure) alongside the value.

Everything else normalizes the encoding on re-encode: the typed impls write preferred serialization (RFC 8949 §4.1) and Value normalizes as documented on the type, so non-shortest-form input comes back with different bytes even though the value is identical.

Raw deserialisation: Deserializer

Deserialisation works by consuming a Deserializer content. To avoid performance issues some objects use a reference to the original source Deserializer internal buffer.

use cbor_event::de::*;

let vec = vec![0x43, 0x01, 0x02, 0x03];
let mut raw = Deserializer::from(vec);
let bytes = raw.bytes().unwrap();

For convenience, we provide the trait Deserialize to help writing simpler deserializers for your types.

Serialisation: Serializer

To serialise your objects into CBOR we provide a simple object Serializer. It is meant to be simple to use and to have limited overhead.

use cbor_event::se::{Serializer};

let mut serializer = Serializer::new_vec();
serializer.write_negative_integer(-12)
    .expect("write a negative integer");

Re-exports

pub use crate::de::Deserialize;

pub use crate::se::Serialize;

Modules

de

CBOR deserialisation tooling

se

CBOR serialisation tooling

Macros

cbor

macro to efficiently serialise the given structure into cbor binary.

Enums

Error

all expected error for cbor parsing and serialising

Len

CBOR len: either a fixed size or an indefinite length.

LenSz

CBOR length with encoding details

Special

CBOR special (as in Special Primary Type).

SpecialValue

CBOR special values as they exist in the data model (RFC 8949 §2): Special minus Break. Break is a wire-level terminator for indefinite-length containers, not a data item (RFC 8949 Appendix C), so Value stores this type instead, making a dangling Break unrepresentable.

StringLenSz

Encoding for the length of a string (text or bytes)

Sz

How many bytes are used in CBOR encoding for a major type/length

Type

CBOR Major Types

Value

All possible CBOR supported values.

Functions

test_encode_decode

exported as a convenient function to test the implementation of Serialize and Deserialize.

Type Aliases

Result

Result type for CBOR serialisation and deserialisation.