|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Array Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.AppendStr
Appends a string value to the end of a JSON array specified by path.
Intention
Use the PSJ.AppendStr command to add a new string item to an existing JSON array. You specify the target document ($$DOC), the path to the array ($$PTH), and the string value to append ($$VAL). Input strings are assumed to be UTF-8 and are handled internally as WSTRINGs. The command returns a status code indicating success or failure.
Illustration
📝 Initial JSON in $$DOC=1:
{"users":["Alice"]}
📝 Command:
PSJ.AppendStr|1|users|Bob
Result: Document 1 now represents {"users":["Alice","Bob"]}.
📝 Append string with spaces and check status:
PSJ.AppendStr|1|users|Charlie Chaplin|$$RES
Result: Document 1 now represents {"users":["Alice","Bob","Charlie Chaplin"]}. $$RES holds 0.
Syntax
PSJ.AppendStr|$$DOC|$$PTH|$$VAL[|$$RES]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier (handle) of the JSON document containing the target array. Required.
P2 - $$PTH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) to the target array node within the document. An empty string targets the root node if it's an array. Assumed UTF-8, converted internally. Required.
P3 - $$VAL - (Variable, String)
The string value to append to the array. Assumed UTF-8, converted internally to WSTRING. Required.
P4 - $$RES - (Variable, Numeric, Optional)
The variable where the result code (%JSON_ERR_*) will be stored. 0 indicates success. If omitted, the result code is returned but not stored.
Technical Background
This command calls W_JSON_ArrayAppendString(docHandle, pathW, valueW) after converting the path and value parameters from STRING (UTF-8 assumed) to WSTRINGs. The JSW function finds the array node at the path, creates a new node of type %JSON_TYPE_STRING with the provided value, and then links this new node as the last element of the target array using W_JSON_Node_AddChild.
Examples
'***********************************
' Sample 1: Append names to a list
PSJ.Parse|'{"names":[]}'|$$DOC
PSJ.AppendStr|$$DOC|names|Alice
PSJ.AppendStr|$$DOC|names|Bob
PSJ.ToString|$$DOC|$$JSON_OUT
PRT.Result: $$JSON_OUT ' Output: {"names":["Alice","Bob"]}
PSJ.Free|$$DOC
MBX.Ready
'***********************************
' Sample 2: Append to root array with status check
PSJ.Parse|'[]'|$$DOC
PSJ.AppendStr|$$DOC||First Item|$$RES
IFE $$RES <> 0 THEN PRT.Error!
PSJ.AppendStr|$$DOC||Second Item|$$RES
IFE $$RES <> 0 THEN PRT.Error!
PSJ.ToString|$$DOC|$$JSON_OUT
PRT.Result: $$JSON_OUT ' Output: ["First Item", "Second Item"]
PSJ.Free|$$DOC
MBX.Ready
'***********************************
Remarks
- The appended string is stored internally as a WSTRING (UTF-16LE). Any required JSON escaping (e.g., for quotes or backslashes within the string) happens automatically when the document is later serialized using PSJ.ToString or PSJ.NodeToStr.
- A return code of 0 indicates success; non-zero indicates an error.
Limitations
- The node specified by $$PTH must exist and must be of type Array.
See also: