Crate minicbor

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. Finally, the length in bytes of a value’s CBOR representation can be calculated if the value’s type implements the CborLen trait.

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.

Support for serde is available in minicbor-serde.

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": Allows deriving Encode and Decode traits.

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);

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()?;

Example: ad-hoc decoding

use minicbor::Decoder;
use minicbor::data::IanaTag;

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!(IanaTag::DateTime.tag(), decoder.tag()?);
assert_eq!("2013-03-21T20:04:00Z", decoder.str()?);

Example: tokenization

use minicbor::display;
use minicbor::{Encoder, Decoder};
use minicbor::data::Token;

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

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

let tokens = Decoder::new(&input).tokens().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)]
};

let mut buffer = [0u8; 9];
Encoder::new(buffer.as_mut()).tokens(&tokens)?;

assert_eq!(input, buffer);

Re-exports

• pub use decode::Decode;
• pub use decode::Decoder;
• pub use encode::Encode;
• pub use encode::Encoder;
• pub use encode::CborLen;

Modules

• bytes
  Newtypes for &[u8], [u8;N] and Vec<u8>.
• data
  CBOR data types, tokens and tags.
• decode
  Traits and types for decoding CBOR.
• encode
  Traits and types for encoding CBOR.

Functions

• decode
  Decode a type implementing Decode from the given byte slice.
• decode_with
  Decode a type implementing Decode from the given byte slice.
• display
  Display the given CBOR bytes in diagnostic notation.
• encode
  Encode a type implementing Encode to the given encode::Write impl.
• encode_with
  Encode a type implementing Encode to the given encode::Write impl.
• len
  Calculate the length in bytes of the given value’s CBOR representation.
• len_with
  Calculate the length in bytes of the given value’s CBOR representation.
• to_vec
  Encode a type implementing Encode and return the encoded byte vector.
• to_vec_with
  Encode a type implementing Encode and return the encoded byte vector.

Derive Macros

• CborLen
  Derive the minicbor::CborLen trait for a struct or enum.
• Decode
  Derive the minicbor::Decode trait for a struct or enum.
• Encode
  Derive the minicbor::Encode trait for a struct or enum.