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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.