Skip to content

v2.0.0 (Feb 2, 2020)

Choose a tag to compare

View all tags
@fxamacker fxamacker released this 03 Feb 05:47
v2.0.0
158e531
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode.

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 decoupled options from encoding/decoding functions so that:

  • new features like CBOR tags can be added without breaking API changes.
  • more encoding/decoding function signatures are identical to encoding/json.
  • more function signatures can remain stable forever even as CBOR options & tags evolve.

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

More function signatures match encoding/json. These will never change their parameters or return types:
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
Assets 2
Loading