Crate tinycbor

Crate tinycbor 

Source
Expand description

A minimal CBOR implementation.

This was designed from scratch, but is inspired by minicbor.

§Overview

This crate is organised around the following traits:

  • Decode: Decode types from CBOR. This is equivalent to Deserialize in serde.
  • Encode: Encode types to CBOR. This is equivalent to Serialize in serde.
  • CborLen: Calculate the length of a type’s CBOR encoding without encoding it.

One can derive these traits on a type using tinycbor-derive, or implement them manually.

§Feature flags

  • alloc: Enables support for types in the alloc crate, such as Vec, Box, Cow, etc.
  • std: Implies alloc, and adds implementations for types and collections only available in the standard library.

§Example

A simple encoding and decoding round-trip:

use tinycbor::{Encode, Decode, Encoder, Decoder};

let input = ["hello", "world"];
let mut buffer = [0u8; 128];
input.encode(&mut Encoder(buffer.as_mut()))?;

let output: [&str; 2] = Decode::decode(&mut Decoder(&buffer))?;
assert_eq!(input, output);

§Design Axioms

  • Simplicity.

This means reducing the number of lines of code at the cost of functionality.

  • Correctness.

If it is possible to design a simple abstraction that enforces correct usage patterns at compile time, we prefer that. Compared to minicbor, the Encoder and Decoder types try to minimize the number of methods that can lead to invalid CBOR encodings or decoding errors. For example, the Decoder exposes array_visitor, which allows iterating over the contents of and array. Note that correctness is not enforced when the required solution is too complex. For example, ArrayVisitor does not ensure that the decoder is in a consistent state if the ArrayVisitor is dropped before reaching the end of the array. Encoder also exposes methods to encode the header of an array, without enforcing that the correct number of elements are encoded.

  • Infallible encoding.

The Encode trait does not support returning encoding errors. The only errors returned are those generated by the underlying W: Write.

  • User defined decoding errors.

The Decode trait has an associated Error type, allowing for better user-defined error types. When deriving Decode, an error type is also generated.

  • Strict decoding.

Compared to ciborium and minicbor, which follow the “robustness principle”, this library is stricter in what it accepts when impelenting Decode with the derive macro. By default, arrays containing extra elements are rejected, and default values are not used when a field is missing.

  • Use smallest numeric representation when encoding.

Integers and floats are encoded using the smallest possible representation that does not lose precision. For example, 16u64 is encoded as a u8, and 1.0f32 is encoded as a f16.

Modules§

container
Containers.
num
Numeric types.
primitive
Primitive types.
string
Text.
tag
Tagged values.

Structs§

Any
Decodes any CBOR data item, keeping its original encoding.
ArrayVisitor
A visitor for decoding array elements of different types.
BytesIter
An iterator over byte slices.
Decoder
A CBOR decoder.
Encoded
Encodes as a tagged byte string, where the content is the CBOR encoding of T.
Encoder
A non-allocating CBOR encoder writing encoded bytes to the given Write sink.
EndOfInput
Unexpected end of input.
InvalidHeader
The CBOR header (first byte) is invalid or malformed.
MapVisitor
A visitor for decoding map key-value pairs of different types.
StrIter
Iterate over string slices.

Enums§

Token
Representation of possible CBOR tokens.
Type
CBOR data type.

Traits§

CborLen
A type that can calculate its own CBOR encoding length.
Decode
A type that can be decoded from CBOR.
Encode
A type that can be encoded to CBOR.
Write
Blocking writer.

Functions§

to_vec
Encode a type implementing Encode and return the encoded byte vector.