Classes
class	Value
	Class used for reading JSON values that are stored in the binary format. More...

Enumerations
enum	enum_serialization_result { OK , VALUE_TOO_BIG , FAILURE }
	Status codes for JSON serialization. More...

Functions
static enum_serialization_result	serialize_json_value (const THD thd, const Json_dom dom, size_t type_pos, String *dest, size_t depth, bool small_parent)
	Serialize a JSON value at the end of the destination string. More...

static void	write_offset_or_size (char *dest, size_t offset_or_size, bool large)
	Write an offset or a size to a char array. More...

static uint8	offset_size (bool large)
	Get the size of an offset value. More...

bool	serialize (const THD thd, const Json_dom dom, String *dest)
	Serialize the JSON document represented by dom to binary format in the destination string, replacing any content already in the destination string. More...

static bool	reserve (String *buffer, size_t bytes_needed)
	Reserve space for the given amount of extra bytes at the end of a String buffer. More...

static bool	append_int16 (String *dest, int16 value)
	Encode a 16-bit int at the end of the destination string. More...

static bool	append_int32 (String *dest, int32 value)
	Encode a 32-bit int at the end of the destination string. More...

static bool	append_int64 (String *dest, int64 value)
	Encode a 64-bit int at the end of the destination string. More...

static bool	append_offset_or_size (String *dest, size_t offset_or_size, bool large)
	Append an offset or a size to a String. More...

static void	insert_offset_or_size (String *dest, size_t pos, size_t offset_or_size, bool large)
	Insert an offset or a size at the specified position in a String. More...

static bool	check_document_size (size_t size)
	Check if the size of a document exceeds the maximum JSON binary size (4 GB, aka UINT_MAX32). More...

static bool	append_variable_length (String *dest, size_t length)
	Append a length to a String. More...

static bool	read_variable_length (const char data, size_t data_length, uint32 length, uint8 *num)
	Read a variable length written by append_variable_length(). More...

static bool	is_too_big_for_json (size_t offset_or_size, bool large)
	Check if the specified offset or size is too big to store in the binary JSON format. More...

static enum_serialization_result	append_key_entries (const Json_object object, String dest, size_t offset, bool large)
	Append all the key entries of a JSON object to a destination string. More...

static bool	inlined_type (uint8 type, bool large)
	Will a value of the specified type be inlined? More...

static uint8	key_entry_size (bool large)
	Get the size of a key entry. More...

static uint8	value_entry_size (bool large)
	Get the size of a value entry. More...

static bool	attempt_inline_value (const Json_dom value, String dest, size_t pos, bool large)
	Attempt to inline a value in its value entry at the beginning of an object or an array. More...

static enum_serialization_result	serialize_json_array (const THD thd, const Json_array array, String *dest, bool large, size_t depth)
	Serialize a JSON array at the end of the destination string. More...

static enum_serialization_result	serialize_json_object (const THD thd, const Json_object object, String *dest, bool large, size_t depth)
	Serialize a JSON object at the end of the destination string. More...

static enum_serialization_result	serialize_opaque (const Json_opaque opaque, size_t type_pos, String dest)
	Serialize a JSON opaque value at the end of the destination string. More...

static enum_serialization_result	serialize_decimal (const Json_decimal jd, size_t type_pos, String dest)
	Serialize a DECIMAL value at the end of the destination string. More...

static enum_serialization_result	serialize_datetime (const Json_datetime jdt, size_t type_pos, String dest)
	Serialize a DATETIME value at the end of the destination string. More...

static Value	err ()
	Create a Value object that represents an error condition. More...

static Value	parse_scalar (uint8 type, const char *data, size_t len)
	Parse a JSON scalar value. More...

static uint32	read_offset_or_size (const char *data, bool large)
	Read an offset or size field from a buffer. More...

static Value	parse_array_or_object (Value::enum_type t, const char *data, size_t len, bool large)
	Parse a JSON array or object. More...

static Value	parse_value (uint8 type, const char *data, size_t len)
	Parse a JSON value within a larger JSON document. More...

Value	parse_binary (const char *data, size_t len)
	Parse a JSON binary document. More...

bool	space_needed (const THD thd, const Json_wrapper value, bool large, size_t *needed)
	How much space is needed for a JSON value when it is stored in the binary format. More...

template<typename Func >
bool	for_each_node (const Value &value, const Func &func)
	Apply a function to every value in a JSON document. More...

Enumeration Type Documentation

◆ enum_serialization_result

enum json_binary::enum_serialization_result

Status codes for JSON serialization.

Enumerator

OK

Success.

The JSON value was successfully serialized.

VALUE_TOO_BIG

The JSON value was too big to be serialized.

If this status code is returned, and the small storage format is in use, the caller should retry the serialization with the large storage format. If this status code is returned, and the large format is in use, my_error() will already have been called.

FAILURE

Some other error occurred.

my_error() will have been called with more specific information about the failure.

Function Documentation

◆ append_int16()

static bool json_binary::append_int16	(	String *	dest,
		int16	value
	)

static

Encode a 16-bit int at the end of the destination string.

◆ append_int32()

static bool json_binary::append_int32	(	String *	dest,
		int32	value
	)

static

Encode a 32-bit int at the end of the destination string.

◆ append_int64()

static bool json_binary::append_int64	(	String *	dest,
		int64	value
	)

static

Encode a 64-bit int at the end of the destination string.

◆ append_key_entries()

static enum_serialization_result json_binary::append_key_entries	(	const Json_object *	object,
		String *	dest,
		size_t	offset,
		bool	large
	)

static

Append all the key entries of a JSON object to a destination string.

The key entries are just a series of offset/length pairs that point to where the actual key names are stored.

Parameters

[in]	object	the JSON object
[out]	dest	the destination string
[in]	offset	the offset of the first key
[in]	large	if true, the large storage format will be used

Returns: serialization status

◆ append_offset_or_size()

static bool json_binary::append_offset_or_size	(	String *	dest,
		size_t	offset_or_size,
		bool	large
	)

static

Append an offset or a size to a String.

Parameters

dest	the destination String
offset_or_size	the offset or size to append
large	if true, use the large storage format (4 bytes); otherwise, use the small storage format (2 bytes)

Returns: false if successfully appended, true otherwise

◆ append_variable_length()

static bool json_binary::append_variable_length	(	String *	dest,
		size_t	length
	)

static

Append a length to a String.

The number of bytes used to store the length uses a variable number of bytes depending on how large the length is. If the highest bit in a byte is 1, then the length is continued on the next byte. The least significant bits are stored in the first byte.

Parameters

dest	the destination String
length	the length to write

Returns: false on success, true on error

◆ attempt_inline_value()

static bool json_binary::attempt_inline_value	(	const Json_dom *	value,
		String *	dest,
		size_t	pos,
		bool	large
	)

static

Attempt to inline a value in its value entry at the beginning of an object or an array.

This function assumes that the destination string has already allocated enough space to hold the inlined value.

Parameters

[in]	value	the JSON value
[out]	dest	the destination string
[in]	pos	the offset where the value should be inlined
[in]	large	true if the large storage format is used

Returns: true if the value was inlined, false if it was not

◆ check_document_size()

static bool json_binary::check_document_size ( size_t size )

static

Check if the size of a document exceeds the maximum JSON binary size (4 GB, aka UINT_MAX32).

Raise an error if it is too big.

Parameters

size	the size of the document

Returns: true if the document is too big, false otherwise

◆ err()

static Value json_binary::err ( )

static

Create a Value object that represents an error condition.

◆ for_each_node()

template<typename Func >

bool json_binary::for_each_node	(	const Value &	value,
		const Func &	func
	)

Apply a function to every value in a JSON document.

That is, apply the function to the root node of the JSON document, to all its children, grandchildren and so on.

Parameters

value	the root of the JSON document
func	the function to apply

Return values

true	if the processing was stopped
false	if the processing was completed

Template Parameters

Func	a functor type that takes a json_binary::Value parameter and returns a `bool` which is `true` if the processing should stop or `false` if the processing should continue with the next node

◆ inlined_type()

static bool json_binary::inlined_type	(	uint8	type,
		bool	large
	)

static

Will a value of the specified type be inlined?

Parameters

type	the type to check
large	true if the large storage format is used

Returns: true if the value will be inlined

◆ insert_offset_or_size()

static void json_binary::insert_offset_or_size	(	String *	dest,
		size_t	pos,
		size_t	offset_or_size,
		bool	large
	)

static

Insert an offset or a size at the specified position in a String.

It is assumed that the String has already allocated enough space to hold the value.

Parameters

dest	the destination String
pos	the position in the String
offset_or_size	the offset or size to append
large	if true, use the large storage format (4 bytes); otherwise, use the small storage format (2 bytes)

◆ is_too_big_for_json()

static bool json_binary::is_too_big_for_json	(	size_t	offset_or_size,
		bool	large
	)

static

Check if the specified offset or size is too big to store in the binary JSON format.

If the small storage format is used, the caller is expected to retry serialization in the large storage format, so no error is generated if the offset or size is too big. If the large storage format is used, an error will be generated if the offset or size is too big.

Parameters

offset_or_size	the offset or size to check
large	if true, we are using the large storage format for JSON arrays and objects, which allows offsets and sizes that fit in a uint32; otherwise, we are using the small storage format, which allow offsets and sizes that fit in a uint16.

Returns: true if offset_or_size is too big for the format, false otherwise

◆ key_entry_size()

static uint8 json_binary::key_entry_size ( bool large )

static

Get the size of a key entry.

Parameters

large true if the large storage format is used

Returns: the size of a key entry

◆ offset_size()

static uint8 json_binary::offset_size ( bool large )

static

Get the size of an offset value.

Parameters

large true if the large storage format is used

Returns: the size of an offset

◆ parse_array_or_object()

static Value json_binary::parse_array_or_object	(	Value::enum_type	t,
		const char *	data,
		size_t	len,
		bool	large
	)

static

Parse a JSON array or object.

Parameters

t	type (either ARRAY or OBJECT)
data	pointer to the start of the array or object
len	the maximum number of bytes to read from data
large	if true, the array or object is stored using the large storage format; otherwise, it is stored using the small storage format

Returns: an object that allows access to the array or object

◆ parse_binary()

EXPORT_JSON_FUNCTION Value json_binary::parse_binary	(	const char *	data,
		size_t	len
	)

Parse a JSON binary document.

Parameters

[in]	data	a pointer to the binary data
[in]	len	the size of the binary document in bytes

Returns: an object that allows access to the contents of the document

◆ parse_scalar()

static Value json_binary::parse_scalar	(	uint8	type,
		const char *	data,
		size_t	len
	)

static

Parse a JSON scalar value.

Parameters

type	the binary type of the scalar
data	pointer to the start of the binary representation of the scalar
len	the maximum number of bytes to read from data

Returns: an object that represents the scalar value

◆ parse_value()

static Value json_binary::parse_value	(	uint8	type,
		const char *	data,
		size_t	len
	)

static

Parse a JSON value within a larger JSON document.

Parameters

type	the binary type of the value to parse
data	pointer to the start of the binary representation of the value
len	the maximum number of bytes to read from data

Returns: an object that allows access to the value

◆ read_offset_or_size()

static uint32 json_binary::read_offset_or_size	(	const char *	data,
		bool	large
	)

static

Read an offset or size field from a buffer.

The offset could be either a two byte unsigned integer or a four byte unsigned integer.

Parameters

data	the buffer to read from
large	tells if the large or small storage format is used; true means read four bytes, false means read two bytes

◆ read_variable_length()

static bool json_binary::read_variable_length	(	const char *	data,
		size_t	data_length,
		uint32 *	length,
		uint8 *	num
	)

static

Read a variable length written by append_variable_length().

Parameters

[in]	data	the buffer to read from
[in]	data_length	the maximum number of bytes to read from data
[out]	length	the length that was read
[out]	num	the number of bytes needed to represent the length

Returns: false on success, true if the variable length field is ill-formed

◆ reserve()

static bool json_binary::reserve	(	String *	buffer,
		size_t	bytes_needed
	)

static

Reserve space for the given amount of extra bytes at the end of a String buffer.

If the String needs to allocate more memory, it will grow by at least 50%, to avoid frequent reallocations.

◆ serialize()

bool json_binary::serialize	(	const THD *	thd,
		const Json_dom *	dom,
		String *	dest
	)

Serialize the JSON document represented by dom to binary format in the destination string, replacing any content already in the destination string.

Parameters

[in]	thd	THD handle
[in]	dom	the input DOM tree
[in,out]	dest	the destination string

Return values

false	on success
true	if an error occurred

◆ serialize_datetime()

static enum_serialization_result json_binary::serialize_datetime	(	const Json_datetime *	jdt,
		size_t	type_pos,
		String *	dest
	)

static

Serialize a DATETIME value at the end of the destination string.

Parameters

[in]	jdt	the DATETIME value
[in]	type_pos	where to write the type specifier
[out]	dest	the destination string

Returns: serialization status

◆ serialize_decimal()

static enum_serialization_result json_binary::serialize_decimal	(	const Json_decimal *	jd,
		size_t	type_pos,
		String *	dest
	)

static

Serialize a DECIMAL value at the end of the destination string.

Parameters

[in]	jd	the DECIMAL value
[in]	type_pos	where to write the type specifier
[out]	dest	the destination string

Returns: serialization status

◆ serialize_json_array()

static enum_serialization_result json_binary::serialize_json_array	(	const THD *	thd,
		const Json_array *	array,
		String *	dest,
		bool	large,
		size_t	depth
	)

static

Serialize a JSON array at the end of the destination string.

Parameters

thd	THD handle
array	the JSON array to serialize
dest	the destination string
large	if true, the large storage format will be used
depth	the current nesting level

Returns: serialization status

◆ serialize_json_object()

static enum_serialization_result json_binary::serialize_json_object	(	const THD *	thd,
		const Json_object *	object,
		String *	dest,
		bool	large,
		size_t	depth
	)

static

Serialize a JSON object at the end of the destination string.

Parameters

thd	THD handle
object	the JSON object to serialize
dest	the destination string
large	if true, the large storage format will be used
depth	the current nesting level

Returns: serialization status

◆ serialize_json_value()

static enum_serialization_result json_binary::serialize_json_value	(	const THD *	thd,
		const Json_dom *	dom,
		size_t	type_pos,
		String *	dest,
		size_t	depth,
		bool	small_parent
	)

static

Serialize a JSON value at the end of the destination string.

Also go back and update the type specifier for the value to specify the correct type. For top-level documents, the type specifier is located in the byte right in front of the value. For documents that are nested within other documents, the type specifier is located in the value entry portion at the beginning of the parent document.

Parameters

thd	THD handle
dom	the JSON value to serialize
type_pos	the position of the type specifier to update
dest	the destination string
depth	the current nesting level
small_parent	tells if dom is contained in an array or object which is stored in the small storage format

Returns: serialization status

◆ serialize_opaque()

static enum_serialization_result json_binary::serialize_opaque	(	const Json_opaque *	opaque,
		size_t	type_pos,
		String *	dest
	)

static

Serialize a JSON opaque value at the end of the destination string.

Parameters

[in]	opaque	the JSON opaque value
[in]	type_pos	where to write the type specifier
[out]	dest	the destination string

Returns: serialization status

◆ space_needed()

bool json_binary::space_needed	(	const THD *	thd,
		const Json_wrapper *	value,
		bool	large,
		size_t *	needed
	)

How much space is needed for a JSON value when it is stored in the binary format.

Parameters

[in]	thd	THD handle
[in]	value	the JSON value to add to a document
[in]	large	true if the large storage format is used
[out]	needed	gets set to the amount of bytes needed to store the value

Return values

false	if successful
true	if an error occurred while calculating the needed space

◆ value_entry_size()

static uint8 json_binary::value_entry_size ( bool large )

static

Get the size of a value entry.

Parameters

large true if the large storage format is used

Returns: the size of a value entry

◆ write_offset_or_size()

static void json_binary::write_offset_or_size	(	char *	dest,
		size_t	offset_or_size,
		bool	large
	)

static

Write an offset or a size to a char array.

The char array is assumed to be large enough to hold an offset or size value.

Parameters

dest	the array to write to
offset_or_size	the offset or size to write
large	if true, use the large storage format

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ enum_serialization_result

Function Documentation

◆ append_int16()

◆ append_int32()

◆ append_int64()

◆ append_key_entries()

◆ append_offset_or_size()

◆ append_variable_length()

◆ attempt_inline_value()

◆ check_document_size()

◆ err()

◆ for_each_node()

◆ inlined_type()

◆ insert_offset_or_size()

◆ is_too_big_for_json()

◆ key_entry_size()

◆ offset_size()

◆ parse_array_or_object()

◆ parse_binary()

◆ parse_scalar()

◆ parse_value()

◆ read_offset_or_size()

◆ read_variable_length()

◆ reserve()

◆ serialize()

◆ serialize_datetime()

◆ serialize_decimal()

◆ serialize_json_array()

◆ serialize_json_object()

◆ serialize_json_value()

◆ serialize_opaque()

◆ space_needed()

◆ value_entry_size()

◆ write_offset_or_size()