Skip to content

v1.0.0

Choose a tag to compare

@zensh zensh released this 13 Jun 01:13
· 18 commits to main since this release

The first stable release, completing the rewrite that shipped as 0.5.0.

Added

  • no_std support behind the new std (default) and alloc features.
    default-features = false, features = ["alloc"] keeps the full API
    minus the std::io blanket implementations and the HashMap
    conversions; readers and writers are byte slices, Vec<u8>, or custom
    cbor2::io trait implementations. Without alloc the crate is a
    serialization/validation core: to_writer/to_slice/serialized_size,
    validate, the tag wrappers and the core header codec (the serde
    deserializer needs a heap; error messages composed at runtime are
    reduced to static ones).

  • to_slice: encodes into a caller-provided buffer and returns the
    written prefix, without allocating. Available in every configuration.

  • A RawValue type holding one item as validated, undecoded bytes (in
    the spirit of serde_json::value::RawValue): serialization splices
    the bytes into the stream untouched and deserialization captures them
    byte for byte — exact even for non-preferred spellings — for
    signature payloads, pass-through items and deferred decoding.
    TryFrom converts in both directions between RawValue and Value
    (decoding and encoding respectively).

  • CBOR tags on containers: #[cbor(tag = 18)] wraps a struct in a tag
    (required on decode), alongside the integer map keys of 0.5.0.

  • Value conversions to and from the common std types: From covers
    the primitive scalars, Option, byte arrays/vectors,
    String/&str/Cow<str>, HashMap/BTreeMap (any Into<Value>
    keys and values) and FromIterator into an array; TryFrom<Value>
    extracts every variant's payload, range-checked integers (the 128-bit
    forms accept bignums) and typed HashMap/BTreeMap with serde-style
    error messages.

  • A cbor2::Cbor trait implemented by #[derive(Cbor)] (sharing its
    name with the derive macro, serde-style), exposing the declared
    protocol details at runtime: T::KEYS (the field name → integer key
    pairs) and T::TAG as allocation-free constants, plus a
    keys(&self) -> BTreeMap<String, i128> convenience method with
    alloc.

  • The tools package, renamed from cbor_conv to cbor2-cli (published
    for the first time, also as 1.0.0), now ships a single cbor command
    line tool. Bare cbor shows each CBOR item as one line of diagnostic
    notation (RFC 8949 §8) with full wire fidelity — indefinite-length
    markers, undefined, bignums as plain integers; cbor decode
    pretty-prints items as JSON or, with --diag, as indented diagnostic
    notation; cbor encode converts JSON values to CBOR (replacing the
    old json2cbor/cbor2json binaries). The CBOR-reading commands take
    their input from stdin, a file, a hex string or a base64/base64url
    string, and everything is covered by end-to-end tests.

Changed

  • The serde Serializer/Deserializer now run over the cbor2::io
    reader/writer traits. With the default std feature these are
    implemented for every std::io::Write/Read and cbor2::io::Error
    is std::io::Error, so existing code is unaffected.
  • The derive feature's #[cbor2::int_keys] attribute macro is
    replaced by #[derive(cbor2::Cbor)], which generates the serde
    Serialize/Deserialize impls itself (serde's derives must not be
    repeated alongside it). Field names and the type name stay untouched —
    the protocol details ride on a hidden serde-remote shadow type — so
    the same types serialize to plain JSON with the original field names
    and no tag: serde_json::to_string(&v) just works.
  • Error types implement the error trait through serde::ser::StdError,
    which is std::error::Error whenever std is available.