|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.MergeArrs
Merges child nodes from one JSON array into another and returns the count.
Intention
The PSJ.MergeArrs command in SPR combines all child nodes from a source JSON array ($$SRC) into a destination JSON array ($$DST), appending them as individual elements. It returns the number of nodes merged, which you can optionally store in a variable (e.g., $$RET). This is useful for consolidating array data within a JSON document.
Think of it as telling your robot, “Take all the items from this array box and add them to that array box,”—and it tells you 3 if it moved three items, placing the count on the Top of Stack (TOS) or in your variable.
Illustration
Consider these JSON arrays:
Dest: [1, 2] Src: [3, 4, 5]
- 🔍 PSJ.MergeArrs|$$DST|$$SRC|$$RET merges [3, 4, 5] into [1, 2], resulting in [1, 2, 3, 4, 5], and stores "3" (nodes merged) in $$RET.
- 🔍 PSJ.MergeArrs|$$DST|$$SRC places "3" on TOS.
Syntax
PSJ.MergeArrs|$$DST|$$SRC[|$$RET]
Parameter Explanation
P1 - $$DST - (Variable, Numeric)
The node ID of the destination JSON array (e.g., $$DST as "5"). Required. Must be an array node.
P2 - $$SRC - (Variable, Numeric)
The node ID of the source JSON array (e.g., $$SRC as "6"). Required. Must be an array node.
P3 - $$RET - (Variable, String, Optional)
The variable to store the number of merged nodes as a string (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS).
Examples
'***********************************
' PSJ.MergeArrs - Sample 1: Merge Two Arrays
'***********************************
PSJ.Parse|[1, 2]|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|[3, 4]|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeArrs|$$DST|$$SRC|$$RET
MBX.Merged: $$RET ' Displays "2", array now [1, 2, 3, 4]
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
'***********************************
' PSJ.MergeArrs - Sample 2: Merge Mixed Types
'***********************************
PSJ.Parse|["a"]|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|[1, true]|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeArrs|$$DST|$$SRC|$$RET
PRT.Merged: $$RET ' Prints "2", array now ["a", 1, true]
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
'***********************************
' PSJ.MergeArrs - Sample 3: Result on TOS
'***********************************
PSJ.Parse|[10]|$$DHA
PSJ.GetByPath|$$DHA||0|$$DST
PSJ.Parse|[20, 30]|$$DHB
PSJ.GetByPath|$$DHB||0|$$SRC
PSJ.MergeArrs|$$DST|$$SRC
' Places "2" on TOS, array now [10, 20, 30]
PSJ.Free|$$DHA
PSJ.Free|$$DHB
MBX.Ready
'
Remarks
- Returns the number of nodes merged as a string (e.g., "3") or "-1" if an error occurs (e.g., non-array nodes).
- Both $$DST and $$SRC must be array nodes; use PSJ.GetType to verify (type "5").
- Modifies the destination array in place by appending source elements.
Limitations
- Both nodes must be arrays; non-array nodes result in "-1".
- Requires valid node IDs from a parsed JSON document.
See also: