The highest tagged major version isv5.
msgpack
packagemodule
This package is not in the latest version of its module.
Details
Valid go.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable licenseRedistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
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 individual empty fields via
msgpack:",omitempty"tag or allempty fields in a struct. - Map keys sorting.
- Encoding/decoding allstructs as arrays orindividual structs.
- Encoder.UseJSONTag withDecoder.UseJSONTag can turn msgpack into drop-in replacement for JSON.
- Simple but very fast and efficientqueries.
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/msgpackQuickstart
func ExampleMarshal() {type Item struct {Foo string}b, err := msgpack.Marshal(&Item{Foo: "bar"})if err != nil {panic(err)}var item Itemerr = 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/opBenchmarkStructUgorjiGoMsgpack-4 100000 17678 ns/op 3616 B/op 70 allocs/opBenchmarkStructUgorjiGoCodec-4 100000 19053 ns/op 7346 B/op 23 allocs/opBenchmarkStructJSON-4 20000 69438 ns/op 7864 B/op 26 allocs/opBenchmarkStructGOB-4 10000 104331 ns/op 14664 B/op 278 allocs/opHowto
Please go throughexamples 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) DecodeExtHeader() (typeId int8, length int, err 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) DecodeInterfaceLoose() (interface{}, error)
- func (d *Decoder) DecodeMap() (interface{}, error)
- func (d *Decoder) DecodeMapLen() (int, error)
- func (d *Decoder) DecodeMulti(v ...interface{}) 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() (codes.Code, 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
- func (d *Decoder) UseDecodeInterfaceLoose(flag bool) *Decoder
- func (d *Decoder) UseJSONTag(v bool) *Decoder
- 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) EncodeExtHeader(typeId int8, length int) error
- func (e *Encoder) EncodeFloat32(n float32) error
- func (e *Encoder) EncodeFloat64(n float64) error
- func (e *Encoder) EncodeInt(n int64) error
- func (e *Encoder) EncodeInt16(n int16) error
- func (e *Encoder) EncodeInt32(n int32) error
- func (e *Encoder) EncodeInt64(n int64) error
- func (e *Encoder) EncodeInt8(n int8) error
- func (e *Encoder) EncodeMapLen(l int) error
- func (e *Encoder) EncodeMulti(v ...interface{}) 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(n uint64) error
- func (e *Encoder) EncodeUint16(n uint16) error
- func (e *Encoder) EncodeUint32(n uint32) error
- func (e *Encoder) EncodeUint64(n uint64) error
- func (e *Encoder) EncodeUint8(n uint8) error
- func (e *Encoder) EncodeValue(v reflect.Value) error
- func (e *Encoder) SortMapKeys(flag bool) *Encoder
- func (e *Encoder) StructAsArray(flag bool) *Encoder
- func (e *Encoder) UseCompactEncoding(flag bool) *Encoder
- func (e *Encoder) UseJSONTag(flag bool) *Encoder
- type Marshaler
- type Unmarshaler
Examples¶
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcMarshal¶
Marshal returns the MessagePack encoding of v.
Example¶
package mainimport ("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 Itemerr = msgpack.Unmarshal(b, &item)if err != nil {panic(err)}fmt.Println(item.Foo)}Output:bar
Example (AsArray)¶
package mainimport ("bytes""fmt""github.com/vmihailenco/msgpack")func main() {type Item struct {_msgpack struct{} `msgpack:",asArray"`Foo stringBar string}var buf bytes.Bufferenc := 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 mainimport ("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 = 1hello = world
Example (OmitEmpty)¶
package mainimport ("fmt""github.com/vmihailenco/msgpack")func main() {type Item struct {Foo stringBar 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 stringBar 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"
funcRegister¶
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 implementingMarshaler/CustomEncoder and Unmarshaler/CustomDecoder interfaces.
funcRegisterExt¶
func RegisterExt(idint8, 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 valuesent or received as an interface variable. Only types that will betransferred as implementations of interface values need to be registered.Expecting to be used only during initialization, it panics if the mappingbetween types and ids is not a bijection.
Example¶
package mainimport ("encoding/binary""fmt""time""github.com/vmihailenco/msgpack")func init() {msgpack.RegisterExt(1, (*EventTime)(nil))}// https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1#eventtime-ext-formattype 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 UTC1973-11-29 21:33:09.000000123 +0000 UTC
Types¶
typeCustomDecoder¶
typeCustomEncoder¶
Example¶
package mainimport ("fmt""github.com/vmihailenco/msgpack")type customStruct struct {S stringN int}var _ msgpack.CustomEncoder = (*customStruct)(nil)var _ msgpack.CustomDecoder = (*customStruct)(nil)func (s *customStruct) EncodeMsgpack(enc *msgpack.Encoder) error {return enc.EncodeMulti(s.S, s.N)}func (s *customStruct) DecodeMsgpack(dec *msgpack.Decoder) error {return dec.DecodeMulti(&s.S, &s.N)}func main() {b, err := msgpack.Marshal(&customStruct{S: "hello", N: 42})if err != nil {panic(err)}var v customStructerr = msgpack.Unmarshal(b, &v)if err != nil {panic(err)}fmt.Printf("%#v", v)}Output:msgpack_test.customStruct{S:"hello", N:42}
typeDecoder¶
type Decoder struct {// contains filtered or unexported fields}funcNewDecoder¶
NewDecoder returns a new decoder that reads from r.
The decoder introduces its own buffering and may read data from rbeyond the MessagePack values requested. Buffering can be disabledby passing a reader that implements io.ByteScanner interface.
func (*Decoder)DecodeArrayLen¶
DecodeArrayLen decodes array length. Length is -1 when array is nil.
func (*Decoder)DecodeBool¶
func (*Decoder)DecodeBytes¶
func (*Decoder)DecodeBytesLen¶
func (*Decoder)DecodeExtHeader¶
func (*Decoder)DecodeFloat32¶
func (*Decoder)DecodeFloat64¶
DecodeFloat64 decodes msgpack float32/64 into Go float64.
func (*Decoder)DecodeInt16¶
func (*Decoder)DecodeInt32¶
func (*Decoder)DecodeInt64¶
DecodeInt64 decodes msgpack int8/16/32/64 and uint8/16/32/64into Go int64.
func (*Decoder)DecodeInt8¶
func (*Decoder)DecodeInterface¶
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 valueyou are decoding. For example, if you are decoding number it is better to useDecodeInt64 for negative numbers and DecodeUint64 for positive numbers.
func (*Decoder)DecodeInterfaceLoose¶
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)DecodeMapLen¶
DecodeMapLen decodes map length. Length is -1 when map is nil.
func (*Decoder)DecodeMulti¶
func (*Decoder)DecodeSlice¶
func (*Decoder)DecodeString¶
func (*Decoder)DecodeUint¶
func (*Decoder)DecodeUint16¶
func (*Decoder)DecodeUint32¶
func (*Decoder)DecodeUint64¶
DecodeUint64 decodes msgpack int8/16/32/64 and uint8/16/32/64into Go uint64.
func (*Decoder)DecodeUint8¶
func (*Decoder)PeekCode¶
PeekCode returns the next MessagePack code without advancing the reader.Subpackage msgpack/codes contains list of available codes.
func (*Decoder)Query¶
Query extracts data specified by the query from the msgpack stream skippingany other data. Query consists of map keys and array indexes separated with dot,e.g. key1.0.key2.
Example¶
package mainimport ("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 mainimport ("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)// Causes decoder to produce map[string]string instead of map[string]interface{}.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.Printf("%#v", out)}Output:map[string]string{"hello":"world"}
func (*Decoder)UseDecodeInterfaceLoose¶
UseDecodeInterfaceLoose causes decoder to use DecodeInterfaceLooseto decode msgpack value into Go interface{}.
func (*Decoder)UseJSONTag¶
UseJSONTag causes the Decoder to use json struct tag as fallback optionif there is no msgpack tag.
typeEncoder¶
type Encoder struct {// contains filtered or unexported fields}funcNewEncoder¶
NewEncoder returns a new encoder that writes to w.
func (*Encoder)EncodeArrayLen¶
func (*Encoder)EncodeBool¶
func (*Encoder)EncodeBytes¶
func (*Encoder)EncodeBytesLen¶
func (*Encoder)EncodeFloat32¶
func (*Encoder)EncodeFloat64¶
func (*Encoder)EncodeInt¶
EncodeNumber encodes an int64 in 1, 2, 3, 5, or 9 bytes.Type of number is lost during encoding.
func (*Encoder)EncodeInt16¶
EncodeInt16 encodes an int16 in 3 bytes preserving type of the number.
func (*Encoder)EncodeInt32¶
EncodeInt32 encodes an int32 in 5 bytes preserving type of the number.
func (*Encoder)EncodeInt64¶
EncodeInt64 encodes an int64 in 9 bytes preserving type of the number.
func (*Encoder)EncodeInt8¶
EncodeInt8 encodes an int8 in 2 bytes preserving type of the number.
func (*Encoder)EncodeMapLen¶
func (*Encoder)EncodeMulti¶
func (*Encoder)EncodeString¶
func (*Encoder)EncodeUint¶
EncodeUnsignedNumber encodes an uint64 in 1, 2, 3, 5, or 9 bytes.Type of the number is lost during encoding.
func (*Encoder)EncodeUint16¶
EncodeUint16 encodes an uint16 in 3 bytes preserving type of the number.
func (*Encoder)EncodeUint32¶
EncodeUint32 encodes an uint16 in 5 bytes preserving type of the number.
func (*Encoder)EncodeUint64¶
EncodeUint64 encodes an uint16 in 9 bytes preserving type of the number.
func (*Encoder)EncodeUint8¶
EncodeUint8 encodes an uint8 in 2 bytes preserving type of the number.
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 mainimport ("bytes""fmt""github.com/vmihailenco/msgpack")func main() {type Item struct {Foo stringBar string}var buf bytes.Bufferenc := 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]
func (*Encoder)UseCompactEncoding¶
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¶
UseJSONTag causes the Encoder to use json struct tag as fallback optionif there is no msgpack tag.
Source Files
Directories