|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations (WsLnTre Integrated) |
SPR Script Language
PSJ.ExtractArrLen
Parses JSON text and returns the length (element count) of an array at a specified path.
Intention
The PSJ.ExtractArrLen command provides a quick, one-shot way to determine the number of elements within a JSON array located at a specific path within a given JSON string. It performs the parsing and length retrieval in a single step without requiring the user to manage document handles explicitly.
For example, given the JSON {"results": ["X", "Y", "Z"]}, using the path "results" would return the count 3.
Illustration
📝 Count: PSJ.ExtractArrLen|{"items":["a","b"]}|items|$$NUM sets $$NUM to 2.
📝 Nested: PSJ.ExtractArrLen|{"data":{"list":[1,2,3]}}|data.list|$$CNT sets $$CNT to 3.
📝 Empty: PSJ.ExtractArrLen|{"emptyList":[]}|emptyList|$$LEN sets $$LEN to 0.
Syntax
PSJ.ExtractArrLen|$$JSON|$$PATH[|$$RET_COUNT]
Parameter Explanation
P1 - $$JSON - (Variable, String)
The JSON text string to parse (UTF-8 assumed). Required.
P2 - $$PATH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) to the target array within the JSON text. Required.
P3 - $$RET_COUNT - (Variable, Numeric, Optional)
The SSPR variable name (e.g., $$COUNT) to store the result. The result will be the array length (a LONG integer >= 0) or -1 if an error occurs.
Technical Background
This command performs the following steps:
1.Converts the input $$JSON string (UTF-8) to an internal WSTRING.
2.Parses the WSTRING using W_JSON_ParseString, obtaining a temporary document handle.
3.Converts the input $$PATH (UTF-8) to an internal WSTRING path.
4.Calls W_JSON_ArrayGetLength using the temporary handle and WSTRING path.
5.Frees the temporary document handle using W_JSON_FreeHandle.
6.Returns the count (>= 0) or -1 if any step failed. The last error code/message can be retrieved using PSJ.ErrCode and PSJ.ErrMsg.
Examples
'***********************************
' Sample 1: Simple Array Count
PSJ.ExtractArrLen|{"items":["a","b"]}|items|$$NUM
' Print the count
PRT.Array length: $$NUM
MBX.Ready
'***********************************
' Sample 2: Nested Array Count
PSJ.ExtractArrLen|{"data":{"list":[1,2,3]}}|data.list|$$CNT
' Print the count
PRT.Array length: $$CNT
MBX.Ready
'***********************************
' Sample 3: No Return Variable
PSJ.ExtractArrLen|{"list":["x","y"]}|list
' Length returned but not stored
MBX.Ready
'***********************************
' Sample 4: Path Not Found or Not Array
PSJ.ExtractArrLen|{"items":"abc"}|items|$$LEN
PRT.Result (should be -1): $$LEN
PSJ.ErrMsg|$$ERRMSG
PRT.Error Message: $$ERRMSG
MBX.Ready
Remarks
- This is a "one-shot" command; it parses the JSON text each time it's called. For multiple operations on the same JSON, use PSJ.Parse first, then PSJ.ArrLen with the handle.
- Returns the count (a LONG integer >= 0) on success.
- Returns -1 if the JSON is invalid, the path doesn’t exist, or the node at the path isn’t an array.
- Use PSJ.ErrCode / PSJ.ErrMsg to get specific error details if -1 is returned.
Limitations
- $$JSON must contain valid JSON text, or the command will fail (-1).
- $$PATH must correctly point to an array within the JSON structure.
See also:
• PSJ.ArrLen (Requires document handle)