JSON DOM. More...

#include <assert.h>
#include <stddef.h>
#include <iterator>
#include <map>
#include <memory>
#include <new>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
#include "field_types.h"
#include "my_inttypes.h"
#include "my_time.h"
#include "mysql_time.h"
#include "prealloced_array.h"
#include "sql-common/json_binary.h"
#include "sql-common/json_error_handler.h"
#include "sql-common/my_decimal.h"
#include "sql/malloc_allocator.h"

Classes
class	Json_dom
	JSON DOM abstract base class. More...

class	Json_container
	Abstract base class of all JSON container types (Json_object and Json_array). More...

struct	Json_key_comparator
	A comparator that is used for ordering keys in a Json_object. More...

class	Json_object
	Represents a JSON container value of type "object" (ECMA), type J_OBJECT here. More...

class	Json_array
	Represents a JSON array container, i.e. More...

class	Json_scalar
	Abstract base class for all Json scalars. More...

class	Json_string
	Represents a JSON string value (ECMA), of type J_STRING here. More...

class	Json_number
	Abstract base class of all JSON number (ECMA) types (subclasses represent MySQL extensions). More...

class	Json_decimal
	Represents a MySQL decimal number, type J_DECIMAL. More...

class	Json_double
	Represents a MySQL double JSON scalar (an extension of the ECMA number value), type J_DOUBLE. More...

class	Json_int
	Represents a MySQL integer (64 bits signed) JSON scalar (an extension of the ECMA number value), type J_INT. More...

class	Json_uint
	Represents a MySQL integer (64 bits unsigned) JSON scalar (an extension of the ECMA number value), type J_UINT. More...

class	Json_null
	Represents a JSON null type (ECMA), type J_NULL here. More...

class	Json_datetime
	Represents a MySQL date/time value (DATE, TIME, DATETIME or TIMESTAMP) - an extension to the ECMA set of JSON scalar types, types J_DATE, J_TIME, J_DATETIME and J_TIMESTAMP respectively. More...

class	Json_opaque
	Represents a MySQL value opaquely, i.e. More...

class	Json_boolean
	Represents a JSON true or false value, type J_BOOLEAN here. More...

class	Json_wrapper
	Abstraction for accessing JSON values irrespective of whether they are (started out as) binary JSON values or JSON DOM values. More...

class	Json_wrapper_object_iterator
	Class that iterates over all members of a JSON object that is wrapped in a Json_wrapper instance. More...

class	Json_object_wrapper
	A wrapper over a JSON object which provides an interface that can be iterated over with a for-each loop. More...

class	Json_scalar_holder
	A class that is capable of holding objects of any sub-type of Json_scalar. More...

union	Json_scalar_holder::Any_json_scalar
	Union of all concrete subclasses of Json_scalar. More...

Typedefs
typedef Prealloced_array< Json_wrapper, 16 >	Json_wrapper_vector

typedef Prealloced_array< Json_dom *, 16 >	Json_dom_vector

using	Json_dom_ptr = std::unique_ptr< Json_dom >

using	Json_array_ptr = std::unique_ptr< Json_array >

using	Json_object_ptr = std::unique_ptr< Json_object >

using	Json_object_map = std::map< std::string, Json_dom_ptr, Json_key_comparator, Malloc_allocator< std::pair< const std::string, Json_dom_ptr > > >
	A type used to hold JSON object elements in a map, see the Json_object class. More...

Enumerations
enum class	enum_json_type { J_NULL , J_DECIMAL , J_INT , J_UINT , J_DOUBLE , J_STRING , J_OBJECT , J_ARRAY , J_BOOLEAN , J_DATE , J_TIME , J_DATETIME , J_TIMESTAMP , J_OPAQUE , J_ERROR }
	Json values in MySQL comprises the stand set of JSON values plus a MySQL specific set. More...

Functions
template<typename T , typename... Args>
std::unique_ptr< T >	create_dom_ptr (Args &&...args)
	Allocate a new Json_dom object and return a std::unique_ptr which points to it. More...

bool	double_quote (const char cptr, size_t length, String buf)
	Perform quoting on a JSON string to make an external representation of it. More...

Json_dom_ptr	merge_doms (Json_dom_ptr left, Json_dom_ptr right)
	Merge two doms. More...

bool	is_valid_json_syntax (const char *text, size_t length)
	Check if a string contains valid JSON text, without generating a Json_dom representation of the document. More...

bool	json_wrapper_contains (const Json_wrapper &doc_wrapper, const Json_wrapper &containee_wr, bool *result)
	Check if one Json_wrapper contains all the elements of another Json_wrapper. More...

std::string_view	json_type_name (const Json_wrapper &doc)
	Returns the name of the type of the JSON document contained in "doc". More...

Variables
const size_t	kMaxJsonTypeNameLength
	The maximum length of the type name returned from JSON_TYPE. More...

Detailed Description

JSON DOM.

When a JSON value is retrieved from a column, a prior it exists in a binary form, cf. Json_binary::Value class.

However, when we need to manipulate the JSON values we mostly convert them from binary form to a structured in-memory from called DOM (from domain object model) which uses a recursive tree representation of the JSON value corresponding closely to a parse tree. This form is more suitable for manipulation.

The JSON type is mostly represented internally as a Json_wrapper which hides if the representation is a binary or DOM one. This makes is possible to avoid building a DOM unless we really need one.

The file defines two sets of classes: a) The Json_dom hierarchy and b) Json_wrapper and its companion classes Json_wrapper_object_iterator and Json_object_wrapper. For both sets, arrays are traversed using an operator[].

Typedef Documentation

◆ Json_array_ptr

using Json_array_ptr = std::unique_ptr<Json_array>

◆ Json_dom_ptr

using Json_dom_ptr = std::unique_ptr<Json_dom>

◆ Json_dom_vector

typedef Prealloced_array<Json_dom *, 16> Json_dom_vector

◆ Json_object_map

using Json_object_map = std::map<std::string, Json_dom_ptr, Json_key_comparator, Malloc_allocator<std::pair<const std::string, Json_dom_ptr> >>

A type used to hold JSON object elements in a map, see the Json_object class.

◆ Json_object_ptr

using Json_object_ptr = std::unique_ptr<Json_object>

◆ Json_wrapper_vector

typedef Prealloced_array<Json_wrapper, 16> Json_wrapper_vector

Enumeration Type Documentation

◆ enum_json_type

enum class enum_json_type

strong

Json values in MySQL comprises the stand set of JSON values plus a MySQL specific set.

A Json number type is subdivided into int, uint, double and decimal.

MySQL also adds four built-in date/time values: date, time, datetime and timestamp. An additional opaque value can store any other MySQL type.

The enumeration is common to Json_dom and Json_wrapper.

The enumeration is also used by Json_wrapper::compare() to determine the ordering when comparing values of different types, so the order in which the values are defined in the enumeration, is significant. The expected order is null < number < string < object < array < boolean < date < time < datetime/timestamp < opaque.

Enumerator
J_NULL
J_DECIMAL
J_INT
J_UINT
J_DOUBLE
J_STRING
J_OBJECT
J_ARRAY
J_BOOLEAN
J_DATE
J_TIME
J_DATETIME
J_TIMESTAMP
J_OPAQUE
J_ERROR

Function Documentation

◆ create_dom_ptr()

template<typename T , typename... Args>

std::unique_ptr< T > create_dom_ptr ( Args &&... args )

inline

Allocate a new Json_dom object and return a std::unique_ptr which points to it.

Parameters

args	the arguments to pass to the constructor

Template Parameters

T	the type of Json_dom to create
Args	the type of the arguments to pass to the constructor

Returns: a pointer to the allocated object

◆ double_quote()

bool double_quote	(	const char *	cptr,
		size_t	length,
		String *	buf
	)

Perform quoting on a JSON string to make an external representation of it.

It wraps double quotes (text quotes) around the string (cptr) and also performs escaping according to the following table:

Common name     C-style  Original unescaped     Transformed to
                escape   UTF-8 bytes            escape sequence
                notation                        in UTF-8 bytes
---------------------------------------------------------------
quote           \"       %x22                    %x5C %x22
backslash       \\       %x5C                    %x5C %x5C
backspace       \b       %x08                    %x5C %x62
formfeed        \f       %x0C                    %x5C %x66
linefeed        \n       %x0A                    %x5C %x6E
carriage-return \r       %x0D                    %x5C %x72
tab             \t       %x09                    %x5C %x74
unicode         \uXXXX  A hex number in the      %x5C %x75
                        range of 00-1F,          followed by
                        except for the ones      4 hex digits
                        handled above (backspace,
                        formfeed, linefeed,
                        carriage-return,
                        and tab).
---------------------------------------------------------------

Parameters

[in]	cptr	pointer to string data
[in]	length	the length of the string
[in,out]	buf	the destination buffer

Return values

true on error

◆ is_valid_json_syntax()

bool is_valid_json_syntax	(	const char *	text,
		size_t	length
	)

Check if a string contains valid JSON text, without generating a Json_dom representation of the document.

Parameters

[in]	text	pointer to the beginning of the string
[in]	length	the length of the string

Returns: true if the string is valid JSON text, false otherwise

◆ json_type_name()

std::string_view json_type_name ( const Json_wrapper & doc )

Returns the name of the type of the JSON document contained in "doc".

◆ json_wrapper_contains()

bool json_wrapper_contains	(	const Json_wrapper &	doc_wrapper,
		const Json_wrapper &	containee_wr,
		bool *	result
	)

Check if one Json_wrapper contains all the elements of another Json_wrapper.

Parameters

[in]	doc_wrapper	the containing document
[in]	containee_wr	the possibly contained document
[out]	result	true if doc_wrapper contains containee_wr, false otherwise

Return values

false	on success
true	on failure

◆ merge_doms()

Json_dom_ptr merge_doms	(	Json_dom_ptr	left,
		Json_dom_ptr	right
	)

Merge two doms.

The right dom is either subsumed into the left dom or the contents of the right dom are transferred to the left dom and the right dom is deleted. After calling this function, the caller should not reference the right dom again. It has been deleted.

Returns NULL if there is a memory allocation failure. In this case both doms are deleted.

scalars - If any of the documents that are being merged is a scalar, each scalar document is autowrapped as a single value array before merging.

arrays - When merging a left array with a right array, then the result is the left array concatenated with the right array. For instance, [ 1, 2 ] merged with [ 3, 4 ] is [ 1, 2, 3, 4 ].

array and object - When merging an array with an object, the object is autowrapped as an array and then the rule above is applied. So [ 1, 2 ] merged with { "a" : true } is [ 1, 2, { "a": true } ].

objects - When merging two objects, the two objects are concatenated into a single, larger object. So { "a" : "foo" } merged with { "b" : 5 } is { "a" : "foo", "b" : 5 }.

duplicates - When two objects are merged and they share a key, the values associated with the shared key are merged.

Parameters

[in,out]	left	The recipient dom.
[in,out]	right	The dom to be consumed

Returns: A composite dom which subsumes the left and right doms, or NULL if a failure happened while merging

Variable Documentation

◆ kMaxJsonTypeNameLength

const size_t kMaxJsonTypeNameLength

extern

The maximum length of the type name returned from JSON_TYPE.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Json_array_ptr

◆ Json_dom_ptr

◆ Json_dom_vector

◆ Json_object_map

◆ Json_object_ptr

◆ Json_wrapper_vector

Enumeration Type Documentation

◆ enum_json_type

Function Documentation

◆ create_dom_ptr()

◆ double_quote()

◆ is_valid_json_syntax()

◆ json_type_name()

◆ json_wrapper_contains()

◆ merge_doms()

Variable Documentation

◆ kMaxJsonTypeNameLength