marshalhash

package
v2.0.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Jan 24, 2019 License: MIT Imports: 18 Imported by: 4

Documentation

Overview

This package is the support library for the hsp code generator (http://github.com/CovenantSQL/HashStablePack).

This package defines the utilites used by the hsp code generator for encoding and decoding MessagePack from []byte and io.Reader/io.Writer types. Much of this package is devoted to helping the hsp code generator implement the Marshaler/Unmarshaler and Encodable/Decodable interfaces.

This package defines four "families" of functions:

  • AppendXxxx() appends an object to a []byte in MessagePack encoding.
  • ReadXxxxBytes() reads an object from a []byte and returns the remaining bytes.
  • (*Writer).WriteXxxx() writes an object to the buffered *Writer type.
  • (*Reader).ReadXxxx() reads an object from a buffered *Reader type.

Once a type has satisfied the `Encodable` and `Decodable` interfaces, it can be written and read from arbitrary `io.Writer`s and `io.Reader`s using

hsp.Encode(io.Writer, hsp.Encodable)

and

hsp.Decode(io.Reader, hsp.Decodable)

There are also methods for converting MessagePack to JSON without an explicit de-serialization step.

For additional tips, tricks, and gotchas, please visit the wiki at http://github.com/CovenantSQL/HashStablePack

Index

Constants

View Source
const (
	// Complex64Extension is the extension number used for complex64
	Complex64Extension = 3

	// Complex128Extension is the extension number used for complex128
	Complex128Extension = 4

	// TimeExtension is the extension number used for time.Time
	TimeExtension = 5
)
View Source
const (
	Int64Size      = 9
	IntSize        = Int64Size
	UintSize       = Int64Size
	Int8Size       = 2
	Int16Size      = 3
	Int32Size      = 5
	Uint8Size      = 2
	ByteSize       = Uint8Size
	Uint16Size     = 3
	Uint32Size     = 5
	Uint64Size     = Int64Size
	Float64Size    = 9
	Float32Size    = 5
	Complex64Size  = 10
	Complex128Size = 18

	TimeSize = 15
	BoolSize = 1
	NilSize  = 1

	MapHeaderSize   = 5
	ArrayHeaderSize = 5

	BytesPrefixSize     = 5
	StringPrefixSize    = 5
	ExtensionPrefixSize = 6
)

The sizes provided are the worst-case encoded sizes for each type. For variable- length types ([]byte, string), the total encoded size is the prefix size plus the length of the object.

Variables

View Source
var (
	// ErrShortBytes is returned when the
	// slice being decoded is too short to
	// contain the contents of the message
	ErrShortBytes error = errShort{}
)
View Source
var (
	// Nowhere is an io.Writer to nowhere
	Nowhere io.Writer = nwhere{}
)

Functions

func AppendArrayHeader

func AppendArrayHeader(b []byte, sz uint32) []byte

AppendArrayHeader appends an array header with the given size to the slice

func AppendBool

func AppendBool(b []byte, t bool) []byte

AppendBool appends a bool to the slice

func AppendByte

func AppendByte(b []byte, u byte) []byte

AppendByte is analogous to AppendUint8

func AppendBytes

func AppendBytes(b []byte, bts []byte) []byte

AppendBytes appends bytes to the slice as MessagePack 'bin' data

func AppendComplex128

func AppendComplex128(b []byte, c complex128) []byte

AppendComplex128 appends a complex128 to the slice as a MessagePack extension

func AppendComplex64

func AppendComplex64(b []byte, c complex64) []byte

AppendComplex64 appends a complex64 to the slice as a MessagePack extension

func AppendExtension

func AppendExtension(b []byte, e Extension) ([]byte, error)

AppendExtension appends a MessagePack extension to the provided slice

func AppendFloat32

func AppendFloat32(b []byte, f float32) []byte

AppendFloat32 appends a float32 to the slice

func AppendFloat64

func AppendFloat64(b []byte, f float64) []byte

AppendFloat64 appends a float64 to the slice

func AppendInt

func AppendInt(b []byte, i int) []byte

AppendInt appends an int to the slice

func AppendInt16

func AppendInt16(b []byte, i int16) []byte

AppendInt16 appends an int16 to the slice

func AppendInt32

func AppendInt32(b []byte, i int32) []byte

AppendInt32 appends an int32 to the slice

func AppendInt64

func AppendInt64(b []byte, i int64) []byte

AppendInt64 appends an int64 to the slice

func AppendInt8

func AppendInt8(b []byte, i int8) []byte

AppendInt8 appends an int8 to the slice

func AppendIntf

func AppendIntf(b []byte, i interface{}) ([]byte, error)

AppendIntf appends the concrete type of 'i' to the provided []byte. 'i' must be one of the following:

  • 'nil'
  • A bool, float, string, []byte, int, uint, or complex
  • A map[string]interface{} or map[string]string
  • A []T, where T is another supported type
  • A *T, where T is another supported type
  • A type that satisfieds the hsp.Marshaler interface
  • A type that satisfies the hsp.Extension interface

func AppendMapHeader

func AppendMapHeader(b []byte, sz uint32) []byte

AppendMapHeader appends a map header with the given size to the slice

func AppendMapStrIntf

func AppendMapStrIntf(b []byte, m map[string]interface{}) ([]byte, error)

AppendMapStrIntf appends a map[string]interface{} to the slice as a MessagePack map with 'str'-type keys.

func AppendMapStrStr

func AppendMapStrStr(b []byte, m map[string]string) []byte

AppendMapStrStr appends a map[string]string to the slice as a MessagePack map with 'str'-type keys and values

func AppendNil

func AppendNil(b []byte) []byte

AppendNil appends a 'nil' byte to the slice

func AppendString

func AppendString(b []byte, s string) []byte

AppendString appends a string as a MessagePack 'str' to the slice

func AppendStringFromBytes

func AppendStringFromBytes(b []byte, str []byte) []byte

AppendStringFromBytes appends a []byte as a MessagePack 'str' to the slice 'b.'

func AppendTime

func AppendTime(b []byte, t time.Time) []byte

AppendTime appends a time.Time to the slice as a MessagePack extension

func AppendUint

func AppendUint(b []byte, u uint) []byte

AppendUint appends a uint to the slice

func AppendUint16

func AppendUint16(b []byte, u uint16) []byte

AppendUint16 appends a uint16 to the slice

func AppendUint32

func AppendUint32(b []byte, u uint32) []byte

AppendUint32 appends a uint32 to the slice

func AppendUint64

func AppendUint64(b []byte, u uint64) []byte

AppendUint64 appends a uint64 to the slice

func AppendUint8

func AppendUint8(b []byte, u uint8) []byte

AppendUint8 appends a uint8 to the slice

func CopyReplace

func CopyReplace(key string, raw []byte, val []byte) []byte

CopyReplace works similarly to Replace except that the returned byte slice does not point to the same memory as 'raw'. CopyReplace returns 'nil' if the field doesn't exist or 'raw' isn't a map.

func CopyToJSON

func CopyToJSON(dst io.Writer, src io.Reader) (n int64, err error)

CopyToJSON reads MessagePack from 'src' and copies it as JSON to 'dst' until EOF.

func Decode

func Decode(r io.Reader, d Decodable) error

Decode decodes 'd' from 'r'.

func Encode

func Encode(w io.Writer, e Encodable) error

Encode encodes an Encodable to an io.Writer.

func GuessSize

func GuessSize(i interface{}) int

GuessSize guesses the size of the underlying value of 'i'. If the underlying value is not a simple builtin (or []byte), GuessSize defaults to 512.

func HasKey

func HasKey(key string, raw []byte) bool

HasKey returns whether the map in 'raw' has a field with key 'key'

func IsNil

func IsNil(b []byte) bool

IsNil returns true if len(b)>0 and the leading byte is a 'nil' MessagePack byte; false otherwise

func Locate

func Locate(key string, raw []byte) []byte

Locate returns a []byte pointing to the field in a messagepack map with the provided key. (The returned []byte points to a sub-slice of 'raw'; Locate does no allocations.) If the key doesn't exist in the map, a zero-length []byte will be returned.

func ReadArrayHeaderBytes

func ReadArrayHeaderBytes(b []byte) (sz uint32, o []byte, err error)

ReadArrayHeaderBytes attempts to read the array header size off of 'b' and return the size and remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not an array)

