cbor

Documentation

Overview

Package cbor implements partial encoding/decoding of concise binary object representation (CBOR) described in RFC 8949.

This package is intended for use only by the smithy client runtime. The exported API therein is not considered stable and is subject to breaking changes without notice. More specifically, this package implements a subset of the RFC 8949 specification required to support the Smithy RPCv2-CBOR protocol and is NOT suitable for general application use.

The following principal restrictions apply:

• Map (major type 5) keys can only be strings.
• Float16 (major type 7, 25) values can be read but not encoded. Any float16 encountered during decode is converted to float32.
• Indefinite-length values can be read but not encoded. Since the encoding API operates strictly off of a constructed syntax tree, the length of each data item in a Value will always be known and the encoder will always generate definite-length variants.

It is the responsibility of the caller to determine whether a decoded CBOR integral or floating-point Value is suitable for its target (e.g. whether the value of a CBOR Uint fits into a field modeled as a Smithy short).

All CBOR tags (major type 6) are implicitly supported since the encoder/decoder does not attempt to interpret a tag's contents. It is the responsibility of the caller to both provide valid Tag values to encode and to assert that a decoded Tag's contents are valid for its tag ID (e.g. ensuring whether a Tag with ID 1, indicating an enclosed epoch timestamp, actually contains a valid integral or floating-point CBOR Value).

Index

• func AsBigInt(v Value) (*big.Int, error)
• func AsFloat32(v Value) (float32, error)
• func AsFloat64(v Value) (float64, error)
• func AsInt16(v Value) (int16, error)
• func AsInt32(v Value) (int32, error)
• func AsInt64(v Value) (int64, error)
• func AsInt8(v Value) (int8, error)
• func AsTime(v Value) (time.Time, error)
• func Encode(v Value) []byte
• type Bool
• type EncodeFixedNegInt
• type EncodeFixedUint
• type EncodeRaw
• type Float32
• type Float64
• type List
• type Map
• type NegInt
• type Nil
• type Slice
• type String
• type Tag
• type Uint
• type Undefined
• type Value
  • func Decode(p []byte) (Value, error)

Functions

func AsBigInt

func AsBigInt(v Value) (*big.Int, error)

AsBigInt coerces a Value to its big.Int representation if possible.

A BigInt may be represented by any of the following:

• Uint
• NegInt
• Tag (type 2/3, where tagged value is a Slice)
• Nil

func AsFloat32

func AsFloat32(v Value) (float32, error)

AsFloat32 coerces a Value to its float32 representation if possible.

A float32 may be represented by any of the following alternatives:

• cbor uint (if within lossless range)
• cbor -int (if within lossless range)

func AsFloat64

func AsFloat64(v Value) (float64, error)

AsFloat64 coerces a Value to its float64 representation if possible.

A float64 may be represented by any of the following alternatives:

• float32
• cbor uint (if within lossless range)
• cbor -int (if within lossless range)

func AsInt16

func AsInt16(v Value) (int16, error)

AsInt16 coerces a Value to its int16 representation if possible.

func AsInt32

func AsInt32(v Value) (int32, error)

AsInt32 coerces a Value to its int32 representation if possible.

func AsInt64

func AsInt64(v Value) (int64, error)

AsInt64 coerces a Value to its int64 representation if possible.

func AsInt8

func AsInt8(v Value) (int8, error)

AsInt8 coerces a Value to its int8 representation if possible.

func AsTime

func AsTime(v Value) (time.Time, error)

AsTime coerces a Value to its time.Time representation if possible.

This coercion will check that the given Value is a Tag with the registered number (1) for epoch time. The value for time.Time within that tag may be derived from any of the following:

• float32
• float64
• cbor uint (within int64 bounds)
• cbor -int (within int64 bounds)

Tag number 0 (date-time RFC3339) is not supported.

func Encode

func Encode(v Value) []byte

Encode returns a byte slice that encodes the given Value.

Types

type Bool

type Bool bool

Bool describes a boolean value (major type 7, argument 20/21).

type EncodeFixedNegInt

type EncodeFixedNegInt uint64

FixedUint encodes fixed-width NegInt values.

This is used by the encoder for the purpose of embedding integrals in document shapes. Decode will never return values of this type.

type EncodeFixedUint

type EncodeFixedUint uint64

FixedUint encodes fixed-width Uint values.

This is used by the encoder for the purpose of embedding integrals in document shapes. Decode will never return values of this type.

type EncodeRaw

type EncodeRaw []byte

EncodeRaw encodes opaque CBOR data.

This is used by the encoder for the purpose of embedding document shapes. Decode will never return values of this type.

type Float32

type Float32 float32

Float32 describes an IEEE 754 single-precision floating-point number (major type 7, argument 26).

Go does not natively support float16, all values encoded as such (major type 7, argument 25) must be represented by this variant instead.

type Float64

type Float64 float64

Float64 describes an IEEE 754 double-precision floating-point number (major type 7, argument 27).

type List

type List []Value

List describes a CBOR list (major type 4).

type Map

type Map map[string]Value

Map describes a CBOR map (major type 5).

The type signature of the map's key is restricted to string as it is in Smithy.

type NegInt

type NegInt uint64

NegInt describes a CBOR negative int (major type 1) in the range [-2^64, -1].

The "true negative" value of a type 1 is specified by RFC 8949 to be -1 minus the encoded value. The encoder/decoder applies this bias automatically, e.g. the integral -100 is represented as NegInt(100), which will which encode to/from hex 3863 (major 1, minor 24, argument 99).

This implicitly means that the lower bound of this type -2^64 is represented as the wraparound value NegInt(0). Deserializer implementations should take care to guard against this case when deriving a value for a signed integral type which was encoded as NegInt.

type Nil

type Nil struct{}

Nil is the `nil` / `null` literal (major type 7, argument 22).

type Slice

type Slice []byte

Slice describes a CBOR byte slice (major type 2).

type String

type String string

String describes a CBOR text string (major type 3).

type Tag

type Tag struct {
	ID    uint64
	Value Value
}

Tag describes a CBOR-tagged value (major type 6).

type Uint

type Uint uint64

Uint describes a CBOR uint (major type 0) in the range [0, 2^64-1].

type Undefined

type Undefined struct{}

Undefined is the `undefined` literal (major type 7, argument 23).

type Value

type Value interface {
	// contains filtered or unexported methods
}

Value describes a CBOR data item.

The following types implement Value:

• Uint
• NegInt
• Slice
• String
• List
• Map
• Tag
• Bool
• Nil
• Undefined
• Float32
• Float64

func Decode

func Decode(p []byte) (Value, error)

Decode returns the Value encoded in the given byte slice.