MiniRobotLanguage (MRL)
ARR.Insert
Insert an Element at a Specified Index in an Array
Insert a string value at a specified index in an array, shifting existing elements and resizing if necessary.
Intention
The ARR.Insert command inserts a string value (P3, optional) at a specified index (P2) in a specified array (P1). If P3 is omitted, an empty string is inserted. The command shifts existing elements at and after the specified index to the right and automatically resizes the array to accommodate the new element. It is ideal for dynamically modifying arrays, such as inserting data into sorted lists or updating array contents at specific positions.
The command returns a status code (1 for success, 0 for failure) and modifies the array in-place. It is designed for string arrays, with values stored as strings internally, consistent with MRL’s array storage mechanism.
•Auto-Dim: The array is automatically resized to accommodate the inserted element.
•Index Validation: The index (P2) is 0-based; invalid indices (e.g., negative or beyond array size) result in failure.
•Default Value: If P3 is omitted, an empty string is inserted.
Schematic (Array Insertion)
Array[1]: ["Apple", "Orange"]
Command: ARR.Insert|1|1|Banana
Result: Array[1]: ["Apple", "Banana", "Orange"]
Syntax
ARR.Insert|P1|P2[|P3]
Parameter Explanation
•P1 - Array Number: Specifies the array number, which can range from 0 to 32.
•P2 - Index: Specifies the 0-based index where the element will be inserted. Must be a valid non-negative integer.
•P3 - Value (Optional): Specifies the string value to insert. If omitted, an empty string is inserted.
Examples
'***********************************
' Example 1: Insert a string at index 1
'***********************************
ARR.Set|1|0|Apple
ARR.Set|1|1|Orange
ARR.Insert|1|1|Banana
' Array 1 now contains: ["Apple", "Banana", "Orange"]
ARR.Get|1|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Insert an empty string at index 0
'***********************************
ARR.Set|2|0|Orange
ARR.Insert|2|0
' Array 2 now contains: ["", "Orange"]
ARR.Get|2|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Insert at the end of an array
'***********************************
ARR.Set|3|0|Apple
ARR.Insert|3|1|Mango
' Array 3 now contains: ["Apple", "Mango"]
ARR.Get|3|1|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Insert
' Purpose: Verify functionality with JIV. for automated checks.
' Tests inserting elements, empty strings, invalid indices, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Insert a string at index 1
STS.CLEAR
ARR.Clr|1
ARR.Set|1|0|Apple
ARR.Set|1|1|Orange
ARR.Insert|1|1|Banana
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: Insert an empty string at index 0
STS.CLEAR
ARR.Clr|2
ARR.Set|2|0|Orange
ARR.Insert|2|0
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: Insert at end of array
STS.CLEAR
ARR.Clr|3
ARR.Set|3|0|Apple
ARR.Insert|3|1|Mango
ARR.Get|3|1|$$RET
$$EXP=Mango
JIV.$$RET!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
PRT. Test 1.4: Invalid index (negative)
STS.CLEAR
ARR.Clr|4
ARR.Set|4|0|Test
ARR.Insert|4|-1|Invalid
ARR.Get|4|0|$$RET
$$EXP=Test
JIV.$$RET!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'-----------------------------------------------------------
:Lab_Next4
PRT. Test 1.5: Invalid array number (negative)
STS.CLEAR
ARR.Clr|5
ARR.Set|5|0|Test
ARR.Insert|-1|0|Invalid
ARR.Get|5|0|$$RET
$$EXP=Test
JIV.$$RET!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'-----------------------------------------------------------
:Lab_Next5
PRT. Test 1.6: Invalid parameter count (too few)
STS.CLEAR
ARR.Clr|6
ARR.Set|6|0|Test
ARR.Insert|6
ARR.Get|6|0|$$RET
$$EXP=Test
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 automatically resizes the array and shifts elements to accommodate the insertion, similar to ARR.Set Array.
- Values are stored as strings internally, consistent with MRL’s array storage mechanism, allowing retrieval as strings.
- The command returns a status code (1 for success, 0 for failure) via SL_27, indicating whether the insertion was successful.
- Invalid indices or array numbers result in no operation and a status code of 0.
Limitations
- Array numbers are limited to 0–32, consistent with other MRL array commands.
- Invalid array numbers (e.g., negative or >32) or invalid indices (e.g., negative or beyond array size) result in no operation.
- The command requires 2 or 3 parameters; fewer or more parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also: