README

MessagePack encoding for Golang

Build Status GoDoc

Supports:

API docs: https://godoc.org/github.com/vmihailenco/msgpack. Examples: https://godoc.org/github.com/vmihailenco/msgpack#pkg-examples.

Installation

Install:

go get -u github.com/vmihailenco/msgpack

Quickstart

func ExampleMarshal() {
	type Item struct {
		Foo string
	}

	b, err := msgpack.Marshal(&Item{Foo: "bar"})
	if err != nil {
		panic(err)
	}

	var item Item
	err = msgpack.Unmarshal(b, &item)
	if err != nil {
		panic(err)
	}
	fmt.Println(item.Foo)
	// Output: bar
}

Benchmark

BenchmarkStructVmihailencoMsgpack-4   	  200000	     12814 ns/op	    2128 B/op	      26 allocs/op
BenchmarkStructUgorjiGoMsgpack-4      	  100000	     17678 ns/op	    3616 B/op	      70 allocs/op
BenchmarkStructUgorjiGoCodec-4        	  100000	     19053 ns/op	    7346 B/op	      23 allocs/op
BenchmarkStructJSON-4                 	   20000	     69438 ns/op	    7864 B/op	      26 allocs/op
BenchmarkStructGOB-4                  	   10000	    104331 ns/op	   14664 B/op	     278 allocs/op

Howto

Please go through examples to get an idea how to use this package.

See also

Expand ▾ Collapse ▴

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Marshal

func Marshal(v interface{}) ([]byte, error)

    Marshal returns the MessagePack encoding of v.

    Example
    Output:
    
    bar
    
    Example (AsArray)
    Output:
    
    [foo bar]
    
    Example (MapStringInterface)
    Output:
    
    foo = 1
    hello = world
    
    Example (OmitEmpty)
    Output:
    
    item: "\x82\xa3Foo\xa5hello\xa3Bar\xa0"
    item2: "\x81\xa3Foo\xa5hello"
    

    func Register

    func Register(value interface{}, enc encoderFunc, dec decoderFunc)

      Register registers encoder and decoder functions for a value. This is low level API and in most cases you should prefer implementing Marshaler/CustomEncoder and Unmarshaler/CustomDecoder interfaces.

      func RegisterExt

      func RegisterExt(id int8, value interface{})

        RegisterExt records a type, identified by a value for that type, under the provided id. That id will identify the concrete type of a value sent or received as an interface variable. Only types that will be transferred as implementations of interface values need to be registered. Expecting to be used only during initialization, it panics if the mapping between types and ids is not a bijection.

        Example
        Output:
        
        1973-11-29 21:33:09.000000123 +0000 UTC
        1973-11-29 21:33:09.000000123 +0000 UTC
        

        func Unmarshal

        func Unmarshal(data []byte, v interface{}) error

          Unmarshal decodes the MessagePack-encoded data and stores the result in the value pointed to by v.

          Types

          type CustomDecoder

          type CustomDecoder interface {
          	DecodeMsgpack(*Decoder) error
          }

          type CustomEncoder

          type CustomEncoder interface {
          	EncodeMsgpack(*Encoder) error
          }
          Example
          Output:
          
          msgpack_test.customStruct{S:"hello", N:42}
          

          type Decoder

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

          func NewDecoder

          func NewDecoder(r io.Reader) *Decoder

            NewDecoder returns a new decoder that reads from r.

            The decoder introduces its own buffering and may read data from r beyond the MessagePack values requested. Buffering can be disabled by passing a reader that implements io.ByteScanner interface.

            func (*Decoder) Decode

            func (d *Decoder) Decode(v interface{}) error

            func (*Decoder) DecodeArrayLen

            func (d *Decoder) DecodeArrayLen() (int, error)

              DecodeArrayLen decodes array length. Length is -1 when array is nil.

              func (*Decoder) DecodeBool

              func (d *Decoder) DecodeBool() (bool, error)

              func (*Decoder) DecodeBytes

              func (d *Decoder) DecodeBytes() ([]byte, error)

              func (*Decoder) DecodeBytesLen

              func (d *Decoder) DecodeBytesLen() (int, error)

              func (*Decoder) DecodeExtHeader

              func (d *Decoder) DecodeExtHeader() (typeId int8, length int, err error)

              func (*Decoder) DecodeFloat32

              func (d *Decoder) DecodeFloat32() (float32, error)

              func (*Decoder) DecodeFloat64

              func (d *Decoder) DecodeFloat64() (float64, error)

                DecodeFloat64 decodes msgpack float32/64 into Go float64.

                func (*Decoder) DecodeInt

                func (d *Decoder) DecodeInt() (int, error)

                func (*Decoder) DecodeInt16

                func (d *Decoder) DecodeInt16() (int16, error)

                func (*Decoder) DecodeInt32

                func (d *Decoder) DecodeInt32() (int32, error)

                func (*Decoder) DecodeInt64

                func (d *Decoder) DecodeInt64() (int64, error)

                  DecodeInt64 decodes msgpack int8/16/32/64 and uint8/16/32/64 into Go int64.

                  func (*Decoder) DecodeInt8

                  func (d *Decoder) DecodeInt8() (int8, error)

                  func (*Decoder) DecodeInterface

                  func (d *Decoder) DecodeInterface() (interface{}, error)

                    DecodeInterface decodes value into interface. It returns following types:

                    - nil,
                    - bool,
                    - int8, int16, int32, int64,
                    - uint8, uint16, uint32, uint64,
                    - float32 and float64,
                    - string,
                    - []byte,
                    - slices of any of the above,
                    - maps of any of the above.
                    

                    DecodeInterface should be used only when you don't know the type of value you are decoding. For example, if you are decoding number it is better to use DecodeInt64 for negative numbers and DecodeUint64 for positive numbers.

                    func (*Decoder) DecodeInterfaceLoose

                    func (d *Decoder) DecodeInterfaceLoose() (interface{}, error)

                      DecodeInterfaceLoose is like DecodeInterface except that:

                      - int8, int16, and int32 are converted to int64,
                      - uint8, uint16, and uint32 are converted to uint64,
                      - float32 is converted to float64.
                      

                      func (*Decoder) DecodeMap

                      func (d *Decoder) DecodeMap() (interface{}, error)

                      func (*Decoder) DecodeMapLen

                      func (d *Decoder) DecodeMapLen() (int, error)

                        DecodeMapLen decodes map length. Length is -1 when map is nil.

                        func (*Decoder) DecodeMulti

                        func (d *Decoder) DecodeMulti(v ...interface{}) error

                        func (*Decoder) DecodeNil

                        func (d *Decoder) DecodeNil() error

                        func (*Decoder) DecodeSlice

                        func (d *Decoder) DecodeSlice() ([]interface{}, error)

                        func (*Decoder) DecodeString

                        func (d *Decoder) DecodeString() (string, error)

                        func (*Decoder) DecodeTime

                        func (d *Decoder) DecodeTime() (time.Time, error)

                        func (*Decoder) DecodeUint

                        func (d *Decoder) DecodeUint() (uint, error)

                        func (*Decoder) DecodeUint16

                        func (d *Decoder) DecodeUint16() (uint16, error)

                        func (*Decoder) DecodeUint32

                        func (d *Decoder) DecodeUint32() (uint32, error)

                        func (*Decoder) DecodeUint64

                        func (d *Decoder) DecodeUint64() (uint64, error)

                          DecodeUint64 decodes msgpack int8/16/32/64 and uint8/16/32/64 into Go uint64.

                          func (*Decoder) DecodeUint8

                          func (d *Decoder) DecodeUint8() (uint8, error)

                          func (*Decoder) DecodeValue

                          func (d *Decoder) DecodeValue(v reflect.Value) error

                          func (*Decoder) PeekCode

                          func (d *Decoder) PeekCode() (codes.Code, error)

                            PeekCode returns the next MessagePack code without advancing the reader. Subpackage msgpack/codes contains list of available codes.

                            func (*Decoder) Query

                            func (d *Decoder) Query(query string) ([]interface{}, error)

                              Query extracts data specified by the query from the msgpack stream skipping any other data. Query consists of map keys and array indexes separated with dot, e.g. key1.0.key2.

                              Example
                              Output:
                              
                              phones are [12345 54321]
                              2nd phone is 54321
                              

                              func (*Decoder) Reset

                              func (d *Decoder) Reset(r io.Reader) error

                              func (*Decoder) SetDecodeMapFunc

                              func (d *Decoder) SetDecodeMapFunc(fn func(*Decoder) (interface{}, error))
                              Example
                              Output:
                              
                              map[string]string{"hello":"world"}
                              

                              func (*Decoder) Skip

                              func (d *Decoder) Skip() error

                                Skip skips next value.

                                func (*Decoder) UseDecodeInterfaceLoose

                                func (d *Decoder) UseDecodeInterfaceLoose(flag bool) *Decoder

                                  UseDecodeInterfaceLoose causes decoder to use DecodeInterfaceLoose to decode msgpack value into Go interface{}.

                                  func (*Decoder) UseJSONTag

                                  func (d *Decoder) UseJSONTag(v bool) *Decoder

                                    UseJSONTag causes the Decoder to use json struct tag as fallback option if there is no msgpack tag.

                                    type Encoder

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

                                    func NewEncoder

                                    func NewEncoder(w io.Writer) *Encoder

                                      NewEncoder returns a new encoder that writes to w.

                                      func (*Encoder) Encode

                                      func (e *Encoder) Encode(v interface{}) error

                                      func (*Encoder) EncodeArrayLen

                                      func (e *Encoder) EncodeArrayLen(l int) error

                                      func (*Encoder) EncodeBool

                                      func (e *Encoder) EncodeBool(value bool) error

                                      func (*Encoder) EncodeBytes

                                      func (e *Encoder) EncodeBytes(v []byte) error

                                      func (*Encoder) EncodeBytesLen

                                      func (e *Encoder) EncodeBytesLen(l int) error

                                      func (*Encoder) EncodeExtHeader

                                      func (e *Encoder) EncodeExtHeader(typeId int8, length int) error

                                      func (*Encoder) EncodeFloat32

                                      func (e *Encoder) EncodeFloat32(n float32) error

                                      func (*Encoder) EncodeFloat64

                                      func (e *Encoder) EncodeFloat64(n float64) error

                                      func (*Encoder) EncodeInt

                                      func (e *Encoder) EncodeInt(n int64) error

                                        EncodeNumber encodes an int64 in 1, 2, 3, 5, or 9 bytes. Type of number is lost during encoding.

                                        func (*Encoder) EncodeInt16

                                        func (e *Encoder) EncodeInt16(n int16) error

                                          EncodeInt16 encodes an int16 in 3 bytes preserving type of the number.

                                          func (*Encoder) EncodeInt32

                                          func (e *Encoder) EncodeInt32(n int32) error

                                            EncodeInt32 encodes an int32 in 5 bytes preserving type of the number.

                                            func (*Encoder) EncodeInt64

                                            func (e *Encoder) EncodeInt64(n int64) error

                                              EncodeInt64 encodes an int64 in 9 bytes preserving type of the number.

                                              func (*Encoder) EncodeInt8

                                              func (e *Encoder) EncodeInt8(n int8) error

                                                EncodeInt8 encodes an int8 in 2 bytes preserving type of the number.

                                                func (*Encoder) EncodeMapLen

                                                func (e *Encoder) EncodeMapLen(l int) error

                                                func (*Encoder) EncodeMulti

                                                func (e *Encoder) EncodeMulti(v ...interface{}) error

                                                func (*Encoder) EncodeNil

                                                func (e *Encoder) EncodeNil() error

                                                func (*Encoder) EncodeString

                                                func (e *Encoder) EncodeString(v string) error

                                                func (*Encoder) EncodeTime

                                                func (e *Encoder) EncodeTime(tm time.Time) error

                                                func (*Encoder) EncodeUint

                                                func (e *Encoder) EncodeUint(n uint64) error

                                                  EncodeUnsignedNumber encodes an uint64 in 1, 2, 3, 5, or 9 bytes. Type of the number is lost during encoding.

                                                  func (*Encoder) EncodeUint16

                                                  func (e *Encoder) EncodeUint16(n uint16) error

                                                    EncodeUint16 encodes an uint16 in 3 bytes preserving type of the number.

                                                    func (*Encoder) EncodeUint32

                                                    func (e *Encoder) EncodeUint32(n uint32) error

                                                      EncodeUint32 encodes an uint16 in 5 bytes preserving type of the number.

                                                      func (*Encoder) EncodeUint64

                                                      func (e *Encoder) EncodeUint64(n uint64) error

                                                        EncodeUint64 encodes an uint16 in 9 bytes preserving type of the number.

                                                        func (*Encoder) EncodeUint8

                                                        func (e *Encoder) EncodeUint8(n uint8) error

                                                          EncodeUint8 encodes an uint8 in 2 bytes preserving type of the number.

                                                          func (*Encoder) EncodeValue

                                                          func (e *Encoder) EncodeValue(v reflect.Value) error

                                                          func (*Encoder) SortMapKeys

                                                          func (e *Encoder) SortMapKeys(flag bool) *Encoder

                                                            SortMapKeys causes the Encoder to encode map keys in increasing order. Supported map types are:

                                                            - map[string]string
                                                            - map[string]interface{}
                                                            

                                                            func (*Encoder) StructAsArray

                                                            func (e *Encoder) StructAsArray(flag bool) *Encoder

                                                              StructAsArray causes the Encoder to encode Go structs as MessagePack arrays.

                                                              Example
                                                              Output:
                                                              
                                                              [foo bar]
                                                              

                                                              func (*Encoder) UseCompactEncoding

                                                              func (e *Encoder) UseCompactEncoding(flag bool) *Encoder

                                                                UseCompactEncoding causes the Encoder to chose the most compact encoding. For example, it allows to encode Go int64 as msgpack int8 saving 7 bytes.

                                                                func (*Encoder) UseJSONTag

                                                                func (e *Encoder) UseJSONTag(flag bool) *Encoder

                                                                  UseJSONTag causes the Encoder to use json struct tag as fallback option if there is no msgpack tag.

                                                                  type Marshaler

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

                                                                  type Unmarshaler

                                                                  type Unmarshaler interface {
                                                                  	UnmarshalMsgpack([]byte) error
                                                                  }

                                                                  Directories

                                                                  Path Synopsis