msgpack

package module
v3.2.6+incompatible Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2018 License: BSD-2-Clause Imports: 14 Imported by: 0

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

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 
package main

import (
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	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
Example (AsArray) 
package main

import (
	"bytes"
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	type Item struct {
		_msgpack struct{} `msgpack:",asArray"`
		Foo      string
		Bar      string
	}

	var buf bytes.Buffer
	enc := msgpack.NewEncoder(&buf)
	err := enc.Encode(&Item{Foo: "foo", Bar: "bar"})
	if err != nil {
		panic(err)
	}

	dec := msgpack.NewDecoder(&buf)
	v, err := dec.DecodeInterface()
	if err != nil {
		panic(err)
	}
	fmt.Println(v)
}

Output:

[foo bar]
Example (MapStringInterface) 
package main

import (
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	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 (OmitEmpty) 
package main

import (
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	type Item struct {
		Foo string
		Bar string
	}

	item := &Item{
		Foo: "hello",
	}
	b, err := msgpack.Marshal(item)
	if err != nil {
		panic(err)
	}
	fmt.Printf("item: %q\n", b)

	type ItemOmitEmpty struct {
		_msgpack struct{} `msgpack:",omitempty"`
		Foo      string
		Bar      string
	}

	itemOmitEmpty := &ItemOmitEmpty{
		Foo: "hello",
	}
	b, err = msgpack.Marshal(itemOmitEmpty)
	if err != nil {
		panic(err)
	}
	fmt.Printf("item2: %q\n", b)

}

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 
package main

import (
	"encoding/binary"
	"fmt"
	"time"

	"github.com/vmihailenco/msgpack"
)

func init() {
	msgpack.RegisterExt(0, (*EventTime)(nil))
}

// https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1#eventtime-ext-format
type EventTime struct {
	time.Time
}

var _ msgpack.Marshaler = (*EventTime)(nil)
var _ msgpack.Unmarshaler = (*EventTime)(nil)

func (tm *EventTime) MarshalMsgpack() ([]byte, error) {
	b := make([]byte, 8)
	binary.BigEndian.PutUint32(b, uint32(tm.Unix()))
	binary.BigEndian.PutUint32(b[4:], uint32(tm.Nanosecond()))
	return b, nil
}

func (tm *EventTime) UnmarshalMsgpack(b []byte) error {
	if len(b) != 8 {
		return fmt.Errorf("invalid data length: got %d, wanted 8", len(b))
	}
	sec := binary.BigEndian.Uint32(b)
	usec := binary.BigEndian.Uint32(b[4:])
	tm.Time = time.Unix(int64(sec), int64(usec))
	return nil
}

func main() {
	b, err := msgpack.Marshal(&EventTime{time.Unix(123456789, 123)})
	if err != nil {
		panic(err)
	}

	var v interface{}
	err = msgpack.Unmarshal(b, &v)
	if err != nil {
		panic(err)
	}
	fmt.Println(v.(*EventTime).UTC())

	tm := new(EventTime)
	err = msgpack.Unmarshal(b, tm)
	if err != nil {
		panic(err)
	}
	fmt.Println(tm.UTC())

}

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 
package main

import (
	"fmt"

	"github.com/vmihailenco/msgpack"
)

type customStruct struct {
	S string
	N int
}

var _ msgpack.CustomEncoder = (*customStruct)(nil)
var _ msgpack.CustomDecoder = (*customStruct)(nil)

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 {
	// 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)

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,
  • 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.

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)

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)

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 
package main

import (
	"bytes"
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	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) SetDecodeMapFunc 

func (d *Decoder) SetDecodeMapFunc(fn func(*Decoder) (interface{}, error))
Example 
package main

import (
	"bytes"
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	buf := new(bytes.Buffer)

	enc := msgpack.NewEncoder(buf)
	in := map[string]string{"hello": "world"}
	err := enc.Encode(in)
	if err != nil {
		panic(err)
	}

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

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

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

			m[mk] = mv
		}
		return m, nil
	})

	out, err := dec.DecodeInterface()
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Output:

map[hello:world]

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

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) 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 int64) error

EncodeInt encodes an int64 in 1, 2, 3, 5, or 9 bytes.

func (*Encoder) EncodeMapLen 

func (e *Encoder) EncodeMapLen(l int) 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(v uint64) error

EncodeUint encodes an uint64 in 1, 2, 3, 5, or 9 bytes.

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{}

func (*Encoder) StructAsArray 

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

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

Example 
package main

import (
	"bytes"
	"fmt"

	"github.com/vmihailenco/msgpack"
)

func main() {
	type Item struct {
		Foo string
		Bar string
	}

	var buf bytes.Buffer
	enc := msgpack.NewEncoder(&buf).StructAsArray(true)
	err := enc.Encode(&Item{Foo: "foo", Bar: "bar"})
	if err != nil {
		panic(err)
	}

	dec := msgpack.NewDecoder(&buf)
	v, err := dec.DecodeInterface()
	if err != nil {
		panic(err)
	}
	fmt.Println(v)
}

Output:

[foo bar]

type Marshaler 

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

type Unmarshaler 

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

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.