|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetNum
Retrieves the numeric value of a node at a specified path as a string.
Intention
The PSJ.GetNum command in SPR is designed to fetch a numeric value (like an integer or decimal) from a JSON document at a given path ($$PATH), using the document handle ($$DH). The number is returned as a string, which you can optionally store in a variable (e.g., $$RET). This is useful for extracting measurements, counts, or any numeric data stored in JSON.
Picture it as asking your robot, “What’s the number on this JSON label?”—and it replies with something like "42" or "3.14", placing it on the Top of Stack (TOS) or in your variable.
Illustration
Consider this JSON document:
{"data": {"count": 42, "price": 19.99}}
- 🔍 PSJ.GetNum|123|data.count|$$RET stores "42" in $$RET.
- 🔍 PSJ.GetNum|123|data.price places "19.99" on TOS.
Syntax
PSJ.GetNum|$$DH|$$PATH[|$$RET]
Parameter Explanation
P1 - $$DH - (Variable, Numeric)
The document handle identifying the JSON data to search (e.g., $$DH as "123"). Required. Obtained from commands like PSJ.Parse or PSJ.LoadFile.
P2 - $$PATH - (Variable, String)
The path to the numeric value in the JSON (e.g., $$PATH as "data.count"). Required. Use dot notation (e.g., "stats.total") or array indices (e.g., "values.0").
P3 - $$RET - (Variable, String, Optional)
The variable to store the numeric value as a string (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.GetNum - Sample 1: Get an Integer
'***********************************
PSJ.Parse|{"items": 150}|$$DH
PSJ.GetNum|$$DH|items|$$RET
MBX.Value: $$RET ' Displays "150"
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetNum - Sample 2: Get a Decimal from Array
'***********************************
PSJ.Parse|{"prices": [9.99, 15.50]}|$$DH
PSJ.GetNum|$$DH|prices.1|$$RET
PRT.Value: $$RET ' Prints "15.50"
PSJ.Free|$$DH
MBX.Ready
'
'***********************************
' PSJ.GetNum - Sample 3: Result on TOS
'***********************************
PSJ.Parse|{"temp": 23.5}|$$DH
PSJ.GetNum|$$DH|temp
' Places "23.5" on Top of Stack (TOS)
PSJ.Free|$$DH
MBX.Ready
'
Remarks
- Returns the number as a string (e.g., "123" or "12.34"). Use VAL() in SPR to convert it to a numeric type if needed.
- Returns an empty string ("") if the path doesn’t exist or the node isn’t a number.
- Use PSJ.GetType to confirm the node is a number if necessary.
Limitations
- Requires a valid document handle; invalid handles return an empty string.
- Only works on numeric nodes; other types (e.g., strings, booleans) return "", which might confuse an empty result with an error.
See also: