minicbor

A small CBOR codec suitable for no_std environments.

Documentation

Documentation is available at

• https://twittner.gitlab.io/minicbor/minicbor/
• https://docs.rs/minicbor/

License

This software is licensed under the Blue Oak Model License Version 1.0.0. If you are interested in contributing to this project, please read the file CONTRIBUTING.md first.

lib.rs:

A small CBOR codec suitable for no_std environments.

The crate is organised around the following entities:

• [Encoder] and [Decoder] for type-directed encoding and decoding of values.

• [Encode] and [Decode] traits which can be implemented for any type that should be encoded to or decoded from CBOR. They are similar to serde's Serialize and Deserialize traits but do not abstract over the encoder/decoder.

Encoding and decoding proceeds in a type-directed way, i.e. by calling methods for expected data item types, e.g. [Decoder::u32] or [Encoder::str]. In addition there is support for data type inspection. The Decoder can be queried for the current data type which returns a [data::Type] that can represent every possible CBOR type and decoding can thus proceed based on this information. It is also possible to just tokenize the input bytes using a Tokenizer, i.e. an Iterator over CBOR Tokens.

Optionally, Encode and Decode can be derived for structs and enums using the respective derive macros (requires feature "derive"). See [minicbor_derive] for details.

For I/O support see minicbor-io.

Feature flags

The following feature flags are supported:

• "alloc": Enables most collection types in a no_std environment.

• "std": Implies "alloc" and enables more functionality that depends on the std crate.

• "derive": Implies "alloc" and allows deriving [Encode] and [Decode] traits.

• "partial-skip-support": Enables the method [Decoder::skip] to skip over any CBOR item other than indefinite-length arrays or maps inside of regular maps or arrays. Support for skipping over any CBOR item is enabled by "alloc" but without"alloc" or "partial-skip-support" Decoder::skip is not available at all.

• "partial-derive-support": Implies "partial-skip-support" and allows deriving [Encode] and [Decode] traits, but does not support indefinite-length CBOR maps and arrays inside of regular CBOR maps and arrays.

Example: generic encoding and decoding

use minicbor::{Encode, Decode};

let input = ["hello", "world"];
let mut buffer = [0u8; 128];

minicbor::encode(&input, buffer.as_mut())?;
let output: [&str; 2] = minicbor::decode(buffer.as_ref())?;
assert_eq!(input, output);

# Ok::<_, Box<dyn std::error::Error>>(())

Example: ad-hoc encoding

use minicbor::Encoder;

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

encoder.begin_map()? // using an indefinite map here
    .str("hello")?.str("world")?
    .str("submap")?.map(2)?
        .u8(1)?.bool(true)?
        .u8(2)?.bool(false)?
    .u16(34234)?.array(3)?.u8(1)?.u8(2)?.u8(3)?
    .bool(true)?.null()?
.end()?;

# Ok::<_, Box<dyn std::error::Error>>(())

Example: ad-hoc decoding

use minicbor::Decoder;
use minicbor::data::Tag;

let input = [
    0xc0, 0x74, 0x32, 0x30, 0x31, 0x33, 0x2d, 0x30,
    0x33, 0x2d, 0x32, 0x31, 0x54, 0x32, 0x30, 0x3a,
    0x30, 0x34, 0x3a, 0x30, 0x30, 0x5a
];

let mut decoder = Decoder::new(&input);
assert_eq!(Tag::DateTime, decoder.tag()?);
assert_eq!("2013-03-21T20:04:00Z", decoder.str()?);
# Ok::<_, Box<dyn std::error::Error>>(())

Example: tokenization

use minicbor::display;
use minicbor::decode::{Token, Tokenizer};

let input  = [0x83, 0x01, 0x9f, 0x02, 0x03, 0xff, 0x82, 0x04, 0x05];

assert_eq!("[1, [_ 2, 3], [4, 5]]", format!("{}", display(&input)));

let tokens = Tokenizer::new(&input).collect::<Result<Vec<Token>, _>>()?;

assert_eq! { &tokens[..],
    &[Token::Array(3),
      Token::U8(1),
      Token::BeginArray,
      Token::U8(2),
      Token::U8(3),
      Token::Break,
      Token::Array(2),
      Token::U8(4),
      Token::U8(5)]
};

# Ok::<_, Box<dyn std::error::Error>>(())