1# UBJSON 2 3Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON. 4 5!!! abstract "References" 6 7 - [UBJSON Website](http://ubjson.org) 8 9## Serialization 10 11The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification: 12 13JSON value type | value/range | UBJSON type | marker 14--------------- | --------------------------------- | ----------- | ------ 15null | `null` | null | `Z` 16boolean | `true` | true | `T` 17boolean | `false` | false | `F` 18number_integer | -9223372036854775808..-2147483649 | int64 | `L` 19number_integer | -2147483648..-32769 | int32 | `l` 20number_integer | -32768..-129 | int16 | `I` 21number_integer | -128..127 | int8 | `i` 22number_integer | 128..255 | uint8 | `U` 23number_integer | 256..32767 | int16 | `I` 24number_integer | 32768..2147483647 | int32 | `l` 25number_integer | 2147483648..9223372036854775807 | int64 | `L` 26number_unsigned | 0..127 | int8 | `i` 27number_unsigned | 128..255 | uint8 | `U` 28number_unsigned | 256..32767 | int16 | `I` 29number_unsigned | 32768..2147483647 | int32 | `l` 30number_unsigned | 2147483648..9223372036854775807 | int64 | `L` 31number_unsigned | 2147483649..18446744073709551615 | high-precision | `H` 32number_float | *any value* | float64 | `D` 33string | *with shortest length indicator* | string | `S` 34array | *see notes on optimized format* | array | `[` 35object | *see notes on optimized format* | map | `{` 36 37!!! success "Complete mapping" 38 39 The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value. 40 41 Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`. 42 43!!! warning "Size constraints" 44 45 The following values can **not** be converted to a UBJSON value: 46 47 - strings with more than 9223372036854775807 bytes (theoretical) 48 49!!! info "Unused UBJSON markers" 50 51 The following markers are not used in the conversion: 52 53 - `Z`: no-op values are not created. 54 - `C`: single-byte strings are serialized with `S` markers. 55 56!!! info "NaN/infinity handling" 57 58 If NaN or Infinity are stored inside a JSON number, they are 59 serialized properly. This behavior differs from the `dump()` 60 function which serializes NaN or Infinity to `null`. 61 62!!! info "Optimized formats" 63 64 The optimized formats for containers are supported: Parameter 65 `use_size` adds size information to the beginning of a container and 66 removes the closing marker. Parameter `use_type` further checks 67 whether all elements of a container have the same type and adds the 68 type marker to the beginning of the container. The `use_type` 69 parameter must only be used together with `use_size = true`. 70 71 Note that `use_size = true` alone may result in larger representations - 72 the benefit of this parameter is that the receiving side is 73 immediately informed on the number of elements of the container. 74 75!!! info "Binary values" 76 77 If the JSON data contains the binary type, the value stored is a list 78 of integers, as suggested by the UBJSON documentation. In particular, 79 this means that serialization and the deserialization of a JSON 80 containing binary values into UBJSON and back will result in a 81 different JSON object. 82 83 84??? example 85 86 ```cpp 87 --8<-- "examples/to_ubjson.cpp" 88 ``` 89 90 Output: 91 92 ```c 93 --8<-- "examples/to_ubjson.output" 94 ``` 95 96## Deserialization 97 98The library maps UBJSON types to JSON value types as follows: 99 100UBJSON type | JSON value type | marker 101----------- | --------------------------------------- | ------ 102no-op | *no value, next value is read* | `N` 103null | `null` | `Z` 104false | `false` | `F` 105true | `true` | `T` 106float32 | number_float | `d` 107float64 | number_float | `D` 108uint8 | number_unsigned | `U` 109int8 | number_integer | `i` 110int16 | number_integer | `I` 111int32 | number_integer | `l` 112int64 | number_integer | `L` 113string | string | `S` 114char | string | `C` 115array | array (optimized values are supported) | `[` 116object | object (optimized values are supported) | `{` 117 118!!! success "Complete mapping" 119 120 The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. 121 122 123??? example 124 125 ```cpp 126 --8<-- "examples/from_ubjson.cpp" 127 ``` 128 129 Output: 130 131 ```json 132 --8<-- "examples/from_ubjson.output" 133 ``` 134