|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.AppendNum
Appends a numeric value to the end of a JSON array.
Intention
Use the PSJ.AppendNum command to add a numeric value (integer or floating-point) as a new element at the end of an existing JSON array. You specify the document handle ($$DOC), the path ($$PATH) to the target array, and the numeric value ($$VALUE) itself. The command internally converts the number to its standard string representation before adding it to the JSON structure.
This is useful for building lists of measurements, counts, scores, IDs, or any other numeric data within a JSON array.
Illustration
If document $$MyDoc contains { "scores": [ 100, 95 ] }:
📝 Append Integer: PSJ.AppendNum|$$MyDoc|scores|88 results in { "scores": [ 100, 95, 88 ] }.
📝 Append Float: PSJ.AppendNum|$$MyDoc|scores|92.5 changes it further to { "scores": [ 100, 95, 88, 92.5 ] }.
Syntax
PSJ.AppendNum|$$DOC|$$PATH|$$VALUE[|$$RET]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The document handle (a number greater than 0) representing the loaded/parsed JSON structure you want to modify. Obtained from PSJ.Parse, PSJ.LoadFile, or creation commands. Required.
P2 - $$PATH - (Variable, String)
The path string identifying the target JSON array within the document specified by $$DOC. See Understanding JSON Paths in PSJ. for syntax details (e.g., `measurements`, `data[0].values`). The node found at this path must be an array. Required.
P3 - $$VALUE - (Variable, Numeric)
The numeric value (integer or floating-point) to append to the array (e.g., `123`, `-5`, `3.14159`). Required.
P4 - $$RET - (Variable, Numeric, Optional)
An optional variable name (e.g., `$$StatusCode`) to store the command's execution status. Returns **0** (%JSON_ERR_NONE) on success, or a non-zero JSW error code on failure.
Examples
VAR $$MyJson = '{ "sensorReadings": [ 12.5 ] }'
PSJ.Parse|$$MyJson|$$Doc
IF $$Doc > 0 THEN
VAR $$Temperature = 13.7
PSJ.AppendNum|$$Doc|sensorReadings|$$Temperature|$$RetCode
IF $$RetCode = 0 THEN PRT.Appended: $$Temperature
PSJ.AppendNum|$$Doc|sensorReadings|11
PSJ.ToString|$$Doc|$$Result
PRT.Result:|$$Result
// Output: {"sensorReadings":[12.5,13.7,11]}
PSJ.Free|$$Doc
END IF
MBX.Ready
Remarks
- The target node specified by $$PATH must exist and be a JSON array. Use PSJ.SetArrByPath if needed.
- The number provided in $$VALUE will be stored internally as its string representation according to standard JSON number formatting.
- Check the optional `$$RET` variable or use PSJ.ErrCode / PSJ.ErrMsg for errors.
Limitations
- Cannot append to non-array nodes.
- The path must correctly identify an existing array within the document.
See also: