msgpack

package module
v2.6.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2016 License: BSD-3-Clause Imports: 14 Imported by: 0

README

MessagePack encoding for Golang Build Status

Supports:

  • Primitives, arrays, maps, structs, time.Time and interface{}.
  • Appengine *datastore.Key and datastore.Cursor.
  • CustomEncoder/CustomDecoder interfaces for custom encoding.
  • Extensions to encode type information.
  • Fields renaming using msgpack:"my_field_name".
  • Structs inlining using msgpack:",inline".
  • Omitempty flag using msgpack:",omitempty".
  • Map keys sorting.

API docs: http://godoc.org/gopkg.in/vmihailenco/msgpack.v2. Examples: http://godoc.org/gopkg.in/vmihailenco/msgpack.v2#pkg-examples.

Installation

Install:

go get gopkg.in/vmihailenco/msgpack.v2

Quickstart

func ExampleMarshal() {
	b, err := msgpack.Marshal(true)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%#v\n", b)
	// Output:

	var out bool
	err = msgpack.Unmarshal([]byte{0xc3}, &out)
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
	// Output: []byte{0xc3}
	// true
}

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.

Documentation

Overview

Example (DecodeMapStringString) 
decodedMap := make(map[string]string)
buf := &bytes.Buffer{}

m := map[string]string{"foo1": "bar1", "foo2": "bar2", "foo3": "bar3"}
keys := []string{"foo1", "foo3", "foo2"}

encodedMap, err := encodeMap(m, keys...)
if err != nil {
	panic(err)
}

_, err = buf.Write(encodedMap)
if err != nil {
	panic(err)
}

decoder := msgpack.NewDecoder(buf)

n, err := decoder.DecodeMapLen()
if err != nil {
	panic(err)
}

for i := 0; i < n; i++ {
	key, err := decoder.DecodeString()
	if err != nil {
		panic(err)
	}
	value, err := decoder.DecodeString()
	if err != nil {
		panic(err)
	}
	decodedMap[key] = value
}

for _, key := range keys {
	fmt.Printf("%#v: %#v, ", key, decodedMap[key])
}

Output:

"foo1": "bar1", "foo3": "bar3", "foo2": "bar2",
Example (EncodeMapStringString) 
buf := &bytes.Buffer{}

m := map[string]string{"foo1": "bar1", "foo2": "bar2", "foo3": "bar3"}
keys := []string{"foo1", "foo3"}

encodedMap, err := encodeMap(m, keys...)
if err != nil {
	panic(err)
}

_, err = buf.Write(encodedMap)
if err != nil {
	panic(err)
}

decoder := msgpack.NewDecoder(buf)
value, err := decoder.DecodeMap()
if err != nil {
	panic(err)
}

decodedMapValue := value.(map[interface{}]interface{})

for _, key := range keys {
	fmt.Printf("%#v: %#v, ", key, decodedMapValue[key])
}

Output:

"foo1": "bar1", "foo3": "bar3",
Example (MapStringInterface) 
in := map[string]interface{}{"foo": 1, "hello": "world"}
b, err := msgpack.Marshal(in)
if err != nil {
	panic(err)
}

var out map[string]interface{}
err = msgpack.Unmarshal(b, &out)
if err != nil {
	panic(err)
}

fmt.Println("foo =", out["foo"])
fmt.Println("hello =", out["hello"])

Output:

foo = 1
hello = world
Example (RecursiveMapStringInterface) 
buf := new(bytes.Buffer)

enc := msgpack.NewEncoder(buf)
in := map[string]interface{}{"foo": map[string]interface{}{"hello": "world"}}
_ = enc.Encode(in)

dec := msgpack.NewDecoder(buf)
dec.DecodeMapFunc = func(d *msgpack.Decoder) (interface{}, error) {
	n, err := d.DecodeMapLen()
	if err != nil {
		return nil, err
	}

	m := make(map[string]interface{}, n)
	for i := 0; i < n; i++ {
		mk, err := d.DecodeString()
		if err != nil {
			return nil, err
		}

		mv, err := d.DecodeInterface()
		if err != nil {
			return nil, err
		}

		m[mk] = mv
	}
	return m, nil
}
out, err := dec.DecodeInterface()
fmt.Printf("%v %#v\n", err, out)

Output:

<nil> map[string]interface {}{"foo":map[string]interface {}{"hello":"world"}}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Marshal 

func Marshal(v ...interface{}) ([]byte, error)
Example 
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

func Register 

func Register(typ reflect.Type, enc encoderFunc, dec decoderFunc)

