@JsonGet

This @Function reads a value from an existing JSON object or JSON array and, where possible, converts it into a corresponding Engine data type.

The behavior of the second parameter depends on whether HJSON references a JSON object or a JSON array.
For a JSON object, the second parameter must be a TEXT KEY. The value of the specified key is returned.
For a JSON array, the second parameter must be a numeric FN INDEX. JSON arrays use zero-based indexing, therefore the first element has index 0.

The optional TEXT OPTIONS parameter controls the return type and the handling of JSON strings. Multiple options can be combined within one string.

If a JSON object or JSON array is returned, @JsonGet creates a separate VSPECHJSON (HJS) handle for it. This handle must be released with @JsonRelease after use.

If the specified key or array index cannot be found, the function returns @ERROR.

As return value, the @Function returns @ERROR on failure; otherwise, it returns the requested JSON value converted into an appropriate Engine data type.

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

TEXT KEY:
Key of the value to be read from a JSON object.
For a JSON object, this parameter must be of type TEXT.

Example:
HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Age\":42}");
NAME:=@JsonGet(HJSON;"Name");
returns:
Max Mustermann

If the specified key does not exist, @JsonGet returns the @ERROR:
JSON VALUE NOT FOUND

FN INDEX:
Index of the element to be read from a JSON array.
The parameter may be specified as NUMBER or FLOAT.
JSON array indexing starts at 0.

Example:
HJSON:=@JsonLoad("[\"A\",\"B\",\"C\"]");
VALUE:=@JsonGet(HJSON;1);
returns:
B

If a FLOAT index is supplied, the value is reduced to an integer value when converted to the array index.

For example:
@JsonGet(HJSON;1.8);
accesses index 1.

Negative values, non-finite values, or indexes outside the array result in @ERROR:
JSON VALUE NOT FOUND

TEXT OPTIONS:
Optional parameter for controlling the return type and character set conversion.

The following options are supported:
"L" Return JSON array as an Engine list
"B" Return JSON string as VSPECBINBUFFER
"H" Return JSON string array as VHUGETEXTLIST
"T" Convert JSON strings from UTF-8 to LMBCS
The options are case-insensitive.

Multiple options can be combined, for example:
"LT"
"HT"
"BT"

"L", "B", and "H" determine the return type. If more than one of these options is specified, the last return type option takes effect.
The "T" option can additionally be combined with a return type option.
Unknown options result in @ERROR:
INVALID JSON GET OPTION

Conversion of JSON data types
Without a specific return type option, the conversion is performed as follows:

JSON String TEXT
JSON Integer FLOAT
JSON Real FLOAT
JSON Boolean NUMBER
JSON Object VSPECHJSON (HJS)
JSON Array VSPECHJSON (HJS)
JSON Null @ERROR

JSON String
A JSON string is returned as TEXT by default.
VALUE:=@JsonGet(HJSON;"Name");

If the string exceeds the maximum permitted size of a normal TEXT value, it can be returned as a VSPECBINBUFFER using the "B" option:
BUFFER:=@JsonGet(HJSON;"Data";"B");

The buffer contains the exact bytes of the JSON string.
The "L" and "H" options do not change the return type of a single JSON string; the value is still returned as TEXT.

JSON Integer and JSON Real
JSON Integer and JSON Real values are returned as Engine FLOAT.

Example:
HJSON:=@JsonLoad("{\"Count\":42,\"Value\":12.75}");
COUNT:=@JsonGet(HJSON;"Count");
VALUE:=@JsonGet(HJSON;"Value");

COUNT contains the numeric value 42, while VALUE contains 12.75.
A JSON Integer is also returned as Engine FLOAT.

JSON Boolean
A JSON Boolean is returned as Engine NUMBER.
false 0
true 1

Example:
HJSON:=@JsonLoad("{\"Active\":true}");
ACTIVE:=@JsonGet(HJSON;"Active");

returns:
1

JSON Object
A JSON object contained within the JSON structure is returned as a new VSPECHJSON (HJS) handle.

Example:
HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Address\":{\"City\":\"Berlin\",\"Country\":\"Deutschland\"}}");
HADDRESS:=@JsonGet(HJSON;"Address");
CITY:=@JsonGet(HADDRESS;"City");
@JsonRelease(HADDRESS);
@JsonRelease(HJSON);

HADDRESS references the object contained within the original JSON:
{
"City":"Berlin",
"Country":"Deutschland"
}

The handle created by @JsonGet owns its own reference to this JSON structure. It therefore remains valid independently of the original handle and must be released separately with @JsonRelease.

JSON Array
A JSON array is also returned as a new VSPECHJSON (HJS) handle by default.

Example:
HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"]}");
HNAMES:=@JsonGet(HJSON;"Names");
NAME:=@JsonGet(HNAMES;1);
@JsonRelease(HNAMES);
@JsonRelease(HJSON);

NAME contains:
Bernd

Alternatively, @JsonGet can attempt to convert the JSON array into an Engine list.

Option "L" – Array as Engine list
With "L", a JSON array is converted, where possible, into a corresponding Engine list type.

The following array types can be converted:
JSON array of strings TEXTLIST
JSON array of Boolean values NUMBERLIST
JSON array of numbers FLOATLIST

In numeric arrays, JSON Integer and JSON Real values may be mixed. In both cases, the result is a FLOATLIST.

Example:
HJSON:=@JsonLoad("{\"Values\":[10,20.5,30]}");
VALUES:=@JsonGet(HJSON;"Values";"L");

returns a FLOATLIST containing:
10 : 20.5 : 30

A string array:
HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"]}");
NAMES:=@JsonGet(HJSON;"Names";"L");

is returned as a TEXTLIST.

Option "H" – Array als VHUGETEXTLIST
With "H", a JSON array of strings can be returned as a VHUGETEXTLIST.

This is particularly useful when the string list may exceed the size limit of a normal TEXTLIST.

Example:
NAMES:=@JsonGet(HJSON;"Names";"H");

The "H" option is only meaningful for JSON arrays containing strings.

Convertibility of JSON arrays
To convert a JSON array into an Engine list, its elements must contain compatible data types.

An array such as:
["A","B","C"]
can be converted into a TEXTLIST or VHUGETEXTLIST.

An array such as:
[10,20.5,30]
can be converted into a FLOATLIST. JSON Integer and JSON Real values may be mixed.

An array such as:
[true,false,true]
can be converted into a NUMBERLIST.

Mixed arrays such as:
["A",10,true]
cannot be converted into an Engine list.

The same applies to arrays containing objects, nested arrays, or null values.
In these cases, @JsonGet may for example return:
UNABLE TO CONVERT JSON ARRAY WITH MIXED VALUES
or:
JSON ARRAY NOT CONVERTIBLE TO ENGINE LIST

An empty JSON array also cannot automatically be converted into an Engine list type because there is no element from which the required list type could be determined.

Option "T" – UTF-8 to LMBCS
JSON strings are stored internally as UTF-8.
Using the "T" option, a returned JSON string can be converted from UTF-8 to LMBCS.

Example:
NAME:=@JsonGet(HJSON;"Name";"T");
The option can also be combined with other options:

BUFFER:=@JsonGet(HJSON;"Text";"BT");
NAMES:=@JsonGet(HJSON;"Names";"LT");
HUGENAMES:=@JsonGet(HJSON;"Names";"HT");

With "LT", for example, all strings in a JSON array are converted to LMBCS and then returned as a TEXTLIST.
With "HT", the corresponding conversion is performed for a VHUGETEXTLIST.

The "T" option only affects JSON strings. Numeric values, Boolean values, and JSON objects are not modified.
If "T" alone is applied to a JSON array, the default return type of the array remains a VSPECHJSON (HJS) handle; the strings contained in the array are not converted in this case.

JSON Null
A JSON null value has no directly corresponding Engine data type and therefore cannot be returned by @JsonGet.

Example:
{"Value":null}
VALUE:=@JsonGet(HJSON;"Value");

results in:
JSON NULL VALUE CANNOT BE REPRESENTED

Notes:
A VSPECHJSON (HJS) handle returned by @JsonGet owns its own reference to the corresponding JSON object or JSON array.
The original JSON handle and the handle created by @JsonGet can therefore be released independently using @JsonRelease.

For JSON arrays, @JsonGet uses the standard zero-based JSON indexing:
0 first element
1 second element
2 third element
…

Example: Reading values from a JSON object

HJSON:=@JsonLoad("{\"Name\":\"Max Mustermann\",\"Age\":42,\"Active\":true,\"Score\":78.5}");
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
ACTIVE:=@JsonGet(HJSON;"Active");
SCORE:=@JsonGet(HJSON;"Score");
@JsonRelease(HJSON);

The return values are:
NAME "Max Mustermann"
AGE 42
ACTIVE 1
SCORE 78.5

Example: Reading an array

HJSON:=@JsonLoad("[\"Text1\",\"Text2\",\"Text3\"]");
VALUE1:=@JsonGet(HJSON;0);
VALUE2:=@JsonGet(HJSON;1);
VALUE3:=@JsonGet(HJSON;2);
@JsonRelease(HJSON);

The values are:
VALUE1 "Text1"
VALUE2 "Text2"
VALUE3 "Text3"

Example: Returning a JSON array as a list

HJSON:=@JsonLoad("{\"Names\":[\"Anna\",\"Bernd\",\"Claudia\"],\"Values\":[10,20,30]}");
NAMES:=@JsonGet(HJSON;"Names";"L");
VALUES:=@JsonGet(HJSON;"Values";"L");
@JsonRelease(HJSON);

NAMES is returned as a TEXTLIST, while VALUES is returned as a FLOATLIST.

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