func ReadBoolBytes

func ReadBoolBytes(b []byte) (bool, []byte, error)

ReadBoolBytes tries to read a float64 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a bool)

func ReadByteBytes

func ReadByteBytes(b []byte) (byte, []byte, error)

ReadByteBytes is analogous to ReadUint8Bytes

func ReadBytesBytes

func ReadBytesBytes(b []byte, scratch []byte) (v []byte, o []byte, err error)

ReadBytesBytes reads a 'bin' object from 'b' and returns its vaue and the remaining bytes in 'b'. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a 'bin' object)

func ReadBytesZC

func ReadBytesZC(b []byte) (v []byte, o []byte, err error)

ReadBytesZC extracts the messagepack-encoded binary field without copying. The returned []byte points to the same memory as the input slice. Possible errors: - ErrShortBytes (b not long enough) - TypeError{} (object not 'bin')

func ReadComplex128Bytes

func ReadComplex128Bytes(b []byte) (c complex128, o []byte, err error)

ReadComplex128Bytes reads a complex128 extension object from 'b' and returns the remaining bytes. Possible errors: - ErrShortBytes (not enough bytes in 'b') - TypeError{} (object not a complex128) - InvalidPrefixError - ExtensionTypeError{} (object an extension of the correct size, but not a complex128)

func ReadComplex64Bytes

func ReadComplex64Bytes(b []byte) (c complex64, o []byte, err error)

ReadComplex64Bytes reads a complex64 extension object from 'b' and returns the remaining bytes. Possible errors: - ErrShortBytes (not enough bytes in 'b') - TypeError{} (object not a complex64) - ExtensionTypeError{} (object an extension of the correct size, but not a complex64)

func ReadExactBytes

func ReadExactBytes(b []byte, into []byte) (o []byte, err error)

func ReadExtensionBytes

func ReadExtensionBytes(b []byte, e Extension) ([]byte, error)

ReadExtensionBytes reads an extension from 'b' into 'e' and returns any remaining bytes. Possible errors: - ErrShortBytes ('b' not long enough) - ExtensionTypeErorr{} (wire type not the same as e.Type()) - TypeErorr{} (next object not an extension) - InvalidPrefixError - An umarshal error returned from e.UnmarshalBinary

func ReadFile

func ReadFile(dst Unmarshaler, file *os.File) error

ReadFile reads a file into 'dst' using a read-only memory mapping. Consequently, the file must be mmap-able, and the Unmarshaler should never write to the source memory. (Methods generated by the hsp tool obey that constraint, but user-defined implementations may not.)

Reading and writing through file mappings is only efficient for large files; small files are best read and written using the ordinary streaming interfaces.

func ReadFloat32Bytes

func ReadFloat32Bytes(b []byte) (f float32, o []byte, err error)

ReadFloat32Bytes tries to read a float64 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a float32)

func ReadFloat64Bytes

func ReadFloat64Bytes(b []byte) (f float64, o []byte, err error)

ReadFloat64Bytes tries to read a float64 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a float64)

func ReadInt16Bytes

func ReadInt16Bytes(b []byte) (int16, []byte, error)

ReadInt16Bytes tries to read an int16 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a int) - IntOverflow{} (value doesn't fit in int16)

func ReadInt32Bytes

func ReadInt32Bytes(b []byte) (int32, []byte, error)

ReadInt32Bytes tries to read an int32 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a int) - IntOverflow{} (value doesn't fit in int32)

func ReadInt64Bytes

func ReadInt64Bytes(b []byte) (i int64, o []byte, err error)

ReadInt64Bytes tries to read an int64 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError (not a int)

func ReadInt8Bytes

func ReadInt8Bytes(b []byte) (int8, []byte, error)

ReadInt8Bytes tries to read an int16 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a int) - IntOverflow{} (value doesn't fit in int8)

func ReadIntBytes

func ReadIntBytes(b []byte) (int, []byte, error)

ReadIntBytes tries to read an int from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a int) - IntOverflow{} (value doesn't fit in int; 32-bit platforms only)

func ReadIntfBytes

func ReadIntfBytes(b []byte) (i interface{}, o []byte, err error)

ReadIntfBytes attempts to read the next object out of 'b' as a raw interface{} and return the remaining bytes.

func ReadMapHeaderBytes

func ReadMapHeaderBytes(b []byte) (sz uint32, o []byte, err error)

ReadMapHeaderBytes reads a map header size from 'b' and returns the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a map)

func ReadMapKeyZC

func ReadMapKeyZC(b []byte) ([]byte, []byte, error)

ReadMapKeyZC attempts to read a map key from 'b' and returns the key bytes and the remaining bytes Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a str or bin)

func ReadMapStrIntfBytes

func ReadMapStrIntfBytes(b []byte, old map[string]interface{}) (v map[string]interface{}, o []byte, err error)

ReadMapStrIntfBytes reads a map[string]interface{} out of 'b' and returns the map and remaining bytes. If 'old' is non-nil, the values will be read into that map.

func ReadNilBytes

func ReadNilBytes(b []byte) ([]byte, error)

ReadNilBytes tries to read a "nil" byte off of 'b' and return the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a 'nil') - InvalidPrefixError

func ReadStringAsBytes

func ReadStringAsBytes(b []byte, scratch []byte) (v []byte, o []byte, err error)

ReadStringAsBytes reads a 'str' object into a slice of bytes. 'v' is the value of the 'str' object, which may reside in memory pointed to by 'scratch.' 'o' is the remaining bytes in 'b.” Possible errors: - ErrShortBytes (b not long enough) - TypeError{} (not 'str' type) - InvalidPrefixError (unknown type marker)

func ReadStringBytes

func ReadStringBytes(b []byte) (string, []byte, error)

ReadStringBytes reads a 'str' object from 'b' and returns its value and the remaining bytes in 'b'. Possible errors: - ErrShortBytes (b not long enough) - TypeError{} (not 'str' type) - InvalidPrefixError

func ReadStringZC

func ReadStringZC(b []byte) (v []byte, o []byte, err error)

ReadStringZC reads a messagepack string field without copying. The returned []byte points to the same memory as the input slice. Possible errors: - ErrShortBytes (b not long enough) - TypeError{} (object not 'str')

func ReadTimeBytes

func ReadTimeBytes(b []byte) (t time.Time, o []byte, err error)

ReadTimeBytes reads a time.Time extension object from 'b' and returns the remaining bytes. Possible errors: - ErrShortBytes (not enough bytes in 'b') - TypeError{} (object not a complex64) - ExtensionTypeError{} (object an extension of the correct size, but not a time.Time)

func ReadUint16Bytes

func ReadUint16Bytes(b []byte) (uint16, []byte, error)

ReadUint16Bytes tries to read a uint16 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a uint) - UintOverflow{} (value too large for uint16)

func ReadUint32Bytes

func ReadUint32Bytes(b []byte) (uint32, []byte, error)

ReadUint32Bytes tries to read a uint32 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a uint) - UintOverflow{} (value too large for uint32)

func ReadUint64Bytes

func ReadUint64Bytes(b []byte) (u uint64, o []byte, err error)

ReadUint64Bytes tries to read a uint64 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a uint)

func ReadUint8Bytes

func ReadUint8Bytes(b []byte) (uint8, []byte, error)

ReadUint8Bytes tries to read a uint8 from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a uint) - UintOverflow{} (value too large for uint8)

func ReadUintBytes

func ReadUintBytes(b []byte) (uint, []byte, error)

ReadUintBytes tries to read a uint from 'b' and return the value and the remaining bytes. Possible errors: - ErrShortBytes (too few bytes) - TypeError{} (not a uint) - UintOverflow{} (value too large for uint; 32-bit platforms only)

func RegisterExtension

func RegisterExtension(typ int8, f func() Extension)

RegisterExtension registers extensions so that they can be initialized and returned by methods that decode `interface{}` values. This should only be called during initialization. f() should return a newly-initialized zero value of the extension. Keep in mind that extensions 3, 4, and 5 are reserved for complex64, complex128, and time.Time, respectively, and that MessagePack reserves extension types from -127 to -1.

For example, if you wanted to register a user-defined struct:

hsp.RegisterExtension(10, func() hsp.Extension { &MyExtension{} })

RegisterExtension will panic if you call it multiple times with the same 'typ' argument, or if you use a reserved type (3, 4, or 5).

func Remove

func Remove(key string, raw []byte) []byte

Remove removes a key-value pair from 'raw'. It returns 'raw' unchanged if the key didn't exist.

func Replace

func Replace(key string, raw []byte, val []byte) []byte

Replace takes a key ("key") in a messagepack map ("raw") and replaces its value with the one provided and returns the new []byte. The returned []byte may point to the same memory as "raw". Replace makes no effort to evaluate the validity of the contents of 'val'. It may use up to the full capacity of 'raw.' Replace returns 'nil' if the field doesn't exist or if the object in 'raw' is not a map.

func Require

func Require(old []byte, extra int) []byte

Require ensures that cap(old)-len(old) >= extra.

func Skip

func Skip(b []byte) ([]byte, error)

Skip skips the next object in 'b' and returns the remaining bytes. If the object is a map or array, all of its elements will be skipped. Possible Errors: - ErrShortBytes (not enough bytes in b) - InvalidPrefixError (bad encoding)

func UnmarshalAsJSON

func UnmarshalAsJSON(w io.Writer, msg []byte) ([]byte, error)

UnmarshalAsJSON takes raw messagepack and writes it as JSON to 'w'. If an error is returned, the bytes not translated will also be returned. If no errors are encountered, the length of the returned slice will be zero.

func UnsafeBytes

func UnsafeBytes(s string) []byte

UnsafeBytes returns the string as a byte slice THIS SHOULD ONLY BE USED BY THE CODE GENERATOR. THIS IS EVIL CODE. YOU HAVE BEEN WARNED.

func UnsafeString

func UnsafeString(b []byte) string

UnsafeString returns the byte slice as a volatile string THIS SHOULD ONLY BE USED BY THE CODE GENERATOR. THIS IS EVIL CODE. YOU HAVE BEEN WARNED.

func WriteFile

func WriteFile(src MarshalSizer, file *os.File) error

WriteFile writes a file from 'src' using memory mapping. It overwrites the entire contents of the previous file. The mapping size is calculated using the `Msgsize()` method of 'src', so it must produce a result equal to or greater than the actual encoded size of the object. Otherwise, a fault (SIGBUS) will occur.

Reading and writing through file mappings is only efficient for large files; small files are best read and written using the ordinary streaming interfaces.

NOTE: The performance of this call is highly OS- and filesystem-dependent. Users should take care to test that this performs as expected in a production environment. (Linux users should run a kernel and filesystem that support fallocate(2) for the best results.)

Types

type ArrayError

type ArrayError struct {
	Wanted uint32
	Got    uint32
}

ArrayError is an error returned when decoding a fix-sized array of the wrong size

func (ArrayError) Error

func (a ArrayError) Error() string

Error implements the error interface

func (ArrayError) Resumable

func (a ArrayError) Resumable() bool

Resumable is always 'true' for ArrayErrors

type Decodable

type Decodable interface {
	DecodeMsg(*Reader) error
}

Decodable is the interface fulfilled by objects that know how to read themselves from a *Reader.

type Encodable

type Encodable interface {
	EncodeMsg(*Writer) error
}

Encodable is the interface implemented by types that know how to write themselves as MessagePack using a *hsp.Writer.

type EndlessReader

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

EndlessReader is an io.Reader that loops over the same data endlessly. It is used for benchmarking.

func NewEndlessReader

func NewEndlessReader(b []byte, tb timer) *EndlessReader

NewEndlessReader returns a new endless reader

func (*EndlessReader) Read

func (c *EndlessReader) Read(p []byte) (int, error)

Read implements io.Reader. In practice, it always returns (len(p), nil), although it fills the supplied slice while the benchmark timer is stopped.

type ErrUnsupportedType

type ErrUnsupportedType struct {
	T reflect.Type
}

ErrUnsupportedType is returned when a bad argument is supplied to a function that takes `interface{}`.

func (*ErrUnsupportedType) Error

func (e *ErrUnsupportedType) Error() string

Error implements error

func (*ErrUnsupportedType) Resumable

func (e *ErrUnsupportedType) Resumable() bool

Resumable returns 'true' for ErrUnsupportedType

type Error

type Error interface {
	error

	// Resumable returns whether
	// or not the error means that
	// the stream of data is malformed
	// and  the information is unrecoverable.
	Resumable() bool
}

Error is the interface satisfied by all of the errors that originate from this package.

type Extension

type Extension interface {
	// ExtensionType should return
	// a int8 that identifies the concrete
	// type of the extension. (Types <0 are
	// officially reserved by the MessagePack
	// specifications.)
	ExtensionType() int8

	// Len should return the length
	// of the data to be encoded
	Len() int

	// MarshalBinaryTo should copy
	// the data into the supplied slice,
	// assuming that the slice has length Len()
	MarshalBinaryTo([]byte) error

	UnmarshalBinary([]byte) error
}

Extension is the interface fulfilled by types that want to define their own binary encoding.

type ExtensionTypeError

type ExtensionTypeError struct {
	Got  int8
	Want int8
}

ExtensionTypeError is an error type returned when there is a mis-match between an extension type and the type encoded on the wire

func (ExtensionTypeError) Error

func (e ExtensionTypeError) Error() string

Error implements the error interface

func (ExtensionTypeError) Resumable

func (e ExtensionTypeError) Resumable() bool

Resumable returns 'true' for ExtensionTypeErrors

type IntOverflow

type IntOverflow struct {
	Value         int64 // the value of the integer
	FailedBitsize int   // the bit size that the int64 could not fit into
}

IntOverflow is returned when a call would downcast an integer to a type with too few bits to hold its value.

func (IntOverflow) Error

func (i IntOverflow) Error() string

Error implements the error interface

func (IntOverflow) Resumable

func (i IntOverflow) Resumable() bool

Resumable is always 'true' for overflows

type InvalidPrefixError

type InvalidPrefixError byte

InvalidPrefixError is returned when a bad encoding uses a prefix that is not recognized in the MessagePack standard. This kind of error is unrecoverable.

func (InvalidPrefixError) Error

func (i InvalidPrefixError) Error() string

Error implements the error interface

func (InvalidPrefixError) Resumable

func (i InvalidPrefixError) Resumable() bool

Resumable returns 'false' for InvalidPrefixErrors

type MarshalSizer

type MarshalSizer interface {
	Marshaler
	Sizer
}

MarshalSizer is the combination of the Marshaler and Sizer interfaces.

type Marshaler

type Marshaler interface {
	MarshalMsg([]byte) ([]byte, error)
}

Marshaler is the interface implemented by types that know how to marshal themselves as MessagePack. MarshalMsg appends the marshalled form of the object to the provided byte slice, returning the extended slice and any errors encountered.

type Number

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

Number can be an int64, uint64, float32, or float64 internally. It can decode itself from any of the native messagepack number types. The zero-value of Number is Int(0). Using the equality operator with Number compares both the type and the value of the number.

func (*Number) AsFloat32

func (n *Number) AsFloat32(f float32)

AsFloat32 sets the value of the number to a float32.

func (*Number) AsFloat64

func (n *Number) AsFloat64(f float64)

AsFloat64 sets the value of the number to a float64.

func (*Number) AsInt

func (n *Number) AsInt(i int64)

AsInt sets the number to an int64.

func (*Number) AsUint

func (n *Number) AsUint(u uint64)

AsUint sets the number to a uint64.

func (*Number) DecodeMsg

func (n *Number) DecodeMsg(r *Reader) error

DecodeMsg implements hsp.Decodable

func (*Number) EncodeMsg

func (n *Number) EncodeMsg(w *Writer) error

EncodeMsg implements hsp.Encodable

func (*Number) Float

func (n *Number) Float() (float64, bool)

Float casts the number to a float64, and returns whether or not that was the underlying type (either a float64 or a float32).

func (*Number) Int

func (n *Number) Int() (int64, bool)

Int casts the number as an int64, and returns whether or not that was the underlying type.

func (*Number) MarshalJSON

func (n *Number) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*Number) MarshalMsg

func (n *Number) MarshalMsg(b []byte) ([]byte, error)

MarshalMsg implements hsp.Marshaler

func (*Number) Msgsize

func (n *Number) Msgsize() int

Msgsize implements hsp.Sizer

func (*Number) String

func (n *Number) String() string

String implements fmt.Stringer

func (*Number) Type

func (n *Number) Type() Type

Type will return one of: Float64Type, Float32Type, UintType, or IntType.

func (*Number) Uint

func (n *Number) Uint() (uint64, bool)

Uint casts the number as a uint64, and returns whether or not that was the underlying type.

func (*Number) UnmarshalMsg

func (n *Number) UnmarshalMsg(b []byte) ([]byte, error)

UnmarshalMsg implements hsp.Unmarshaler

type Raw

type Raw []byte

Raw is raw MessagePack. Raw allows you to read and write data without interpreting its contents.

func (*Raw) DecodeMsg

func (r *Raw) DecodeMsg(f *Reader) error

DecodeMsg implements hsp.Decodable. It sets the value of *Raw to be the next object on the wire.

func (Raw) EncodeMsg

func (r Raw) EncodeMsg(w *Writer) error

EncodeMsg implements hsp.Encodable. It writes the raw bytes to the writer. If r is empty, it writes 'nil' instead.

func (*Raw) MarshalJSON

func (r *Raw) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (Raw) MarshalMsg

func (r Raw) MarshalMsg(b []byte) ([]byte, error)

MarshalMsg implements hsp.Marshaler. It appends the raw contents of 'raw' to the provided byte slice. If 'raw' is 0 bytes, 'nil' will be appended instead.

func (Raw) Msgsize

func (r Raw) Msgsize() int

Msgsize implements hsp.Sizer

func (*Raw) UnmarshalMsg

func (r *Raw) UnmarshalMsg(b []byte) ([]byte, error)

UnmarshalMsg implements hsp.Unmarshaler. It sets the contents of *Raw to be the next object in the provided byte slice.

type RawExtension

type RawExtension struct {
	Data []byte
	Type int8
}

RawExtension implements the Extension interface

func (*RawExtension) ExtensionType

func (r *RawExtension) ExtensionType() int8

ExtensionType implements Extension.ExtensionType, and returns r.Type

func (*RawExtension) Len

func (r *RawExtension) Len() int

Len implements Extension.Len, and returns len(r.Data)

func (*RawExtension) MarshalBinaryTo

func (r *RawExtension) MarshalBinaryTo(d []byte) error

MarshalBinaryTo implements Extension.MarshalBinaryTo, and returns a copy of r.Data

func (*RawExtension) UnmarshalBinary

func (r *RawExtension) UnmarshalBinary(b []byte) error

UnmarshalBinary implements Extension.UnmarshalBinary, and sets r.Data to the contents of the provided slice

type Reader

type Reader struct {
	// R is the buffered reader
	// that the Reader uses
	// to decode MessagePack.
	// The Reader itself
	// is stateless; all the
	// buffering is done
	// within R.
	R *fwd.Reader
	// contains filtered or unexported fields
}

Reader wraps an io.Reader and provides methods to read MessagePack-encoded values from it. Readers are buffered.

func NewReader

func NewReader(r io.Reader) *Reader

NewReader returns a *Reader that reads from the provided reader. The reader will be buffered.

func NewReaderSize

func NewReaderSize(r io.Reader, sz int) *Reader

NewReaderSize returns a *Reader with a buffer of the given size. (This is vastly preferable to passing the decoder a reader that is already buffered.)

func (*Reader) BufferSize

func (m *Reader) BufferSize() int

BufferSize returns the capacity of the read buffer.

func (*Reader) Buffered

func (m *Reader) Buffered() int

Buffered returns the number of bytes currently in the read buffer.

func (*Reader) CopyNext

func (m *Reader) CopyNext(w io.Writer) (int64, error)

CopyNext reads the next object from m without decoding it and writes it to w. It avoids unnecessary copies internally.

func (*Reader) IsNil

func (m *Reader) IsNil() bool

IsNil returns whether or not the next byte is a null messagepack byte

func (*Reader) NextType

func (m *Reader) NextType() (Type, error)

NextType returns the next object type to be decoded.

func (*Reader) Read

func (m *Reader) Read(p []byte) (int, error)

Read implements `io.Reader`

func (*Reader) ReadArrayHeader

func (m *Reader) ReadArrayHeader() (sz uint32, err error)

ReadArrayHeader reads the next object as an array header and returns the size of the array and the number of bytes read.

func (*Reader) ReadBool

func (m *Reader) ReadBool() (b bool, err error)

ReadBool reads a bool from the reader

func (*Reader) ReadByte

func (m *Reader) ReadByte() (b byte, err error)

ReadByte is analogous to ReadUint8.

NOTE: this is *not* an implementation of io.ByteReader.

func (*Reader) ReadBytes

func (m *Reader) ReadBytes(scratch []byte) (b []byte, err error)

ReadBytes reads a MessagePack 'bin' object from the reader and returns its value. It may use 'scratch' for storage if it is non-nil.

func (*Reader) ReadBytesHeader

func (m *Reader) ReadBytesHeader() (sz uint32, err error)

ReadBytesHeader reads the size header of a MessagePack 'bin' object. The user is responsible for dealing with the next 'sz' bytes from the reader in an application-specific way.

func (*Reader) ReadComplex128

func (m *Reader) ReadComplex128() (f complex128, err error)

ReadComplex128 reads a complex128 from the reader

func (*Reader) ReadComplex64

func (m *Reader) ReadComplex64() (f complex64, err error)

ReadComplex64 reads a complex64 from the reader

func (*Reader) ReadExactBytes

func (m *Reader) ReadExactBytes(into []byte) error

ReadExactBytes reads a MessagePack 'bin'-encoded object off of the wire into the provided slice. An ArrayError will be returned if the object is not exactly the length of the input slice.

func (*Reader) ReadExtension

func (m *Reader) ReadExtension(e Extension) (err error)

ReadExtension reads the next object from the reader as an extension. ReadExtension will fail if the next object in the stream is not an extension, or if e.Type() is not the same as the wire type.

func (*Reader) ReadFloat32

func (m *Reader) ReadFloat32() (f float32, err error)

ReadFloat32 reads a float32 from the reader

func (*Reader) ReadFloat64

func (m *Reader) ReadFloat64() (f float64, err error)

ReadFloat64 reads a float64 from the reader. (If the value on the wire is encoded as a float32, it will be up-cast to a float64.)

func (*Reader) ReadFull

func (m *Reader) ReadFull(p []byte) (int, error)

ReadFull implements `io.ReadFull`

func (*Reader) ReadInt

func (m *Reader) ReadInt() (i int, err error)

ReadInt reads an int from the reader

func (*Reader) ReadInt16

func (m *Reader) ReadInt16() (i int16, err error)

ReadInt16 reads an int16 from the reader

func (*Reader) ReadInt32

func (m *Reader) ReadInt32() (i int32, err error)

ReadInt32 reads an int32 from the reader

func (*Reader) ReadInt64

func (m *Reader) ReadInt64() (i int64, err error)

ReadInt64 reads an int64 from the reader

func (*Reader) ReadInt8

func (m *Reader) ReadInt8() (i int8, err error)

ReadInt8 reads an int8 from the reader

func (*Reader) ReadIntf

func (m *Reader) ReadIntf() (i interface{}, err error)

ReadIntf reads out the next object as a raw interface{}. Arrays are decoded as []interface{}, and maps are decoded as map[string]interface{}. Integers are decoded as int64 and unsigned integers are decoded as uint64.

func (*Reader) ReadMapHeader

func (m *Reader) ReadMapHeader() (sz uint32, err error)

ReadMapHeader reads the next object as a map header and returns the size of the map and the number of bytes written. It will return a TypeError{} if the next object is not a map.

func (*Reader) ReadMapKey

func (m *Reader) ReadMapKey(scratch []byte) ([]byte, error)

ReadMapKey reads either a 'str' or 'bin' field from the reader and returns the value as a []byte. It uses scratch for storage if it is large enough.

func (*Reader) ReadMapKeyPtr

func (m *Reader) ReadMapKeyPtr() ([]byte, error)

MapKeyPtr returns a []byte pointing to the contents of a valid map key. The key cannot be empty, and it must be shorter than the total buffer size of the *Reader. Additionally, the returned slice is only valid until the next *Reader method call. Users should exercise extreme care when using this method; writing into the returned slice may corrupt future reads.

func (*Reader) ReadMapStrIntf

func (m *Reader) ReadMapStrIntf(mp map[string]interface{}) (err error)

ReadMapStrIntf reads a MessagePack map into a map[string]interface{}. (You must pass a non-nil map into the function.)

func (*Reader) ReadNil

func (m *Reader) ReadNil() error

ReadNil reads a 'nil' MessagePack byte from the reader

func (*Reader) ReadString

func (m *Reader) ReadString() (s string, err error)

ReadString reads a utf-8 string from the reader

func (*Reader) ReadStringAsBytes

func (m *Reader) ReadStringAsBytes(scratch []byte) (b []byte, err error)

ReadStringAsBytes reads a MessagePack 'str' (utf-8) string and returns its value as bytes. It may use 'scratch' for storage if it is non-nil.

func (*Reader) ReadStringHeader

func (m *Reader) ReadStringHeader() (sz uint32, err error)

ReadStringHeader reads a string header off of the wire. The user is then responsible for dealing with the next 'sz' bytes from the reader in an application-specific manner.

func (*Reader) ReadTime

func (m *Reader) ReadTime() (t time.Time, err error)

ReadTime reads a time.Time object from the reader. The returned time's location will be set to time.Local.

func (*Reader) ReadUint

func (m *Reader) ReadUint() (u uint, err error)

ReadUint reads a uint from the reader

func (*Reader) ReadUint16

func (m *Reader) ReadUint16() (u uint16, err error)

ReadUint16 reads a uint16 from the reader

func (*Reader) ReadUint32

func (m *Reader) ReadUint32() (u uint32, err error)

ReadUint32 reads a uint32 from the reader

func (*Reader) ReadUint64

func (m *Reader) ReadUint64() (u uint64, err error)

ReadUint64 reads a uint64 from the reader

func (*Reader) ReadUint8

func (m *Reader) ReadUint8() (u uint8, err error)

ReadUint8 reads a uint8 from the reader

func (*Reader) Reset

func (m *Reader) Reset(r io.Reader)

Reset resets the underlying reader.

func (*Reader) Skip

func (m *Reader) Skip() error

Skip skips over the next object, regardless of its type. If it is an array or map, the whole array or map will be skipped.

func (*Reader) WriteToJSON

func (r *Reader) WriteToJSON(w io.Writer) (n int64, err error)

WriteToJSON translates MessagePack from 'r' and writes it as JSON to 'w' until the underlying reader returns io.EOF. It returns the number of bytes written, and an error if it stopped before EOF.

type Sizer

type Sizer interface {
	Msgsize() int
}

Sizer is an interface implemented by types that can estimate their size when MessagePack encoded. This interface is optional, but encoding/marshaling implementations may use this as a way to pre-allocate memory for serialization.

type Type

type Type byte

Type is a MessagePack wire type, including this package's built-in extension types.

const (
	InvalidType Type = iota

	StrType
	BinType
	MapType
	ArrayType
	Float64Type
	Float32Type
	BoolType
	IntType
	UintType
	NilType
	ExtensionType

	Complex64Type
	Complex128Type
	TimeType
)

MessagePack Types

The zero value of Type is InvalidType.

func NextType

func NextType(b []byte) Type

NextType returns the type of the next object in the slice. If the length of the input is zero, it returns InvalidType.

func (Type) String

func (t Type) String() string

String implements fmt.Stringer

type TypeError

type TypeError struct {
	Method  Type // Type expected by method
	Encoded Type // Type actually encoded
}

A TypeError is returned when a particular decoding method is unsuitable for decoding a particular MessagePack value.

func (TypeError) Error

func (t TypeError) Error() string

Error implements the error interface

func (TypeError) Resumable

func (t TypeError) Resumable() bool

Resumable returns 'true' for TypeErrors

type UintBelowZero

type UintBelowZero struct {
	Value int64 // value of the incoming int
}

UintBelowZero is returned when a call would cast a signed integer below zero to an unsigned integer.

func (UintBelowZero) Error

func (u UintBelowZero) Error() string

Error implements the error interface

func (UintBelowZero) Resumable

func (u UintBelowZero) Resumable() bool

Resumable is always 'true' for overflows

type UintOverflow

type UintOverflow struct {
	Value         uint64 // value of the uint
	FailedBitsize int    // the bit size that couldn't fit the value
}

UintOverflow is returned when a call would downcast an unsigned integer to a type with too few bits to hold its value

func (UintOverflow) Error

func (u UintOverflow) Error() string

Error implements the error interface

func (UintOverflow) Resumable

func (u UintOverflow) Resumable() bool

Resumable is always 'true' for overflows

type Unmarshaler

type Unmarshaler interface {
	UnmarshalMsg([]byte) ([]byte, error)
}

Unmarshaler is the interface fulfilled by objects that know how to unmarshal themselves from MessagePack. UnmarshalMsg unmarshals the object from binary, returing any leftover bytes and any errors encountered.

type Writer

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

Writer is a buffered writer that can be used to write MessagePack objects to an io.Writer. You must call *Writer.Flush() in order to flush all of the buffered data to the underlying writer.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a new *Writer.

func NewWriterSize

func NewWriterSize(w io.Writer, sz int) *Writer

NewWriterSize returns a writer with a custom buffer size.

func (*Writer) Append

func (mw *Writer) Append(b ...byte) error

func (*Writer) Buffered

func (mw *Writer) Buffered() int

Buffered returns the number bytes in the write buffer

func (*Writer) Flush

