|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.ArrLen
Gets the number of elements (length) of a JSON array specified by path.
Intention
Use the PSJ.ArrLen command to find out how many items are currently inside a JSON array. You provide the document handle ($$DOC) and the path to the array ($$PTH). The command returns the non-negative count of elements in the array, or -1 if the path doesn't point to a valid array or another error occurs. The result can be stored in an optional variable ($$RES).
Illustration
📝 JSON in $$DOC=1:
{"items":["a", "b", "c"], "empty":[]}
📝 Command:
PSJ.ArrLen|1|items|$$LEN
Result: $$LEN will be set to "3".
PSJ.ArrLen|1|empty|$$LEN2
Result: $$LEN2 will be set to "0".
PSJ.ArrLen|1|nonexistent|$$LEN3
Result: $$LEN3 will be set to "-1".
PSJ.ArrLen|1|items.a|$$LEN4 // Error: Trying to get length of a string
Result: $$LEN4 will be set to "-1".
Syntax
PSJ.ArrLen|$$DOC|$$PTH[|$$RES]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier (handle) of the JSON document containing the target array. Required.
P2 - $$PTH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) to the target array node within the document. An empty string targets the root node if it's an array. Assumed UTF-8, converted internally. Required.
P3 - $$RES - (Variable, Numeric, Optional)
The variable where the array length (number of elements) will be stored.
- Returns count (0 or greater) on success.
- Returns -1 if the path is not found, the node is not an array, or another error occurs.
If omitted, the length is returned but not stored.
Technical Background
This command calls the W_JSON_ArrayGetLength(docHandle, pathW) function in the JSW library after converting the path to WSTRING. The JSW function locates the node specified by the path using W_JSON_FindNodeByPath (or W_JSON_Node_GetRootNode if the path is empty). If the node is found and validated to be of type %JSON_TYPE_ARRAY, it calls W_JSON_Node_GetChildCount which returns the count stored for that array node. If any step fails (node not found, wrong type), it returns -1 and sets the appropriate error code.
Examples
'***********************************
' Sample 1: Get length of a nested array
VAR $$MYJSON = '{"data":{"ids":[101, 102, 103]}}'
PSJ.Parse|$$MYJSON|$$DOC
PSJ.ArrLen|$$DOC|data.ids|$$COUNT
PRT.Array Length: $$COUNT ' Output: 3
PSJ.Free|$$DOC
MBX.Ready
'***********************************
' Sample 2: Check for error
PSJ.Parse|'{"name":"value"}'|$$DOC
PSJ.ArrLen|$$DOC|name|$$COUNT
IFE $$COUNT = -1 THEN
PSJ.ErrMsg|$$ERR
PRT.Error getting array length: $$ERR
' Output: Error getting array length: [...] Target node (...) is not an array (...)
ELSE
PRT.Length: $$COUNT
END
PSJ.Free|$$DOC
MBX.Ready
'***********************************
Remarks
- Returns 0 for an empty array ([]).
- Use PSJ.ErrCode to get the specific error reason if the command returns -1.
Limitations
- The node targeted by $$PTH must exist and be of type Array for a non-negative result.
See also:
• PSJ.ChildCount (Use ArrLen for arrays)