|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Text-Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.CreateArrFromStr
Creates a JSON array from a delimited string.
Intention
The PSJ.CreateArrFromStr command in SPR takes a string of values (like a list of items separated by a character) and turns it into a JSON array—a structured format computers love to work with. You give it the string of values ($$VALUES), an optional separator character ($$DELIM), and an optional variable to store the result ($$RET). If you don’t specify a separator, it defaults to a semicolon (;). The command then creates a JSON array where each piece of the string becomes an element, ready for further processing in your script.
Think of it as turning a shopping list written as "apples;bananas;oranges" into a neat JSON box: ["apples", "bananas", "oranges"]—perfect for your robot assistant to handle! You’ll get a handle (a number) to this box, which you must later free with PSJ.Free when you’re done.
Illustration
📝 Input: PSJ.CreateArrFromStr|cat;dog;bird|;|$$ARR creates ["cat", "dog", "bird"].
📝 Default: PSJ.CreateArrFromStr|red;green;blue|$$COLORS uses ";" to make ["red", "green", "blue"].
Syntax
PSJ.CreateArrFromStr|$$VALUES[|$$DELIM|$$RET]
Parameter Explanation
P1 - $$VALUES - (Variable, String)
The string containing values to split (e.g., $$VALUES as "apple;banana;orange"). Required.
P2 - $$DELIM - (Variable, String, Optional)
The delimiter to split the string (e.g., $$DELIM as "," or ";"). Defaults to ";" if omitted.
P3 - $$RET - (Variable, Numeric, Optional)
The variable to store the JSON array handle (e.g., $$RET as "$$ARR"). If omitted, the handle is returned but not stored.
Technical Background
This command calls W_JSON_CreateArrayFromStrings, which creates a JSON array from a list of values separated by $$DELIM (default ";"). It returns a document handle—a number representing the array (e.g., ["Hi", "Hello"] from "Hi;Hello"). If an error occurs (e.g., memory allocation fails), it returns 0 and sets global error variables gLastJSONError and gLastJSONErrorMsg. Internally, it builds a temporary object with an "array" property, fills it with the split values, and extracts the array as the final result. The caller must free this handle using PSJ.Free (which calls W_JSON_FreeHandle) to avoid memory leaks.
Examples
'***********************************
' Sample 1: Basic Array Creation with Free
'***********************************
PSJ.CreateArrFromStr|one;two;three|;|$$ARR
PRT.Created array handle: $$ARR
' Use the array here (e.g., PSJ.ToString)
PSJ.Free|$$ARR
MBX.Ready
'
'***********************************
' Sample 2: Custom Delimiter
'***********************************
PSJ.CreateArrFromStr|a,b,c|,|$$LIS
PRT.Array handle: $$LIS
PSJ.Free|$$LIS
MBX.Ready
'
'***********************************
' Sample 3: Default Delimiter, No Return Var
'***********************************
PSJ.CreateArrFromStr|x;y;z
' Handle returned but not stored or freed here
MBX.Ready
'
Remarks
- Returns a handle to the created JSON Doc, which can be used with commands like PSJ.ToString.
- Each value becomes a string element in the JSON array.
- The caller must free the handle with PSJ.Free to prevent memory leaks.
Limitations
- $$DELIM should be a single character for best results.
- Empty values (e.g., "a;;c") result in empty strings in the array.
- Failing to free the handle causes memory leaks.
See also:
• PSJ.Free