cboring

README

cboring

Simple CBOR Go(lang) library for a selected subset of features, developed to be used in dtn7-go, an implementation of the Bundle Protocol Version 7. The name is based on the fact that cboring is both boring to use and bored about the amount of data to handle.

Features

• Supports a selected subset of CBOR's features:
  • Unsigned Integer
  • Floating-point values
  • Byte and Text String
  • Arrays, both of definite and indefinite length
  • Maps of definite length
  • Booleans
• Small and clear codebase:
  • Only works on streams, Go's io.Reader or io.Writer
  • Does not use reflection or makes any strange assumptions
• Surprisingly fast

Documentation

Index

• Constants
• func Marshal(data CborMarshaler, w io.Writer) error
• func ReadArrayLength(r io.Reader) (n uint64, err error)
• func ReadBoolean(r io.Reader) (b bool, err error)
• func ReadByteString(r io.Reader) (data []byte, err error)
• func ReadByteStringLen(r io.Reader) (n uint64, err error)
• func ReadExpect(b byte, r io.Reader) error
• func ReadExpectMajors(m MajorType, r io.Reader) (n uint64, err error)
• func ReadFloat32(r io.Reader) (f float32, err error)
• func ReadFloat64(r io.Reader) (f float64, err error)
• func ReadMapPairLength(r io.Reader) (n uint64, err error)
• func ReadRawBytes(l uint64, r io.Reader) (data []byte, err error)
• func ReadTextString(r io.Reader) (data string, err error)
• func ReadTextStringLen(r io.Reader) (n uint64, err error)
• func ReadUInt(r io.Reader) (n uint64, err error)
• func Unmarshal(data CborMarshaler, r io.Reader) error
• func WriteArrayLength(n uint64, w io.Writer) error
• func WriteBoolean(b bool, w io.Writer) (err error)
• func WriteByteString(data []byte, w io.Writer) error
• func WriteByteStringLen(n uint64, w io.Writer) error
• func WriteFloat32(f float32, w io.Writer) (err error)
• func WriteFloat64(f float64, w io.Writer) (err error)
• func WriteMajors(m MajorType, n uint64, w io.Writer) (err error)
• func WriteMapPairLength(n uint64, w io.Writer) error
• func WriteTextString(data string, w io.Writer) error
• func WriteTextStringLen(n uint64, w io.Writer) error
• func WriteUInt(n uint64, w io.Writer) error
• type CborMarshaler
• type Flag
  • func (f Flag) Error() string
• type MajorType
  • func ReadMajors(r io.Reader) (m MajorType, n uint64, err error)

Constants

const (
	IndefiniteArray byte = 0x9F
	BreakCode       byte = 0xFF
)

const (
	FlagIndefiniteArray = Flag(iota)
	FlagBreakCode       = Flag(iota)
)

Functions

func Marshal

func Marshal(data CborMarshaler, w io.Writer) error

Marshal writes a CBOR representation of a CborMarshaler into the Writer.

func ReadArrayLength

func ReadArrayLength(r io.Reader) (n uint64, err error)

ReadArrayLength expects an array at the Reader's position and returns its length.

func ReadBoolean

func ReadBoolean(r io.Reader) (b bool, err error)

ReadBoolean reads a bool value from the Reader.

func ReadByteString

func ReadByteString(r io.Reader) (data []byte, err error)

ReadByteStringLen expects a byte string at the Reader's position and returns the byte string.

func ReadByteStringLen

func ReadByteStringLen(r io.Reader) (n uint64, err error)

ReadByteStringLen expects a byte string at the Reader's position and returns the byte string's length.

func ReadExpect

func ReadExpect(b byte, r io.Reader) error

ReadExpect reads one byte from the Reader and errors if it does not contain the expected value. This might be useful to check if an indefinite-length array begins or ends with an break stop code.

func ReadExpectMajors

func ReadExpectMajors(m MajorType, r io.Reader) (n uint64, err error)

ReadExpectMajors parses the next (major) type, which must equal the requested one. This function wraps ReadMajors.

func ReadFloat32

func ReadFloat32(r io.Reader) (f float32, err error)

ReadFloat32 reads a float32 value from the Reader.

func ReadFloat64

func ReadFloat64(r io.Reader) (f float64, err error)

ReadFloat64 reads a float64 value from the Reader.

func ReadMapPairLength

func ReadMapPairLength(r io.Reader) (n uint64, err error)

ReadMapPairLength expects a map at the Reader's position and returns the amount of pairs stored.

func ReadRawBytes

func ReadRawBytes(l uint64, r io.Reader) (data []byte, err error)

ReadRawBytes reads the next l bytes from r into a new byte slice.

func ReadTextString

func ReadTextString(r io.Reader) (data string, err error)

ReadTextStringLen expects a text string at the Reader's position and returns the text string.

func ReadTextStringLen

func ReadTextStringLen(r io.Reader) (n uint64, err error)

ReadTextStringLen expects a text string at the Reader's position and returns the text string's length.

func ReadUInt

func ReadUInt(r io.Reader) (n uint64, err error)

ReadUInt expects an unsigned integer at the Reader's position and returns it.

func Unmarshal

func Unmarshal(data CborMarshaler, r io.Reader) error

Unmarshal reads a CBOR representation from a Reader into a CborMarshaler.

func WriteArrayLength

func WriteArrayLength(n uint64, w io.Writer) error

WriteArrayLength writes the type definition for an array with the given length into the Writer.

func WriteBoolean

func WriteBoolean(b bool, w io.Writer) (err error)

WriteBoolean writes a bool into the Writer.

func WriteByteString

func WriteByteString(data []byte, w io.Writer) error

WriteByteString writes a byte string into the Writer.

func WriteByteStringLen

func WriteByteStringLen(n uint64, w io.Writer) error

WriteByteStringLen writes the type definition for a byte string with the given length into the Writer.

func WriteFloat32

func WriteFloat32(f float32, w io.Writer) (err error)

WriteFloat32 writes a float32 into the Writer.

func WriteFloat64

func WriteFloat64(f float64, w io.Writer) (err error)

WriteFloat64 writes a float64 into the Writer.

func WriteMajors

func WriteMajors(m MajorType, n uint64, w io.Writer) (err error)

WriteMajors composes a (major) type definition into the Writer.

func WriteMapPairLength

func WriteMapPairLength(n uint64, w io.Writer) error

WriteMapPairLength writes the type definition for a map with the given amount of pairs into the Writer.

func WriteTextString

func WriteTextString(data string, w io.Writer) error

WriteTextString writes a byte string into the Writer.

func WriteTextStringLen

func WriteTextStringLen(n uint64, w io.Writer) error

WriteTextStringLen writes the type definition for a text string with the given length into the Writer.

func WriteUInt

func WriteUInt(n uint64, w io.Writer) error

WriteUInt serializes an unsigned integer into the Writer.

Types

type CborMarshaler

type CborMarshaler interface {
	MarshalCbor(w io.Writer) error
	UnmarshalCbor(r io.Reader) error
}

CborMarshaler is the interface implemented by an object that can both marshal itself into a CBOR form and unmarshal a CBOR representation of itself.

type Flag

type Flag byte

func (Flag) Error

func (f Flag) Error() string

type MajorType

type MajorType = byte

MajorType defines a Major Type, as specified in RFC7049, section 2.1

const (
	UInt       MajorType = 0x00
	ByteString MajorType = 0x40
	TextString MajorType = 0x60
	Array      MajorType = 0x80
	Map        MajorType = 0xA0
	SimpleData MajorType = 0xE0
)

func ReadMajors

func ReadMajors(r io.Reader) (m MajorType, n uint64, err error)

ReadMajors parses a (major) type definition from the Reader.