Json and XML
hJson unitThJsonNode_Type
Defines the possible data types for a JSON node. The table below lists each possible value and its meaning:This enumeration defines the different possible types for a JSON node in the hJson unit.
Each value represents a specific kind of JSON data structure or special node.
| Value | Description |
|---|---|
| JObject | Represents a JSON object, which is a collection of name-value pairs. |
| JValue | Represents a single value, such as a string, number, boolean, or null, following standard JSON rules. |
| JValueBare | Represents a bare value in JSON, possibly without quotes or type annotation, used for simplified or optimized output. |
| JArray | Represents a JSON array, which is an ordered list of items. |
| Jstream |
Represents a node that contains a RAM buffer (of a big json object).
This content is inserted directly into the final JSON file or memory stream, AS-IS. |
| Jsye_Stream | This is an illegal or special node format. It stores a binary stream, noted as "SyeStream":SizeInBytes (integer), followed by a binary stream of that size. Not valid for standard JSON data. |
ThJsonNode Class
Clear
Removes all child nodes, and resets the value and name fields of the node.After calling this procedure, the node becomes empty and ready for reuse.
procedure Clear;ChildCount
Returns the number of direct child nodes contained within the node.This function is mainly relevant for nodes of type JObject or JArray.
function ChildCount: Cardinal;Return Value
Returns the count of child nodes as a Cardinal value.Child
Returns the child node at the specified zero-based index.Allows access to a specific child node within the current node.
function Child(const Index: Integer): ThJsonNode;Parameters
- Index: Integer; The index of the child node to retrieve.
Return Value
Returns the child node at the specified index as a ThJsonNode object.LastChild
Returns the last child node of the current node.If there are no children, the result is undefined.
function LastChild: ThJsonNode;Return Value
Returns the last child node as a ThJsonNode object.Empty
Checks if the node is considered empty, depending on its type and content.An optional parameter allows checking value emptiness as a numeric type.
function Empty(Value_As_Numeric_Type: Boolean = False): Boolean;Parameters
- Value_As_Numeric_Type: Boolean; If True, the value is checked for numeric emptiness (zero or invalid number). If False, the standard empty check applies.
Return Value
Returns True if the node is empty according to the selected criteria.Returns False otherwise.
Exist
Checks if a sub node matching the provided name path exists and has a value or stream.Returns True only if the specified sub node is found and contains data.
function Exist(const Find_Names: ThFlds_Name_Array): Boolean;Parameters
- Find_Names: ThFlds_Name_Array; An array representing the sequence of field names to match in the node hierarchy.
Return Value
Returns True if a matching sub node exists and has a value or stream.Returns False otherwise.
Find_Node_By_Name
Searches for a child node with the specified name. Can search recursively and with case sensitivity options.Returns the first matching node, or nil if not found.
function Find_Node_By_Name(const FldName: String; const Recurse: Boolean = False; const CaseSens: Boolean = False): ThJsonNode;Parameters
- FldName: String; The field name to search for.
- Recurse: Boolean; If True, the search includes all descendant nodes. If False, only direct children are checked.
- CaseSens: Boolean; If True, the search is case sensitive. If False, the search is case insensitive.
Return Value
Returns the first matching node as a ThJsonNode object.Returns nil if no match is found.
Find_Node_ML
Finds a sub node by following a sequence of names in the hierarchy.Returns the node matching the full path, or nil if not found.
function Find_Node_ML(const Find_Names: ThFlds_Name_Array): ThJsonNode;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
Return Value
Returns the node matching the name path as a ThJsonNode object.Returns nil if no such node exists.
Value_String
Retrieves the string value from a sub node specified by a path of field names.Returns an empty string if the node or value is not found.
function Value_String(const Find_Names: ThFlds_Name_Array): String;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
Return Value
Returns the value as a String.Returns an empty string if not found.
Value_Integer
Retrieves the integer value from a sub node specified by a path of field names.Returns 0 if the node or value is not found or is not an integer.
function Value_Integer(const Find_Names: ThFlds_Name_Array): Int64;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
Return Value
Returns the value as an Int64 integer.Returns 0 if not found or not an integer.
Value_Real
Retrieves the numeric (real) value from a sub node specified by a path of field names.Optionally filters out all non-digit characters before conversion.
Returns 0 if the node or value is not found or cannot be converted.
function Value_Real(const Find_Names: ThFlds_Name_Array; Filter_All_But_Digits: Boolean = False): ThNumeric;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
- Filter_All_But_Digits: Boolean; If True, all non-digit characters are removed before converting to a number. If False, the value is converted as is.
Return Value
Returns the value as a ThNumeric type.Returns 0 if not found or cannot be converted.
Value_DateTime
Retrieves the date and time value from a sub node specified by a path of field names.An optional date mask determines the date parsing format.
Returns 0 if the node or value is not found or cannot be converted.
function Value_DateTime(const Find_Names: ThFlds_Name_Array; DateMask: ThDateMask = he_YYYY_MM_DD): TDateTime;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
- DateMask: ThDateMask; Specifies the date format to use for conversion (default is he_YYYY_MM_DD).
Return Value
Returns the value as a TDateTime.Returns 0 if not found or cannot be converted.
Value_Byte
Retrieves the byte value from a sub node specified by a path of field names.Returns 0 if the node or value is not found or cannot be converted.
function Value_Byte(const Find_Names: ThFlds_Name_Array): Byte;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
Return Value
Returns the value as a Byte.Returns 0 if not found or cannot be converted.
Value_Boolean
Retrieves the boolean value from a sub node specified by a path of field names.Returns False if the node or value is not found or cannot be converted.
function Value_Boolean(const Find_Names: ThFlds_Name_Array): Boolean;Parameters
- Find_Names: ThFlds_Name_Array; An array of field names specifying the path to the target node.
Return Value
Returns the value as a Boolean.Returns False if not found or cannot be converted.
Add_Object
Adds a new child object node to the current node. Optionally assigns a name to the new object.Returns the newly created object node.
function Add_Object(const Name: String = ''): ThJsonNode;Parameters
- Name: String; The optional name to assign to the new object node. If empty, the object is unnamed.
Return Value
Returns the new object node as a ThJsonNode.Add_Value
Adds a new value node as a child of the current node. Sets the specified name and value, and allows setting the value as bare (unquoted).Returns the created value node.
function Add_Value(const Name, Value: String; const Bare: Boolean = False): ThJsonNode;Parameters
- Name: String; The name to assign to the value node.
- Value: String; The value to store in the node.
- Bare: Boolean; If True, the value is added as a bare value (without quotes). If False, the value is quoted.
Return Value
Returns the new value node as a ThJsonNode.Add_String
Adds a new string value node as a child of the current node. Assigns the specified name and value, and can limit the maximum text length.Returns the created string node.
function Add_String(const Name, Value: String; const LimitTextLength: Word): ThJsonNode;Parameters
- Name: String; The name to assign to the string node.
- Value: String; The string value to store in the node.
- LimitTextLength: Word; Limits the maximum length of the value. If exceeded, the text may be truncated.
Return Value
Returns the new string node as a ThJsonNode.Add_Integer
Adds a new integer value node as a child of the current node. Sets the specified name and integer value.Returns the created node.
function Add_Integer(const Name: String; const Value: Integer): ThJsonNode;Parameters
- Name: String; The name to assign to the integer node.
- Value: Integer; The integer value to store in the node.
Return Value
Returns the new integer node as a ThJsonNode.Add_Money
Adds a new value node representing a monetary amount as a child of the current node. Sets the specified name and double value.Returns the created node.
function Add_Money(const Name: String; const Amount: Double): ThJsonNode;Parameters
- Name: String; The name to assign to the money node.
- Amount: Double; The monetary value to store in the node.
Return Value
Returns the new money node as a ThJsonNode.Add_Real
Adds a new real (floating-point) value node as a child of the current node. Sets the specified name and double value.Returns the created node.
function Add_Real(const Name: String; const Amount: Double): ThJsonNode;Parameters
- Name: String; The name to assign to the real node.
- Amount: Double; The real value to store in the node.
Return Value
Returns the new real node as a ThJsonNode.Add_Date
Adds a new date value node as a child of the current node. Sets the specified name and date value.Returns the created node.
function Add_Date(const Name: String; const Value: TDateTime): ThJsonNode;Parameters
- Name: String; The name to assign to the date node.
- Value: TDateTime; The date value to store in the node.
Return Value
Returns the new date node as a ThJsonNode.Add_DateTime
Adds a new date and time value node as a child of the current node. Sets the specified name and TDateTime value, with an option to store it in ISO format.Returns the created node.
function Add_DateTime(const Name: String; const Value: TDateTime; const ISO: Boolean = False): ThJsonNode;Parameters
- Name: String; The name to assign to the date-time node.
- Value: TDateTime; The date and time value to store in the node.
- ISO: Boolean; If True, the value is stored in ISO format. If False, the default format is used.
Return Value
Returns the new date-time node as a ThJsonNode.Add_Bool
Adds a new boolean value node as a child of the current node. Sets the specified name and boolean value.Returns the created node.
function Add_Bool(const Name: String; const Value: Boolean): ThJsonNode;Parameters
- Name: String; The name to assign to the boolean node.
- Value: Boolean; The boolean value to store in the node.
Return Value
Returns the new boolean node as a ThJsonNode.Add_Array
Adds a new array node as a child of the current node. Optionally assigns a name to the new array node.Returns the created array node.
function Add_Array(const Name: String = ''): ThJsonNode;Parameters
- Name: String; The optional name to assign to the array node. If empty, the array is unnamed.
Return Value
Returns the new array node as a ThJsonNode.Add_Array_Value
Adds a new value node as an item in the current array node. Sets the value and allows adding it as bare (unquoted).Returns the created value node.
function Add_Array_Value(const Value: String; const Bare: Boolean = False): ThJsonNode;Parameters
- Value: String; The value to add as an item in the array.
- Bare: Boolean; If True, adds the value as bare (without quotes). If False, the value is quoted.
Return Value
Returns the new array item as a ThJsonNode.Add_SYE_Stream_Node
Adds a special node to represent a binary stream according to the "SYE_Stream" format.Returns the created stream node.
function Add_SYE_Stream_Node: ThJsonNode;Return Value
Returns the new SYE_Stream node as a ThJsonNode.Add_Field_Value
Adds a new value node by reading a field value from a table at a specific row. Sets the node name to the field name and the node value to the field value.Returns the created node.
function Add_Field_Value(SourceTb: ThTable; FldName: String; Row: Integer): ThJsonNode;Parameters
- SourceTb: ThTable; The table object from which to read the value.
- FldName: String; The name of the field to read.
- Row: Integer; The row index to read from.
Return Value
Returns the new field value node as a ThJsonNode.Remove_Child
Removes a child node from the current node, either by its index or by its name.Returns True if a child was removed, False if not found.
function Remove_Child(const Index: Integer): Boolean; overload;
function Remove_Child(const Name: String): Boolean; overload;Parameters
- Index: Integer; The zero-based index of the child node to remove.
- Name: String; The name of the child node to remove.
Return Value
Returns True if the child was found and removed.Returns False if the specified child was not found.
Add_Dev_Help_Table_Structure
Adds a development helper structure to the node that describes the fields and structure of a given table.The structure can include hidden fields if requested.
procedure Add_Dev_Help_Table_Structure(SourceTb: ThTable; ObjectName: String; Expose_Hidden_Fields: Boolean = False);Parameters
- SourceTb: ThTable; The table object whose structure will be described.
- ObjectName: String; The name to assign to the helper structure node.
- Expose_Hidden_Fields: Boolean; If True, hidden fields in the table are included. If False, only visible fields are described.
Add_Table_Stream
Adds records from a table as nodes under the current node.Supports exporting as a single record or array, can process multiple rows, and allows including/excluding hidden fields.
procedure Add_Table_Stream(SourceTb: ThTable; ObjectName: String;
SingleRecord, Multiline_As_Array: Boolean;
FromRow: Integer = 0; UntilRow: Integer = -1; Check_If_Empty: Boolean = True;
Expose_Hidden_Fields: Boolean = False);Parameters
- SourceTb: ThTable; The source table from which records will be exported.
- ObjectName: String; The name for the output node containing the records.
- SingleRecord: Boolean; If True, exports as a single record. If False, exports as an array.
- Multiline_As_Array: Boolean; If True, each multiline field is split and stored as an array.
- FromRow: Integer; The starting row index to include.
- UntilRow: Integer; The last row index to include (-1 means all remaining rows).
- Check_If_Empty: Boolean; If True, empty records are skipped.
- Expose_Hidden_Fields: Boolean; If True, hidden fields in the table are included. If False, only visible fields are exported.
OUT_Update_Table
Updates the content of a table using the current JSON node data. Supports updating a single record, skipping empty values, and enforcing language constraints.Outputs a list of fields that failed a language check.
Returns True if the update succeeded, or False otherwise.
function OUT_Update_Table(TargetTb: ThTable; SingleRecord, SkipEmptyValues, Enforce_Lang_Input: Boolean;
var Wrong_Lang_Fields_List: String): Boolean;Parameters
- TargetTb: ThTable; The table object to be updated.
- SingleRecord: Boolean; If True, updates only a single record. If False, updates multiple records.
- SkipEmptyValues: Boolean; If True, skips updating fields with empty values.
- Enforce_Lang_Input: Boolean; If True, enforces language constraints on the input data.
- Wrong_Lang_Fields_List: String; Outputs the list of fields that failed the language check.
Return Value
Returns True if the table was updated successfully.Returns False if the update failed or validation errors occurred.
Write_To_MS
Appends the current node and all its subnodes to the specified memory stream in JSON format.Optionally limits the size of data written to the stream.
procedure Write_To_MS(const MS: ThMemoryStream; Limit_MS_Size: Integer = 0);Parameters
- MS: ThMemoryStream; The memory stream to which the JSON data is appended.
- Limit_MS_Size: Integer; Optional limit for the maximum size in bytes to write. If zero, no limit is applied.
Debug_Write_To_Log
Writes a debug representation of the current node and its structure to the application log.Useful for inspecting the internal state and data for troubleshooting.
procedure Debug_Write_To_Log;Write_Pretty_Html_To_MS
Writes a human-readable HTML representation of the current node and all its subnodes to the specified memory stream.Optionally limits the size of data written to the stream.
procedure Write_Pretty_Html_To_MS(const MS: ThMemoryStream; Limit_MS_Size: Integer = 0);Parameters
- MS: ThMemoryStream; The memory stream to which the HTML data is appended.
- Limit_MS_Size: Integer; Optional limit for the maximum size in bytes to write. If zero, no limit is applied.
Parent
Provides access to the parent node of the current node. This property is read-only.property Parent: ThJsonNode read _Parent_Node;Stream
Provides access to the memory buffer associated with the current node. This property is read-only and returns the internal memory stream.property Stream: ThMemoryStream read Buffer;Flat Functions (hJson unit)
Filter_Json_Object_Name
Filters a string to be used as a JSON object name, leaving only valid characters.Keeps uppercase and lowercase letters, digits, dash, and underscore.
function Filter_Json_Object_Name(const Name: String): RawByteString;Parameters
- Name: String; The input string to be filtered for use as a JSON object name.
Return Value
Returns a RawByteString containing only valid JSON name characters.Convert_Wide_To_Json
Converts a Unicode string to a JSON-encoded byte string. Ensures that wide characters are encoded in a JSON-safe way.function Convert_Wide_To_Json(Value: String): RawByteString;Parameters
- Value: String; The Unicode string to convert for JSON output.
Return Value
Returns the converted RawByteString suitable for JSON encoding.Calc_Json_Field_Name
Calculates a field name for JSON output, using the provided name.This function is published mainly for documentation and knowledge base purposes.
function Calc_Json_Field_Name(const Name: String): RawByteString;Parameters
- Name: String; The source name to process as a JSON field name.
Return Value
Returns a RawByteString representing the processed JSON field name.Clean_JSON_Stream_From_Inverted_Commas
Removes or corrects inverted commas in the given JSON memory stream. Helps to clean and fix common quotation mark issues in a JSON data stream.Returns True if any changes were made.
function Clean_JSON_Stream_From_Inverted_Commas(MS: ThMemoryStream): Boolean;Parameters
- MS: ThMemoryStream; The memory stream containing the JSON data to be cleaned.
Return Value
Returns True if the memory stream was modified.Returns False if no changes were needed.
Load_JSON_From_Stream
Loads a JSON structure from the specified memory stream, starting from the current position.Optionally limits the number of bytes to read from the stream.
Returns the root node of the loaded JSON data.
function Load_JSON_From_Stream(MS: ThMemoryStream; ReadSize: Int64 = -1): ThJsonNode;Parameters
- MS: ThMemoryStream; The memory stream containing the JSON data to be loaded.
- ReadSize: Int64; Optional parameter to limit the number of bytes read. If -1, reads to the end of the stream.
Return Value
Returns the root node of the loaded JSON as a ThJsonNode object.Load_JSON_From_File
Loads a JSON structure from the specified file.Returns the root node of the loaded JSON data.
function Load_JSON_From_File(const Filename: String): ThJsonNode;Parameters
- Filename: String; The file name of the JSON file to load.
Return Value
Returns the root node of the loaded JSON as a ThJsonNode object.Save_JSON_To_File
Saves the provided root JSON node to a file. Supports writing the JSON in a pretty-printed format if requested.Returns True if the save operation succeeded.
function Save_JSON_To_File(Root_Node: ThJsonNode; const Filename: String; Pretty: Boolean): Boolean;Parameters
- Root_Node: ThJsonNode; The root node of the JSON data to save.
- Filename: String; The file name to save the JSON data to.
- Pretty: Boolean; If True, the JSON is written in a pretty (indented) format.
Return Value
Returns True if the JSON was saved successfully.Returns False on failure.
Load_JSON_From_WideString
Loads a JSON structure from a wide (Unicode) string.Returns the root node of the loaded JSON data.
function Load_JSON_From_WideString(const Source: String): ThJsonNode;Parameters
- Source: String; The wide string containing the JSON data to load.
Return Value
Returns the root node of the loaded JSON as a ThJsonNode object.Save_JSON_To_UTF8_RawString
Serializes the provided root JSON node into a UTF-8 encoded RawByteString.Returns the result as a RawByteString for further use or saving.
function Save_JSON_To_UTF8_RawString(Root_Node: ThJsonNode): RawByteString;Parameters
- Root_Node: ThJsonNode; The root node of the JSON data to serialize.
Return Value
Returns the serialized JSON as a UTF-8 RawByteString.Load_XML_From_Stream
Loads an XML structure from the specified memory stream, starting from the current position. Converts the XML data to a ThJsonNode tree.Supports specifying the code page for decoding the stream.
function Load_XML_From_Stream(MS: ThMemoryStream; CodePage: Cardinal = CP_UTF8): ThJsonNode;Parameters
- MS: ThMemoryStream; The memory stream containing the XML data to be loaded.
- CodePage: Cardinal; The code page used for decoding the XML stream. Default is CP_UTF8.
Return Value
Returns the root node of the converted XML as a ThJsonNode object.Load_XML_From_File
Loads an XML structure from the specified file. Converts the XML data to a ThJsonNode tree.Returns the root node of the loaded XML.
function Load_XML_From_File(const Filename: String): ThJsonNode;Parameters
- Filename: String; The file name of the XML file to load.