1# MessagePack 2 3MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves. 4 5!!! abstract "References" 6 7 - [MessagePack website](https://msgpack.org) 8 - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) 9 10## Serialization 11 12The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification: 13 14JSON value type | value/range | MessagePack type | first byte 15--------------- | --------------------------------- | ---------------- | ---------- 16null | `null` | nil | 0xC0 17boolean | `true` | true | 0xC3 18boolean | `false` | false | 0xC2 19number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3 20number_integer | -2147483648..-32769 | int32 | 0xD2 21number_integer | -32768..-129 | int16 | 0xD1 22number_integer | -128..-33 | int8 | 0xD0 23number_integer | -32..-1 | negative fixint | 0xE0..0xFF 24number_integer | 0..127 | positive fixint | 0x00..0x7F 25number_integer | 128..255 | uint 8 | 0xCC 26number_integer | 256..65535 | uint 16 | 0xCD 27number_integer | 65536..4294967295 | uint 32 | 0xCE 28number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF 29number_unsigned | 0..127 | positive fixint | 0x00..0x7F 30number_unsigned | 128..255 | uint 8 | 0xCC 31number_unsigned | 256..65535 | uint 16 | 0xCD 32number_unsigned | 65536..4294967295 | uint 32 | 0xCE 33number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF 34number_float | *any value representable by a float* | float 32 | 0xCA 35number_float | *any value NOT representable by a float* | float 64 | 0xCB 36string | *length*: 0..31 | fixstr | 0xA0..0xBF 37string | *length*: 32..255 | str 8 | 0xD9 38string | *length*: 256..65535 | str 16 | 0xDA 39string | *length*: 65536..4294967295 | str 32 | 0xDB 40array | *size*: 0..15 | fixarray | 0x90..0x9F 41array | *size*: 16..65535 | array 16 | 0xDC 42array | *size*: 65536..4294967295 | array 32 | 0xDD 43object | *size*: 0..15 | fix map | 0x80..0x8F 44object | *size*: 16..65535 | map 16 | 0xDE 45object | *size*: 65536..4294967295 | map 32 | 0xDF 46binary | *size*: 0..255 | bin 8 | 0xC4 47binary | *size*: 256..65535 | bin 16 | 0xC5 48binary | *size*: 65536..4294967295 | bin 32 | 0xC6 49 50!!! success "Complete mapping" 51 52 The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value. 53 54 Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. 55 56!!! warning "Size constraints" 57 58 The following values can **not** be converted to a MessagePack value: 59 60 - strings with more than 4294967295 bytes 61 - byte strings with more than 4294967295 bytes 62 - arrays with more than 4294967295 elements 63 - objects with more than 4294967295 elements 64 65!!! info "NaN/infinity handling" 66 67 If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`. 68 69??? example 70 71 ```cpp 72 --8<-- "examples/to_msgpack.cpp" 73 ``` 74 75 Output: 76 77 ```c 78 --8<-- "examples/to_msgpack.output" 79 ``` 80 81## Deserialization 82 83The library maps MessagePack types to JSON value types as follows: 84 85MessagePack type | JSON value type | first byte 86---------------- | --------------- | ---------- 87positive fixint | number_unsigned | 0x00..0x7F 88fixmap | object | 0x80..0x8F 89fixarray | array | 0x90..0x9F 90fixstr | string | 0xA0..0xBF 91nil | `null` | 0xC0 92false | `false` | 0xC2 93true | `true` | 0xC3 94float 32 | number_float | 0xCA 95float 64 | number_float | 0xCB 96uint 8 | number_unsigned | 0xCC 97uint 16 | number_unsigned | 0xCD 98uint 32 | number_unsigned | 0xCE 99uint 64 | number_unsigned | 0xCF 100int 8 | number_integer | 0xD0 101int 16 | number_integer | 0xD1 102int 32 | number_integer | 0xD2 103int 64 | number_integer | 0xD3 104str 8 | string | 0xD9 105str 16 | string | 0xDA 106str 32 | string | 0xDB 107array 16 | array | 0xDC 108array 32 | array | 0xDD 109map 16 | object | 0xDE 110map 32 | object | 0xDF 111bin 8 | binary | 0xC4 112bin 16 | binary | 0xC5 113bin 32 | binary | 0xC6 114ext 8 | binary | 0xC7 115ext 16 | binary | 0xC8 116ext 32 | binary | 0xC9 117fixext 1 | binary | 0xD4 118fixext 2 | binary | 0xD5 119fixext 4 | binary | 0xD6 120fixext 8 | binary | 0xD7 121fixext 16 | binary | 0xD8 122negative fixint | number_integer | 0xE0-0xFF 123 124!!! info 125 126 Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`. 127 128 129??? example 130 131 ```cpp 132 --8<-- "examples/from_msgpack.cpp" 133 ``` 134 135 Output: 136 137 ```json 138 --8<-- "examples/from_msgpack.output" 139 ``` 140