|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.DelElem
Removes an element at a specified **zero-based** index from a JSON array.
Intention
Use the PSJ.DelElem command to remove a specific item from a JSON array based on its position (index). You specify the document handle ($$DH), the path ($$PT) to the array, and the **zero-based** index ($$IX) of the element you want to remove (e.g., index 0 removes the first element, index 1 removes the second, etc.). All subsequent elements in the array will shift down to fill the gap. Optionally, get a status code back in $$RC.
This command is essential for managing dynamic lists where items need to be deleted. Note that this operation modifies the array in place within the specified document handle.
Illustration
If document $$D1 contains { "items": [ "apple", "banana", "cherry" ] }:
📝 Remove Middle Element: PSJ.DelElem|$$D1|items|1 modifies the JSON to { "items": [ "apple", "cherry" ] }.
📝 Remove First Element: PSJ.DelElem|$$D1|items|0 changes it further to { "items": [ "cherry" ] }.
Syntax
PSJ.DelElem|$$DH|$$PT|$$IX[|$$RC]
Parameter Explanation
P1 - $$DH - (Variable, Numeric)
The document handle (e.g., `$$D1`). Required.
P2 - $$PT - (Variable, String)
The path to the array (e.g., `$$P1` as "root.array"). Required.
P3 - $$IX - (Variable, Numeric)
The zero-based index of the element to remove (e.g., `$$I1` as "0"). Required.
P4 - $$RC - (Variable, Numeric, Optional)
Variable to store the status code (e.g., `$$ST`). Returns 0=Success, non-zero=Error. Optional.
Examples
'***********************************
' Sample 1: Remove an Element
VAR $$J1 = '{ "users": [ "admin", "guest", "testuser" ] }'
PSJ.Parse|$$J1|$$DH
IF $$DH > 0 THEN
// Remove the "guest" user (at index 1)
VAR $$PTH = "users"
VAR $$IDX = 1
PSJ.DelElem|$$DH|$$PTH|$$IDX|$$RC
IF $$RC <> 0 THEN
PSJ.ErrMsg|$$EM
PRT.Error removing element: $$EM
ELSE
PRT.Element at index $$IDX removed successfully.
PSJ.ToString|$$DH|$$R1
PRT.New JSON: $$R1
// Output: {"users":["admin","testuser"]}
END IF
// Attempt to remove an element at an invalid index
VAR $$IDX = 5
PSJ.DelElem|$$DH|$$PTH|$$IDX|$$RC
IF $$RC <> 0 THEN
PSJ.ErrMsg|$$EM
PRT.Error removing element at index $$IDX: $$EM
// Expected Error: Index 5 is out of range [...]
END IF
PSJ.Free|$$DH
END IF
MBX.Ready
Remarks
- **Important:** The $$IX parameter is **zero-based**, meaning the first element is at index 0.
- This command modifies the array in place. The removed element and its entire subtree (if it was an object or array) are freed from memory.
- The return code in `$$RC` should be checked. A non-zero value indicates an error, which can be diagnosed further using PSJ.ErrCode and PSJ.ErrMsg.
- This command relies on the underlying `W_JSON_Node_RemoveChild` core function, which is intended **only for arrays** due to the WsLnTre integration for objects.
Limitations
- The node identified by $$PT must be an array. Attempting to use this on an object or primitive value will result in an error.
- The $$IX must be a valid, non-negative integer less than the current size of the array.
See also:
• PSJ.AppendStr (and other Append commands)