func (mw *Writer) Flush() error

Flush flushes all of the buffered data to the underlying writer.

func (*Writer) Reset

func (mw *Writer) Reset(w io.Writer)

Reset changes the underlying writer used by the Writer

func (*Writer) Write

func (mw *Writer) Write(p []byte) (int, error)

Write implements io.Writer, and writes data directly to the buffer.

func (*Writer) WriteArrayHeader

func (mw *Writer) WriteArrayHeader(sz uint32) error

WriteArrayHeader writes an array header of the given size to the writer

func (*Writer) WriteBool

func (mw *Writer) WriteBool(b bool) error

WriteBool writes a bool to the writer

func (*Writer) WriteByte

func (mw *Writer) WriteByte(u byte) error

WriteByte is analogous to WriteUint8

func (*Writer) WriteBytes

func (mw *Writer) WriteBytes(b []byte) error

WriteBytes writes binary as 'bin' to the writer

func (*Writer) WriteBytesHeader

func (mw *Writer) WriteBytesHeader(sz uint32) error

WriteBytesHeader writes just the size header of a MessagePack 'bin' object. The user is responsible for then writing 'sz' more bytes into the stream.

func (*Writer) WriteComplex128

func (mw *Writer) WriteComplex128(f complex128) error

WriteComplex128 writes a complex128 to the writer

func (*Writer) WriteComplex64

func (mw *Writer) WriteComplex64(f complex64) error

WriteComplex64 writes a complex64 to the writer

func (*Writer) WriteExtension

func (mw *Writer) WriteExtension(e Extension) error

WriteExtension writes an extension type to the writer

func (*Writer) WriteFloat32

func (mw *Writer) WriteFloat32(f float32) error

WriteFloat32 writes a float32 to the writer

func (*Writer) WriteFloat64

func (mw *Writer) WriteFloat64(f float64) error

WriteFloat64 writes a float64 to the writer

func (*Writer) WriteInt

func (mw *Writer) WriteInt(i int) error

WriteInt writes an int to the writer

func (*Writer) WriteInt16

func (mw *Writer) WriteInt16(i int16) error

WriteInt16 writes an int16 to the writer

func (*Writer) WriteInt32

func (mw *Writer) WriteInt32(i int32) error

WriteInt32 writes an int32 to the writer

func (*Writer) WriteInt64

func (mw *Writer) WriteInt64(i int64) error

WriteInt64 writes an int64 to the writer

func (*Writer) WriteInt8

func (mw *Writer) WriteInt8(i int8) error

WriteInt8 writes an int8 to the writer

func (*Writer) WriteIntf

func (mw *Writer) WriteIntf(v interface{}) error

WriteIntf writes the concrete type of 'v'. WriteIntf will error if 'v' is not one of the following:

  • A bool, float, string, []byte, int, uint, or complex
  • A map of supported types (with string keys)
  • An array or slice of supported types
  • A pointer to a supported type
  • A type that satisfies the hsp.Encodable interface
  • A type that satisfies the hsp.Extension interface

func (*Writer) WriteMapHeader

func (mw *Writer) WriteMapHeader(sz uint32) error

WriteMapHeader writes a map header of the given size to the writer

func (*Writer) WriteMapStrIntf

func (mw *Writer) WriteMapStrIntf(mp map[string]interface{}) (err error)

WriteMapStrIntf writes a map[string]interface to the writer

func (*Writer) WriteMapStrStr

func (mw *Writer) WriteMapStrStr(mp map[string]string) (err error)

WriteMapStrStr writes a map[string]string to the writer

func (*Writer) WriteNil

func (mw *Writer) WriteNil() error

WriteNil writes a nil byte to the buffer

func (*Writer) WriteString

func (mw *Writer) WriteString(s string) error

WriteString writes a messagepack string to the writer. (This is NOT an implementation of io.StringWriter)

func (*Writer) WriteStringFromBytes

func (mw *Writer) WriteStringFromBytes(str []byte) error

WriteStringFromBytes writes a 'str' object from a []byte.

func (*Writer) WriteStringHeader

func (mw *Writer) WriteStringHeader(sz uint32) error

WriteStringHeader writes just the string size header of a MessagePack 'str' object. The user is responsible for writing 'sz' more valid UTF-8 bytes to the stream.

func (*Writer) WriteTime

func (mw *Writer) WriteTime(t time.Time) error

WriteTime writes a time.Time object to the wire.

Time is encoded as Unix time, which means that location (time zone) data is removed from the object. The encoded object itself is 12 bytes: 8 bytes for a big-endian 64-bit integer denoting seconds elapsed since "zero" Unix time, followed by 4 bytes for a big-endian 32-bit signed integer denoting the nanosecond offset of the time. This encoding is intended to ease portability across languages. (Note that this is *not* the standard time.Time binary encoding, because its implementation relies heavily on the internal representation used by the time package.)

func (*Writer) WriteUint

func (mw *Writer) WriteUint(u uint) error

WriteUint writes a uint to the writer

func (*Writer) WriteUint16

func (mw *Writer) WriteUint16(u uint16) error

WriteUint16 writes a uint16 to the writer

func (*Writer) WriteUint32

func (mw *Writer) WriteUint32(u uint32) error

WriteUint32 writes a uint32 to the writer

func (*Writer) WriteUint64

func (mw *Writer) WriteUint64(u uint64) error

WriteUint64 writes a uint64 to the writer

func (*Writer) WriteUint8

func (mw *Writer) WriteUint8(u uint8) error

WriteUint8 writes a uint8 to the writer

Jump to

Keyboard shortcuts

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