README
¶
MessagePack encoding for Golang
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.
- Renaming fields via
msgpack:"my_field_name". - Omitting empty fields via
msgpack:",omitempty". - Map keys sorting.
- Encoding/decoding all structs as arrays or individual structs.
- Simple but very fast and efficient queries.
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 ¶
- func Marshal(v ...interface{}) ([]byte, error)
- func Register(value interface{}, enc encoderFunc, dec decoderFunc)
- func RegisterExt(id int8, value interface{})
- func Unmarshal(data []byte, v ...interface{}) error
- type CustomDecoder
- type CustomEncoder
- type Decoder
- func (d *Decoder) Decode(v ...interface{}) error
- func (d *Decoder) DecodeArrayLen() (int, error)
- func (d *Decoder) DecodeBool() (bool, error)
- func (d *Decoder) DecodeBytes() ([]byte, error)
- func (d *Decoder) DecodeBytesLen() (int, error)
- func (d *Decoder) DecodeFloat32() (float32, error)
- func (d *Decoder) DecodeFloat64() (float64, error)
- func (d *Decoder) DecodeInt() (int, error)
- func (d *Decoder) DecodeInt16() (int16, error)
- func (d *Decoder) DecodeInt32() (int32, error)
- func (d *Decoder) DecodeInt64() (int64, error)
- func (d *Decoder) DecodeInt8() (int8, error)
- func (d *Decoder) DecodeInterface() (interface{}, error)
- func (d *Decoder) DecodeMap() (interface{}, error)
- func (d *Decoder) DecodeMapLen() (int, error)
- func (d *Decoder) DecodeNil() error
- func (d *Decoder) DecodeSlice() ([]interface{}, error)
- func (d *Decoder) DecodeString() (string, error)
- func (d *Decoder) DecodeTime() (time.Time, error)
- func (d *Decoder) DecodeUint() (uint, error)
- func (d *Decoder) DecodeUint16() (uint16, error)
- func (d *Decoder) DecodeUint32() (uint32, error)
- func (d *Decoder) DecodeUint64() (uint64, error)
- func (d *Decoder) DecodeUint8() (uint8, error)
- func (d *Decoder) DecodeValue(v reflect.Value) error
- func (d *Decoder) PeekCode() (code byte, err error)
- func (d *Decoder) Query(query string) ([]interface{}, error)
- func (d *Decoder) Reset(r io.Reader) error
- func (d *Decoder) SetDecodeMapFunc(fn func(*Decoder) (interface{}, error))
- func (d *Decoder) Skip() error
- type Encoder
- func (e *Encoder) Encode(v ...interface{}) error
- func (e *Encoder) EncodeArrayLen(l int) error
- func (e *Encoder) EncodeBool(value bool) error
- func (e *Encoder) EncodeBytes(v []byte) error
- func (e *Encoder) EncodeBytesLen(l int) error
- func (e *Encoder) EncodeFloat32(n float32) error
- func (e *Encoder) EncodeFloat64(n float64) error
- func (e *Encoder) EncodeInt(v int64) error
- func (e *Encoder) EncodeMapLen(l int) error
- func (e *Encoder) EncodeNil() error
- func (e *Encoder) EncodeString(v string) error
- func (e *Encoder) EncodeTime(tm time.Time) error
- func (e *Encoder) EncodeUint(v uint64) error
- func (e *Encoder) EncodeValue(v reflect.Value) error
- func (e *Encoder) SortMapKeys(v bool) *Encoder
- func (e *Encoder) StructAsArray(v bool) *Encoder
- type Marshaler
- type Unmarshaler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
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
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())
var tm 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
Types ¶
type CustomDecoder ¶
type CustomEncoder ¶
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 (*Decoder) DecodeArrayLen ¶
func (*Decoder) DecodeBool ¶
func (*Decoder) DecodeBytes ¶
func (*Decoder) DecodeBytesLen ¶
func (*Decoder) DecodeFloat32 ¶
func (*Decoder) DecodeFloat64 ¶
func (*Decoder) DecodeInt16 ¶
func (*Decoder) DecodeInt32 ¶
func (*Decoder) DecodeInt64 ¶
func (*Decoder) DecodeInt8 ¶
func (*Decoder) DecodeInterface ¶
DecodeInterface decodes value into interface. Possible value types are:
- nil,
- bool,
- int8, int16, int32, int64,
- uint8, uint16, uint32, uint64,
- float32 and float64,
- string,
- slices of any of the above,
- maps of any of the above.
func (*Decoder) DecodeMapLen ¶
func (*Decoder) DecodeSlice ¶
func (*Decoder) DecodeString ¶
func (*Decoder) DecodeUint ¶
func (*Decoder) DecodeUint16 ¶
func (*Decoder) DecodeUint32 ¶
func (*Decoder) DecodeUint64 ¶
func (*Decoder) DecodeUint8 ¶
func (*Decoder) PeekCode ¶
peekCode returns next MessagePack code. See https://github.com/msgpack/msgpack/blob/master/spec.md#formats for details.
func (*Decoder) Query ¶
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) SetDecodeMapFunc ¶
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]
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
func NewEncoder ¶
func (*Encoder) EncodeArrayLen ¶
func (*Encoder) EncodeBool ¶
func (*Encoder) EncodeBytes ¶
func (*Encoder) EncodeBytesLen ¶
func (*Encoder) EncodeFloat32 ¶
func (*Encoder) EncodeFloat64 ¶
func (*Encoder) EncodeMapLen ¶
func (*Encoder) EncodeString ¶
func (*Encoder) EncodeUint ¶
EncodeUint encodes an uint64 in 1, 2, 3, 5, or 9 bytes.
func (*Encoder) SortMapKeys ¶
SortMapKeys causes the Encoder to encode map keys in increasing order. Supported map types are:
- map[string]string
- map[string]interface{}
func (*Encoder) StructAsArray ¶
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 Unmarshaler ¶
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.