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 ¶
- Variables
- func Marshal(v interface{}) ([]byte, error)
- func MarshalAtlased(v interface{}, atl atlas.Atlas) ([]byte, error)
- func Unmarshal(cfg DecodeOptions, data []byte, v interface{}) error
- func UnmarshalAtlased(cfg DecodeOptions, data []byte, v interface{}, atl atlas.Atlas) error
- type DecodeOptions
- type Decoder
- type EncodeOptions
- type Encoder
- type ErrInvalidTokenStream
- type Marshaller
- type Unmarshaller
Constants ¶
This section is empty.
Variables ¶
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.
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.
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.
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.
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.
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 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)
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 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