cbor

package
v0.90.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 19, 2026 License: MIT Imports: 10 Imported by: 48

Documentation

Overview

Package implementing the CBOR -- Concise Binary Object Notation -- http://cbor.io/ -- spec.

CBOR is more or less freely interchangable with json: it's schemaless, and composed of similar map and array types. However, CBOR is binary, length delimited -- and thus very fast to parse, and can store binary data without expansion problems -- and also distinguishes types like integer, string, float, and bytes all clearly from each other.

The `cbor.Marshal` and `cbor.Unmarshal` functions are the quickest way to convert your Go objects to and from serial CBOR.

The `cbor.NewMarshaller` and `cbor.NewUmarshaller` functions give a little more control. If performance is important, prefer these; recycling the marshaller instances will significantly cut down on memory allocations and improve performance.

The `*Atlased` variants of constructors allow you set up marshalling with an `refmt/obj/atlas.Atlas`, unlocking all of refmt's advanced features and custom object mapping powertools.

The `cbor.Encoder` and `cbor.Decoder` types implement the low-level functionality of converting serial CBOR byte streams into refmt Token streams. Users don't usually need to use these directly.

Index

Constants

This section is empty.

Variables

View Source
var ErrFloatInfinity = errors.New("cbor: infinite float value rejected")

ErrFloatInfinity is returned by the decoder when an infinite float value is encountered and DecodeOptions.RejectInfinity is set.

View Source
var ErrFloatNaN = errors.New("cbor: NaN float value rejected")

ErrFloatNaN is returned by the decoder when a NaN float value is encountered and DecodeOptions.RejectNaN is set.

View Source
var ErrIndefiniteLength = errors.New("cbor: indefinite-length encoding rejected")

ErrIndefiniteLength is returned by the decoder when an indefinite-length encoding is encountered and DecodeOptions.RejectIndefinite is set.

View Source
var ErrIndefiniteSizeExceeded = errors.New("cbor: indefinite-length string/bytes total size exceeds limit")

ErrIndefiniteSizeExceeded is returned by the decoder when the cumulative size of an indefinite-length bytes or string value would exceed DecodeOptions.MaxIndefiniteSize.

View Source
var ErrNarrowFloat = errors.New("cbor: float narrower than 64 bits rejected")

ErrNarrowFloat is returned by the decoder when a 16-bit or 32-bit float encoding is encountered and DecodeOptions.RejectNarrowFloat is set.

View Source
var ErrNonMinimalInteger = errors.New("cbor: integer not minimally encoded")

ErrNonMinimalInteger is returned by the decoder when a CBOR head's integer argument is encoded in more bytes than necessary and DecodeOptions.RejectNonMinimalInteger is set.

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

func MarshalAtlased

func MarshalAtlased(v interface{}, atl atlas.Atlas) ([]byte, error)

func Unmarshal

func Unmarshal(cfg DecodeOptions, data []byte, v interface{}) error

func UnmarshalAtlased

func UnmarshalAtlased(cfg DecodeOptions, data []byte, v interface{}, atl atlas.Atlas) error

Types

type DecodeOptions

type DecodeOptions struct {
	CoerceUndefToNull bool

	// RejectIndefinite errors at the indefinite-length sigil byte (0x5f,
	// 0x7f, 0x9f, 0xbf) before any chunks are read or allocated.
	RejectIndefinite bool

	// MaxIndefiniteSize caps the cumulative size, in bytes, of an
	// indefinite-length bytes or string value during chunk aggregation.
	// Decoding errors when the running total would exceed this. When zero,
	// a default of 32 MiB is used (matching the per-chunk maximum, so
	// indefinite values can't grow larger in total than a single
	// definite-length value).
	MaxIndefiniteSize int

	// RejectNonMinimalInteger rejects CBOR heads whose integer argument is
	// encoded in more bytes than necessary. Applies to uints, negative
	// ints, length headers (bytes/strings/arrays/maps) and tag headers.
	RejectNonMinimalInteger bool

	// RejectNaN errors when a float value decodes to NaN, regardless of
	// which bit pattern was used to encode it.
	RejectNaN bool

	// RejectInfinity errors when a float value decodes to +Inf or -Inf.
	RejectInfinity bool

	// RejectNarrowFloat rejects 16-bit (0xf9) and 32-bit (0xfa) float
	// encodings at the sigil byte, before any payload is read.
	RejectNarrowFloat bool
}

DecodeOptions controls decoder behaviour. Rejection flags select stricter CBOR dialects; all are independent and off by default. Indefinite-length bytes and strings remain accepted by default, but their aggregate size is capped by MaxIndefiniteSize.

func (DecodeOptions) IsDecodeOptions

func (DecodeOptions) IsDecodeOptions()

marker method -- you may use this type to instruct `refmt.Marshal` what kind of encoder to use.

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

func NewDecoder

func NewDecoder(cfg DecodeOptions, r io.Reader) (d *Decoder)

func (*Decoder) Reset

func (d *Decoder) Reset()

func (*Decoder) Step

func (d *Decoder) Step(tokenSlot *Token) (done bool, err error)

type EncodeOptions

type EncodeOptions struct {
}

func (EncodeOptions) IsEncodeOptions

func (EncodeOptions) IsEncodeOptions()

marker method -- you may use this type to instruct `refmt.Marshal` what kind of encoder to use.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

func NewEncoder

func NewEncoder(w io.Writer) (d *Encoder)

func (*Encoder) Reset

func (d *Encoder) Reset()

func (*Encoder) Step

func (d *Encoder) Step(tokenSlot *Token) (done bool, err error)

type ErrInvalidTokenStream

type ErrInvalidTokenStream struct {
	Got        Token
	Acceptable []TokenType
}

Error raised by Encoder when invalid tokens or invalid ordering, e.g. a MapClose with no matching open. Should never be seen by the user in practice unless generating their own token streams.

func (*ErrInvalidTokenStream) Error

func (e *ErrInvalidTokenStream) Error() string

type Marshaller

type Marshaller struct {
	// contains filtered or unexported fields
}

func NewMarshaller

func NewMarshaller(wr io.Writer) *Marshaller

func NewMarshallerAtlased

func NewMarshallerAtlased(wr io.Writer, atl atlas.Atlas) *Marshaller

func (*Marshaller) Marshal

func (x *Marshaller) Marshal(v interface{}) error

type Unmarshaller

type Unmarshaller struct {
	// contains filtered or unexported fields
}

func NewUnmarshaller

func NewUnmarshaller(cfg DecodeOptions, r io.Reader) *Unmarshaller

func NewUnmarshallerAtlased

func NewUnmarshallerAtlased(cfg DecodeOptions, r io.Reader, atl atlas.Atlas) *Unmarshaller

func (*Unmarshaller) Unmarshal

func (x *Unmarshaller) Unmarshal(v interface{}) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL