ยซ Changelog History


cbor v2.0.0 Release Notes

Release Date: 2020-02-03 // about 4 years ago

  • ๐Ÿ”„ Changes in v2.0:

    • ๐Ÿ‘Œ Improved API.
    • ๐ŸŽ Faster performance.
    • โฌ‡๏ธ Reduced memory usage.
    • ๐Ÿ‘Œ Improved code quality using around 20 linters.
    • Replaced EncOptions.TimeRFC3339 bool with TimeMode (5 settings).
    • Decode NaN and Infinity time values to Go's "zero time" value.
    • โœ‚ Removed deprecated v1 options and Valid() function.
    • Many improvements to README.md.

    Why 2.0?

    v2.0 was needed to simplify adding new features planned for v2.1 and v2.2.

    Roadmap

    • ๐Ÿ‘ v2.1 (Feb. 9, 2020) support for CBOR tags (major type 6) and some decoder optimizations.
    • v2.2 (Feb. 2020) options for handling duplicate map keys.

    ๐Ÿšš CBOR Tags (major type 6) was moved to milestone v2.1. and is over 50% done.

    Status

    ๐Ÿš€ v2.0 passed 1+ billion execs in coverage-guided fuzzing before release. This is the most well-tested and most reliable release of this library. Upgrading is highly recommended.

    ๐Ÿ‘Œ Improved API

    In v2, more function signatures match encoding/json. These are the most widely used:
    Marshal, Unmarshal, NewEncoder, NewDecoder, encoder.Encode, decoder.Decode.

    "Mode" in this API means definite way of encoding or decoding.

    EncMode and DecMode are interfaces created from EncOptions or DecOptions structs.

    EncMode and DecMode use immutable options so their behavior won't accidentally change at runtime. Modes are intended to be reused and are safe for concurrent use.

    // Create EncOptions, using either struct literal or a function.
opts := cbor.CanonicalEncOptions()

// If needed, modify options -- e.g. how time values should be encoded.
opts.Time = cbor.TimeUnix

// Create reusable EncMode interface with immutable options, safe for concurrent use.
em, err := opts.EncMode()   

// Use EncMode like encoding/json, with same function signatures.
b, err := em.Marshal(v)
// or
encoder := em.NewEncoder(w)
err := encoder.Encode(v)

    ๐Ÿ“ฆ Package Level Functions

    ๐Ÿ“ฆ These package level functions use default options without CBOR tags. Their API matches encoding/json. EncMode and DecMode also provide these functions with same signatures.

    b, err := cbor.Marshal(v)
err := cbor.Unmarshal(b, &v)
encoder := cbor.NewEncoder(w)
decoder := cbor.NewDecoder(r)

    EncOptions.Time

    Replaced EncOptions.TimeRFC3339 bool with TimeMode:

    • TimeUnix // secs, encodes to CBOR integer using fewest bytes
    • TimeUnixMicro // ฮผs, encodes to CBOR float with subsecs in fractional part
    • TimeUnixDynamic // secs or ฮผs, encodes to either int or float depending on empty subsecs
    • TimeRFC3339 // secs, encodes to string
    • ๐Ÿšš TimeRFC3339Nano // ns, encodes to string with trailing zeros removed