|
◆ to_ubjson() [1/3]
template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer>
Serializes a given JSON value j to a byte vector using the UBJSON (Universal Binary JSON) serialization format. UBJSON aims to be more compact than JSON itself, yet more efficient to parse.
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
JSON value type | value/range | UBJSON type | marker |
null | null | null | Z |
boolean | true | true | T |
boolean | false | false | F |
number_integer | -9223372036854775808..-2147483649 | int64 | L |
number_integer | -2147483648..-32769 | int32 | l |
number_integer | -32768..-129 | int16 | I |
number_integer | -128..127 | int8 | i |
number_integer | 128..255 | uint8 | U |
number_integer | 256..32767 | int16 | I |
number_integer | 32768..2147483647 | int32 | l |
number_integer | 2147483648..9223372036854775807 | int64 | L |
number_unsigned | 0..127 | int8 | i |
number_unsigned | 128..255 | uint8 | U |
number_unsigned | 256..32767 | int16 | I |
number_unsigned | 32768..2147483647 | int32 | l |
number_unsigned | 2147483648..9223372036854775807 | int64 | L |
number_float | any value | float64 | D |
string | with shortest length indicator | string | S |
array | see notes on optimized format | array | [ |
object | see notes on optimized format | map | { |
- Note
- The mapping is complete in the sense that any JSON value type can be converted to a UBJSON value.
-
The following values can not be converted to a UBJSON value:
- strings with more than 9223372036854775807 bytes (theoretical)
- unsigned integer numbers above 9223372036854775807
-
The following markers are not used in the conversion:
Z : no-op values are not created.
C : single-byte strings are serialized with S markers.
-
Any UBJSON output created to_ubjson can be successfully parsed by from_ubjson.
-
If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the dump() function which serializes NaN or Infinity to
null .
-
The optimized formats for containers are supported: Parameter use_size adds size information to the beginning of a container and removes the closing marker. Parameter use_type further checks whether all elements of a container have the same type and adds the type marker to the beginning of the container. The use_type parameter must only be used together with use_size = true. Note that use_size = true alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed on the number of elements of the container.
- Parameters
-
[in] | j | JSON value to serialize |
[in] | use_size | whether to add size annotations to container types |
[in] | use_type | whether to add type annotations to container types (must be combined with use_size = true) |
- Returns
- UBJSON serialization as byte vector
- Complexity^^ Linear in the size of the JSON value j.
- Example^^ The example shows the serialization of a JSON value to a byte
- vector in UBJSON format. ^^
3 #include <nlohmann/json.hpp> 8 void print_byte(uint8_t byte) 10 if (32 < byte and byte < 128) 12 std::cout << (char)byte; 16 std::cout << (int)byte; 23 json j = R "({"compact": true, "schema": false})"_json; 33 std::cout << std::endl; 36 json array = {1, 2, 3, 4, 5, 6, 7, 8}; 43 std::vector<uint8_t> v_array_size_and_type = json::to_ubjson(array, true, true); 46 for ( auto& byte : v_array) 50 std::cout << std::endl; 52 for ( auto& byte : v_array_size) 56 std::cout << std::endl; 58 for ( auto& byte : v_array_size_and_type) 62 std::cout << std::endl; static std::vector< uint8_t > to_ubjson(const basic_json &j, const bool use_size=false, const bool use_type=false) create a UBJSON serialization of a given JSON value
basic_json<> json default JSON class
Output (play with this example online):^^ {i7compactTi6schemaF}
[i1i2i3i4i5i6i7i8]
[#i8i1i2i3i4i5i6i7i8
[$i#i812345678
^^ The example code above can be translated withg++ -std=c++11 -Isingle_include doc/examples/to_ubjson.cpp -o to_ubjson
- See also
- http://ubjson.org
-
from_ubjson(detail::input_adapter&&, const bool, const bool) for the analogous deserialization
-
to_cbor(const basic_json& for the related CBOR format
-
to_msgpack(const basic_json&) for the related MessagePack format
- Since
- version 3.1.0
Definition at line 19015 of file json.hpp.
|