MiniRobotLanguage (MRL)
ARR.Add Element
Append an Element to the End of an Array
Add a new element to the end of a specified array, automatically resizing if necessary.
Intention
The ARR.Add Element command appends a new element to the end of a specified array (P1). The element to add is specified by P2, which can be a string or binary string. If P2 is omitted, an empty string is added. The command automatically resizes the array to accommodate the new element, making it ideal for dynamically building arrays or appending data in tasks like data collection or list management.
The command is binary-safe, ensuring that null characters or special sequences in P2 are handled without variable expansion. The array is modified in-place, with the new element added at the next available index.
•Auto-Dim: If the array is not large enough, it is automatically resized to include the new element.
•Binary Safety: The element value is resolved once, preserving binary data integrity.
•Default Value: If P2 is omitted, an empty string is appended.
Schematic (Array Append)
Array[1]: ["Apple", "Banana"]
Command: ARR.Add Element|1|Orange
Result: Array[1]: ["Apple", "Banana", "Orange"]
Syntax
ARR.Add Element|P1[|P2]
ARR.Add|P1[|P2]
Parameter Explanation
•P1 - Array Number: Specifies the array number, which can range from 0 to 32.
•P2 - Element Value (Optional): Specifies the value to append to the array. Can be a string or binary string. If omitted, an empty string is appended.
Examples
'***********************************
' Example 1: Add a string element to an array
'***********************************
ARR.Set|1|0|Apple
ARR.Add Element|1|Banana
' Array 1 now contains: ["Apple", "Banana"]
ARR.Get|1|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Add an empty string to an array
'***********************************
ARR.Set|2|0|Orange
ARR.Add Element|2
' Array 2 now contains: ["Orange", ""]
ARR.Get|2|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Add a binary string to an array
'***********************************
VAR.$$BIN=Binary\x00Data
ARR.Add Element|3|$$BIN
' Array 3 now contains: ["Binary\x00Data"]
ARR.Get|3|0|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Add Element
' Purpose: Verify functionality with JIV. for automated checks.
' Tests adding elements, empty strings, binary data, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Add a string element
STS.CLEAR
ARR.Clr|1
ARR.Add Element|1|Apple
ARR.Get|1|0|$$RET
$$EXP=Apple
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Add an empty string
STS.CLEAR
ARR.Clr|2
ARR.Add Element|2
ARR.Get|2|0|$$RET
$$EXP=
JIV.$$RET!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT. Test 1.3: Add a binary string
STS.CLEAR
ARR.Clr|3
VAR.$$BIN=Binary\x00Data
ARR.Add Element|3|$$BIN
ARR.Get|3|0|$$RET
$$EXP=Binary\x00Data
JIV.$$RET!$$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
ARR.Add Element|-1|Test
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.Add Element
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. ===================================================
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 automatically resizes the array if necessary, similar to the auto-dimensioning behavior of ARR.Set Array.
- Binary-safe: The element value (P2) is resolved once using Vari_Bin, ensuring safe handling of binary data.
- Arrays can store mixed data types (e.g., strings, binary strings, or encoded integers), as all elements are stored as strings internally, similar to ARR.Set Array.
- The command modifies the array in-place and does not return a value.
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.
- The command requires 1 or 2 parameters; fewer or more parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also: