MySQL  8.0.17
Source Code Documentation
json_binary Namespace Reference

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

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]objectthe JSON object
[out]destthe destination string
[in]offsetthe offset of the first key
[in]largeif 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
destthe destination String
offset_or_sizethe offset or size to append
largeif 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
destthe destination String
lengththe 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]valuethe JSON value
[out]destthe destination string
[in]posthe offset where the value should be inlined
[in]largetrue 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
sizethe 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
valuethe root of the JSON document
functhe function to apply
Return values
trueif the processing was stopped
falseif the processing was completed
Template Parameters
Funca 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
typethe type to check
largetrue 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
destthe destination String
posthe position in the String
offset_or_sizethe offset or size to append
largeif 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_sizethe offset or size to check
largeif 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
largetrue 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
largetrue 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
ttype (either ARRAY or OBJECT)
datapointer to the start of the array or object
lenthe maximum number of bytes to read from data
largeif 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()

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

Parse a JSON binary document.

Parameters
[in]dataa pointer to the binary data
[in]lenthe 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
typethe binary type of the scalar
datapointer to the start of the binary representation of the scalar
lenthe 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
typethe binary type of the value to parse
datapointer to the start of the binary representation of the value
lenthe 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
datathe buffer to read from
largetells 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]datathe buffer to read from
[in]data_lengththe maximum number of bytes to read from data
[out]lengththe length that was read
[out]numthe 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]thdTHD handle
[in]domthe input DOM tree
[in,out]destthe destination string
Return values
falseon success
trueif 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]jdtthe DATETIME value
[in]type_poswhere to write the type specifier
[out]destthe 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]jdthe DECIMAL value
[in]type_poswhere to write the type specifier
[out]destthe 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
thdTHD handle
arraythe JSON array to serialize
destthe destination string
largeif true, the large storage format will be used
depththe 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
thdTHD handle
objectthe JSON object to serialize
destthe destination string
largeif true, the large storage format will be used
depththe 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
thdTHD handle
domthe JSON value to serialize
type_posthe position of the type specifier to update
destthe destination string
depththe current nesting level
small_parenttells 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]opaquethe JSON opaque value
[in]type_poswhere to write the type specifier
[out]destthe 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]thdTHD handle
[in]valuethe JSON value to add to a document
[in]largetrue if the large storage format is used
[out]neededgets set to the amount of bytes needed to store the value
Return values
falseif successful
trueif 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
largetrue 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
destthe array to write to
offset_or_sizethe offset or size to write
largeif true, use the large storage format