Register registers encoder and decoder functions for a type. In most cases you should prefer implementing CustomEncoder and CustomDecoder interfaces.

func RegisterExt 

func RegisterExt(id int8, value interface{})
Example 
type Item struct {
	S string
}

msgpack.RegisterExt(1, Item{})

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

var v interface{}
err = msgpack.Unmarshal(b, &v)
if err != nil {
	panic(err)
}
fmt.Printf("%#v", v)

Output:

msgpack_test.Item{S:"string"}

func Unmarshal 

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

Types

type CustomDecoder 

type CustomDecoder interface {
	DecodeMsgpack(*Decoder) error
}

type CustomEncoder 

type CustomEncoder interface {
	EncodeMsgpack(*Encoder) error
}
Example 
package main

import (
	"fmt"

	"gopkg.in/vmihailenco/msgpack.v2"
)

type customStruct struct {
	S string
	N int
}

var (
	_ msgpack.CustomEncoder = &customStruct{}
	_ msgpack.CustomDecoder = &customStruct{}
)

func (s *customStruct) EncodeMsgpack(enc *msgpack.Encoder) error {
	return enc.Encode(s.S, s.N)
}

func (s *customStruct) DecodeMsgpack(dec *msgpack.Decoder) error {
	return dec.Decode(&s.S, &s.N)
}

func main() {
	b, err := msgpack.Marshal(&customStruct{S: "hello", N: 42})
	if err != nil {
		panic(err)
	}

	var v customStruct
	err = msgpack.Unmarshal(b, &v)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%#v", v)
}

Output:

msgpack_test.customStruct{S:"hello", N:42}

type Decoder 

type Decoder struct {
	DecodeMapFunc func(*Decoder) (interface{}, error)
	// contains filtered or unexported fields
}

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Decode 

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

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) DecodeFloat32 

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

func (*Decoder) DecodeFloat64 

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

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)

func (*Decoder) DecodeInt8 

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

func (*Decoder) DecodeInterface 

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

DecodeInterface decodes value into interface. Possible value types are:

  • nil,
  • bool,
  • int64 for negative numbers,
  • uint64 for positive numbers,
  • float32 and float64,
  • string,
  • slices of any of the above,
  • maps of any of the above.

func (*Decoder) DecodeMap 

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

func (*Decoder) DecodeMapLen 

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

func (*Decoder) DecodeNil 

func (d *Decoder) DecodeNil() error

func (*Decoder) DecodeSlice 

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

func (*Decoder) DecodeSliceLen 

func (d *Decoder) DecodeSliceLen() (int, 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)

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() (code byte, err error)

peekCode returns the next Msgpack code. See https://github.com/msgpack/msgpack/blob/master/spec.md#formats for details.

func (*Decoder) Query 

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

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

Example 
b, err := msgpack.Marshal([]map[string]interface{}{
	{"id": 1, "attrs": map[string]interface{}{"phone": 12345}},
	{"id": 2, "attrs": map[string]interface{}{"phone": 54321}},
})
if err != nil {
	panic(err)
}

dec := msgpack.NewDecoder(bytes.NewBuffer(b))
values, err := dec.Query("*.attrs.phone")
if err != nil {
	panic(err)
}
fmt.Println("phones are", values)

dec.Reset(bytes.NewBuffer(b))
values, err = dec.Query("1.attrs.phone")
if err != nil {
	panic(err)
}
fmt.Println("2nd phone is", values[0])

Output:

phones are [12345 54321]
2nd phone is 54321

func (*Decoder) Reset 

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

func (*Decoder) Skip 

func (d *Decoder) Skip() error

Skip skips next value.

type Encoder 

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

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

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) 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(v int) error

func (*Encoder) EncodeInt16 

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

func (*Encoder) EncodeInt32 

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

func (*Encoder) EncodeInt64 

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

func (*Encoder) EncodeInt8 

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

func (*Encoder) EncodeMapLen 

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

func (*Encoder) EncodeNil 

func (e *Encoder) EncodeNil() error

func (*Encoder) EncodeSliceLen 

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

Deprecated. Use EncodeArrayLen instead.

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(v uint) error

func (*Encoder) EncodeUint16 

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

func (*Encoder) EncodeUint32 

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

func (*Encoder) EncodeUint64 

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

func (*Encoder) EncodeUint8 

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

func (*Encoder) EncodeValue 

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

func (*Encoder) SortMapKeys 

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

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

  • map[string]string
  • map[string]interface{}

type Marshaler 

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

Deprecated. Use CustomEncoder.

type Unmarshaler 

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

Deprecated. Use CustomDecoder.

Source Files

View all Source files

Directories

Path Synopsis

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.