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, class BinaryType = std::vector<std::uint8_t>>

static std::vector< std::uint8_t > nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::to_ubjson ( const basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType > &  j, const bool  use_size = false, const bool  use_type = false  )

inlinestatic

create a UBJSON serialization of a given JSON value

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_unsigned	2147483649..18446744073709551615	high-precision	H
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)

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.

If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON documentation. In particular, this means that serialization and the deserialization of a JSON containing binary values into UBJSON and back will result in a different JSON object.

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.

@liveexample{The example shows the serialization of a JSON value to a byte vector in UBJSON format.,to_ubjson}

See also

http://ubjson.org

see from_ubjson(InputType&&, const bool, const bool) for the analogous deserialization

see to_cbor(const basic_json& for the related CBOR format

see to_msgpack(const basic_json&) for the related MessagePack format

Since

version 3.1.0

Definition at line 25239 of file json.hpp.

    {
        std::vector<std::uint8_t> result;
        to_ubjson(j, result, use_size, use_type);
        return result;
    }