JSON for Modern C++  3.6.1

◆ 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>
static std::vector<uint8_t> nlohmann::basic_json::to_ubjson ( const basic_json j,
const bool  use_size = false,
const bool  use_type = false 
)
inlinestatic

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]jJSON value to serialize
[in]use_sizewhether to add size annotations to container types
[in]use_typewhether 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.
1 #include <iostream>
2 #include <iomanip>
3 #include <nlohmann/json.hpp>
4 
5 using json = nlohmann::json;
6 
7 // function to print UBJSON's diagnostic format
8 void print_byte(uint8_t byte)
9 {
10  if (32 < byte and byte < 128)
11  {
12  std::cout << (char)byte;
13  }
14  else
15  {
16  std::cout << (int)byte;
17  }
18 }
19 
20 int main()
21 {
22  // create a JSON value
23  json j = R"({"compact": true, "schema": false})"_json;
24 
25  // serialize it to UBJSON
26  std::vector<uint8_t> v = json::to_ubjson(j);
27 
28  // print the vector content
29  for (auto& byte : v)
30  {
31  print_byte(byte);
32  }
33  std::cout << std::endl;
34 
35  // create an array of numbers
36  json array = {1, 2, 3, 4, 5, 6, 7, 8};
37 
38  // serialize it to UBJSON using default representation
39  std::vector<uint8_t> v_array = json::to_ubjson(array);
40  // serialize it to UBJSON using size optimization
41  std::vector<uint8_t> v_array_size = json::to_ubjson(array, true);
42  // serialize it to UBJSON using type optimization
43  std::vector<uint8_t> v_array_size_and_type = json::to_ubjson(array, true, true);
44 
45  // print the vector contents
46  for (auto& byte : v_array)
47  {
48  print_byte(byte);
49  }
50  std::cout << std::endl;
51 
52  for (auto& byte : v_array_size)
53  {
54  print_byte(byte);
55  }
56  std::cout << std::endl;
57 
58  for (auto& byte : v_array_size_and_type)
59  {
60  print_byte(byte);
61  }
62  std::cout << std::endl;
63 }
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
Definition: json.hpp:19432
basic_json<> json
default JSON class
Definition: json.hpp:871
static JSON_NODISCARD basic_json array(initializer_list_t init={})
explicitly create an array from an initializer list
Definition: json.hpp:14263

Output (play with this example online):
{i7compactTi6schemaF}
[i1i2i3i4i5i6i7i8]
[#i8i1i2i3i4i5i6i7i8
[$i#i812345678
The example code above can be translated with
g++ -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 19432 of file json.hpp.