@JsonAdd

This @Function adds a new value to an existing JSON object or JSON array.

The behavior and meaning of the optional parameters depend on whether HJSON references a JSON object or a JSON array.

For a JSON object, VALUE is stored under the key specified by TEXT KEY. If an entry with the same key already exists, its current value is replaced.

For a JSON array, VALUE is appended as a new element at the end of the array. Since elements of a JSON array do not have keys, the KEY parameter is omitted.
Therefore, an optional third parameter is already interpreted as TEXT TYPE for arrays.

The following data types are supported for VALUE: TEXT, FN, TEXTLIST, FNLIST and VSPECBINBUFFER, as well as existing VSPECHJSON (HJS) handles.
Engine lists are inserted as complete JSON arrays and are not expanded into the target structure.

Numeric values are created as JSON Real values by default. Using the optional TYPE parameter, numeric values can alternatively be stored as JSON Integer or JSON Boolean values.

JSON strings must contain valid UTF-8. Using the "S" option, invalid UTF-8 sequences in text values can automatically be sanitized.

As return value, the @Function returns @ERROR on failure; otherwise, it returns TRUE.

VSPECHJSON HJSON:
Handle of the JSON object or JSON array to which a value is to be added.
HJSON must contain a valid VSPECHJSON (HJS) handle referencing a JSON object or JSON array.

VALUE:
The value to be added.

The following data types are supported:
TEXT
TEXTLIST
NUMBER
NUMBERLIST
FLOAT
FLOATLIST
VSPECBINBUFFER
VSPECHJSON (HJS)

The conversion to JSON depends on the data type:
TEXT JSON String
TEXTLIST JSON Array of Strings

NUMBER JSON Real, Boolean or Integer
NUMBERLIST JSON Array of Real, Boolean or Integer values

FLOAT JSON Real, Boolean or Integer
FLOATLIST JSON Array of Real, Boolean or Integer values

VSPECBINBUFFER JSON String
VSPECHJSON JSON Object or JSON Array

For NUMBER, NUMBERLIST, FLOAT, and FLOATLIST, the JSON type Real is used by default if TEXT TYPE is not specified.
An Engine list is always inserted as a single JSON array. Therefore, if a list is added to an existing JSON array, a nested array is created.

Example:
VALUES:="A":"B":"C";
@JsonAdd(HJSON;VALUES);

For a JSON array, this results in:
[["A","B","C"]]
and not:
["A","B","C"]

TEXT KEY:
Key under which VALUE is stored in a JSON object.
This parameter is only used for JSON objects.

@JsonAdd(HJSON;"Max Mustermann";"Name");
for example creates:
{"Name":"Max Mustermann"}

If the specified key already exists, its value is replaced.
The key itself is not sanitized by the "S" option and must contain valid UTF-8.
If no KEY is specified for a JSON object, the current implementation uses an empty string as the key.
Normally, a KEY should therefore be specified for JSON objects.

TEXT TYPE:
Optional type or processing parameter for VALUE.
"R" Real
"B" Boolean
"I" Integer
"S" Sanitize invalid UTF-8 sequences in Strings
The values are case-insensitive.

Only one of these options can be specified at a time; combinations such as "SI" or "SB" are not permitted.
"R" – Real
Numeric values are stored as JSON Real values.
This is the default behavior and normally does not need to be specified explicitly.
@JsonAdd(HJSON;42;"Value";"R");
creates:
{"Value":42.0}

"B" – Boolean
Numeric values are interpreted as JSON Boolean values.
The value 0 results in false; any value other than 0 results in true.
@JsonAdd(HJSON;1;"Active";"B");
creates:
{"Active":true}

"I" – Integer
Numeric values are stored as JSON Integer values.
@JsonAdd(HJSON;42;"Count";"I");
creates:
{"Count":42}

For a FLOAT value, the value is converted to an integer value during conversion.

"S" – UTF-8 Sanitize
JSON strings must contain valid UTF-8. If "S" is specified, @JsonAdd attempts to sanitize invalid UTF-8 sequences in the supplied string before the value is added to the JSON structure.
The option applies to:
TEXT
TEXTLIST
VSPECBINBUFFER

Without "S", an invalid UTF-8 string causes the value not to be added.
The "S" option does not perform character set conversion. In particular, it is not an LMBCS-to-UTF-8 conversion. It is only intended to sanitize malformed UTF-8 sequences in data that is already supposed to be UTF-8.

Special behavior for JSON arrays:
Elements of a JSON array do not have keys. Therefore, the third parameter has a different meaning for a JSON array than for a JSON object.

HJSON:=@JsonCreate("Array");
@JsonAdd(HJSON;42);
@JsonAdd(HJSON;10;"I");
@JsonAdd(HJSON;1;"B");

results in:
[42.0,10,true]
A fourth parameter is not permitted for a JSON array.

Notes:
The same Engine variable must not be used simultaneously as the target JSON and as the value to be added or as another parameter.
In this case, @JsonAdd returns the error:
SAME JSON VARIABLE CANNOT BE USED AS SOURCE AND TARGET

A VSPECBINBUFFER is treated by @JsonAdd as a UTF-8 string. Its contents are not parsed as JSON.
If an existing JSON text representation is to be inserted as an actual JSON structure, it must first be converted into a VSPECHJSON (HJS) handle, for example using @JsonLoad.

Example: Creating a JSON Object
HJSON:=@JsonCreate;
@JsonAdd(HJSON;"Max Mustermann";"Name");
@JsonAdd(HJSON;42;"Age";"I");
@JsonAdd(HJSON;1;"Active";"B");
@JsonAdd(HJSON;78.5;"Score");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

The resulting JSON structure is:
{"Name":"Max Mustermann","Age":42,"Active":true,"Score":78.5}

Example: Adding Lists
HJSON:=@JsonCreate;
NAMES:="Anna":"Bernd":"Claudia";
VALUES:=10:20:30;
@JsonAdd(HJSON;NAMES;"Names");
@JsonAdd(HJSON;VALUES;"Values";"I");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

The resulting JSON structure is:
{"Names":["Anna","Bernd","Claudia"],"Values":[10,20,30]}

A list is stored as one complete JSON array.

Example: Nested JSON Structures
HPERSON:=@JsonCreate;
HADDRESS:=@JsonCreate;
@JsonAdd(HADDRESS;"Berlin";"City");
@JsonAdd(HADDRESS;"Deutschland";"Country");
@JsonAdd(HPERSON;"Max Mustermann";"Name");
@JsonAdd(HPERSON;HADDRESS;"Address");
JSONTEXT:=@JsonSerialize(HPERSON;"A");
@JsonRelease(HADDRESS);
@JsonRelease(HPERSON);

The resulting JSON structure is:
{
"Name":"Max Mustermann",
"Address":{
"City":"Berlin",
"Country":"Deutschland"
}
}

A VSPECHJSON (HJS) handle supplied as VALUE is directly inserted as a JSON substructure.
@JsonAdd creates its own reference to the inserted JSON structure. Therefore, the handle supplied as VALUE remains valid and can be released independently from the parent JSON handle using @JsonRelease.

Example: JSON Array
HJSON:=@JsonCreate("Array");
@JsonAdd(HJSON;"Text1");
@JsonAdd(HJSON;"Text2");
@JsonAdd(HJSON;100;"I");
@JsonAdd(HJSON;TRUE;"B");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

The resulting JSON structure is:
["Text1","Text2",100,true]

Note : This text was machine-translated and may contain inaccuracies.