vendor/github.com/vmihailenco/msgpack/README.md

   1 # MessagePack encoding for Golang
   2
   3 [![Build Status](https://travis-ci.org/vmihailenco/msgpack.svg?branch=v2)](https://travis-ci.org/vmihailenco/msgpack)
   4 [![GoDoc](https://godoc.org/github.com/vmihailenco/msgpack?status.svg)](https://godoc.org/github.com/vmihailenco/msgpack)
   5
   6 Supports:
   7 - Primitives, arrays, maps, structs, time.Time and interface{}.
   8 - Appengine *datastore.Key and datastore.Cursor.
   9 - [CustomEncoder](https://godoc.org/github.com/vmihailenco/msgpack#example-CustomEncoder)/CustomDecoder interfaces for custom encoding.
  10 - [Extensions](https://godoc.org/github.com/vmihailenco/msgpack#example-RegisterExt) to encode type information.
  11 - Renaming fields via `msgpack:"my_field_name"`.
  12 - Omitting individual empty fields via `msgpack:",omitempty"` tag or all [empty fields in a struct](https://godoc.org/github.com/vmihailenco/msgpack#example-Marshal--OmitEmpty).
  13 - [Map keys sorting](https://godoc.org/github.com/vmihailenco/msgpack#Encoder.SortMapKeys).
  14 - Encoding/decoding all [structs as arrays](https://godoc.org/github.com/vmihailenco/msgpack#Encoder.StructAsArray) or [individual structs](https://godoc.org/github.com/vmihailenco/msgpack#example-Marshal--AsArray).
  15 - [Encoder.UseJSONTag](https://godoc.org/github.com/vmihailenco/msgpack#Encoder.UseJSONTag) with [Decoder.UseJSONTag](https://godoc.org/github.com/vmihailenco/msgpack#Decoder.UseJSONTag) can turn msgpack into drop-in replacement for JSON.
  16 - Simple but very fast and efficient [queries](https://godoc.org/github.com/vmihailenco/msgpack#example-Decoder-Query).
  17
  18 API docs: https://godoc.org/github.com/vmihailenco/msgpack.
  19 Examples: https://godoc.org/github.com/vmihailenco/msgpack#pkg-examples.
  20
  21 ## Installation
  22
  23 Install:
  24
  25 ```shell
  26 go get -u github.com/vmihailenco/msgpack
  27 ```
  28
  29 ## Quickstart
  30
  31 ```go
  32 func ExampleMarshal() {
  33         type Item struct {
  34                 Foo string
  35         }
  36
  37         b, err := msgpack.Marshal(&Item{Foo: "bar"})
  38         if err != nil {
  39                 panic(err)
  40         }
  41
  42         var item Item
  43         err = msgpack.Unmarshal(b, &item)
  44         if err != nil {
  45                 panic(err)
  46         }
  47         fmt.Println(item.Foo)
  48         // Output: bar
  49 }
  50 ```
  51
  52 ## Benchmark
  53
  54 ```
  55 BenchmarkStructVmihailencoMsgpack-4       200000             12814 ns/op            2128 B/op         26 allocs/op
  56 BenchmarkStructUgorjiGoMsgpack-4          100000             17678 ns/op            3616 B/op         70 allocs/op
  57 BenchmarkStructUgorjiGoCodec-4            100000             19053 ns/op            7346 B/op         23 allocs/op
  58 BenchmarkStructJSON-4                      20000             69438 ns/op            7864 B/op         26 allocs/op
  59 BenchmarkStructGOB-4                       10000            104331 ns/op           14664 B/op        278 allocs/op
  60 ```
  61
  62 ## Howto
  63
  64 Please go through [examples](https://godoc.org/github.com/vmihailenco/msgpack#pkg-examples) to get an idea how to use this package.
  65
  66 ## See also
  67
  68 - [Golang PostgreSQL ORM](https://github.com/go-pg/pg)
  69 - [Golang message task queue](https://github.com/go-msgqueue/msgqueue)