MiniRobotLanguage (MRL)
ARR.Parse
Parse a String into an Array Using a Delimiter
Split a source string into array elements based on a specified or default delimiter.
Intention
The ARR.Parse command splits a source string (P2) into elements and stores them in a specified string array (P1) using a delimiter (P3). If the delimiter is omitted, a comma (",") is used by default. The command is ideal for processing delimited data, such as CSV strings or log entries, into an array for further manipulation. The number of parsed elements is returned on the Top of Stack (TOS).
•Array Number: The array is specified by a number (0–32), which is modified in-place with the parsed elements.
•Delimiter: A string that separates elements in the source string. Defaults to "," if omitted or empty.
•Return Value: The number of elements parsed is pushed to the TOS.
•Binary Safety: The command is binary-safe, handling special characters or null bytes in the source string.
Schematic (String Parsing to Array)
Source String: apple,banana,orange
Command: ARR.Parse|1|apple,banana,orange|,
Result Array[1]: ["apple", "banana", "orange"]
TOS: 3 (number of elements parsed)
Syntax
ARR.Parse|P1|P2[|P3]
Parameter Explanation
•P1 - Array Number: Specifies the string array number (0–32) to store the parsed elements. Resolved to an integer.
•P2 - Source String: The string to parse, containing delimited elements. Can be a variable or literal.
•P3 - Delimiter (Optional): The string used to split P2. Defaults to "," if omitted or empty.
Examples
'***********************************
' Example 1: Parse with default delimiter
'***********************************
VAR.$$SRC=apple,banana,orange
ARR.Parse|1|$$SRC
' Array 1 contains: ["apple", "banana", "orange"]
ARR.Get|1|1|$$RET
ARR.Show|1
MBX.$$RET
ENR.
'***********************************
' Example 2: Parse with custom delimiter
'***********************************
VAR.$$SRC=cat;dog;bird
ARR.Parse|2|$$SRC|;
' Array 2 contains: ["cat", "dog", "bird"]
ARR.Get|2|2|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Parse empty string
'***********************************
VAR.$$SRC=
ARR.Parse|3|$$SRC
' Array 3 contains: []
POP.$$CNT
MBX.$$CNT
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Parse
' Purpose: Verify functionality with JIV. for automated checks.
' Tests default delimiter, custom delimiter, empty string, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Parse with default delimiter
STS.CLEAR
ARR.Clr|1
VAR.$$SRC=apple,banana,orange
ARR.Parse|1|$$SRC
ARR.Get|1|1|$$RET
$$EXP=banana
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'--------------------------------------
:Lab_Next1
PRT. Test 1.2: Parse with custom delimiter
STS.CLEAR
ARR.Clr|2
VAR.$$SRC=cat;dog;bird
ARR.Parse|2|$$SRC|;
ARR.Get|2|1|$$RET
$$EXP=dog
JIV.$$RET!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'--------------------------------------
:Lab_Next2
PRT. Test 1.3: Parse empty string
STS.CLEAR
ARR.Clr|3
VAR.$$SRC=
ARR.Parse|3|$$SRC
POP.$$CNT
$$EXP=0
JIV.$$CNT!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'--------------------------------------
:Lab_Next3
PRT. Test 1.4: Invalid array number (negative)
STS.CLEAR
ARR.Clr|4
VAR.$$SRC=apple,banana
ARR.Parse|-1|$$SRC
ARR.Get|4|0|$$RET
$$EXP=
JIV.$$RET!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'--------------------------------------
:Lab_Next4
PRT. Test 1.5: Invalid parameter count (too few)
STS.CLEAR
ARR.Clr|5
ARR.Parse|5
ARR.Get|5|0|$$RET
$$EXP=
JIV.$$RET!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'--------------------------------------
:Lab_Next5
PRT. Test 1.6: Empty delimiter
STS.CLEAR
ARR.Clr|6
VAR.$$SRC=apple,banana
ARR.Parse|6|$$SRC||
ARR.Get|6|1|$$RET
$$EXP=banana
JIV.$$RET!$$EXP|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
GSB.Test
:Lab_Next6
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
JIV.$$FAI=0|Lab_Success
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
JMP.Lab_End
:Lab_Success
MBX.SUCCESS: All tests passed!|Test Result|64
:Lab_End
ENR.
:Test
$$MSG= -> FAIL - Result: $$RET (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
RET.
Remarks
- The command is binary-safe, handling special characters or null bytes in the source string or delimiter.
- P1 is resolved to an integer; non-integer values are rounded down.
- If P3 is empty or omitted, the default comma (",") is used as the delimiter.
- The number of parsed elements is returned on the TOS, useful for checking the result.
- The array is cleared before parsing, ensuring no residual elements remain.
Limitations
- Array numbers are limited to 0–32, consistent with other MRL array commands.
- Invalid array numbers (e.g., negative or >32) result in no operation.
- Requires 2 or 3 parameters; fewer or more parameters result in no operation.
- No support for multidimensional arrays or complex parsing patterns.
See also:
• ARR.Set
• ARR.Get
• ARR.Clr
• ARR.Dim