MySQL 8.4.3
Source Code Documentation
json_dom.h File Reference

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/mysql_lex_string.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"

Go to the source code of this file.

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

◆ 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

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
argsthe arguments to pass to the constructor
Template Parameters
Tthe type of Json_dom to create
Argsthe 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]cptrpointer to string data
[in]lengththe length of the string
[in,out]bufthe destination buffer
Return values
trueon 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]textpointer to the beginning of the string
[in]lengththe 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_wrapperthe containing document
[in]containee_wrthe possibly contained document
[out]resulttrue if doc_wrapper contains containee_wr, false otherwise
Return values
falseon success
trueon 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]leftThe recipient dom.
[in,out]rightThe 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.