MiniRobotLanguage (MRL)
ARR.Insert INT
Insert a Large Integer Value at a Specified Index in an Integer Array
Insert a large integer value at a specified index in an integer array, shifting existing elements and resizing if necessary.
Intention
The ARR.Insert INT command inserts a mandatory large integer value (P3) at a specified index (P2) in a specified integer array (P1). 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 integer arrays, such as inserting values into sorted lists or updating array contents at specific positions for tasks like indexing or counters.
The command requires exactly three parameters: the array number, index, and integer value. The array is modified in-place, and a status code (1 for success, 0 for failure) is returned. Values are stored as strings internally, consistent with MRL’s array storage mechanism.
•Auto-Dim: The array is automatically resized to accommodate the inserted element.
•Numeric Validation: The value (P3) is resolved to an integer, ensuring proper numeric format.
•Mandatory Value: The integer value (P3) is required; omitting it results in no operation.
Schematic (Integer Array Insertion)
Array[1]: ["123", "456"]
Command: ARR.Insert INT|1|1|789
Result: Array[1]: ["123", "789", "456"]
Syntax
ARR.Insert INT|P1|P2|P3
Parameter Explanation
•P1 - Array Number: Specifies the integer array number, which can range from 0 to 32.
•P2 - Index: Specifies the 0-based index where the integer value will be inserted. Must be a valid non-negative integer.
•P3 - Integer Value: Specifies the large integer value to insert. Must be a valid numeric string (e.g., "123", "-456").
Examples
'***********************************
' Example 1: Insert a positive integer at index 1
'***********************************
ARR.Set INT|1|0|123
ARR.Set INT|1|1|456
ARR.Insert INT|1|1|789
' Array 1 now contains: ["123", "789", "456"]
ARR.Get|1|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Insert a negative integer at index 0
'***********************************
ARR.Set INT|2|0|0
ARR.Insert INT|2|0|-789
' Array 2 now contains: ["-789", "0"]
ARR.Get|2|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Insert a zero value at end of array
'***********************************
ARR.Set INT|3|0|123
ARR.Insert INT|3|1|0
' Array 3 now contains: ["123", "0"]
ARR.Get|3|1|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Insert INT
' Purpose: Verify functionality with JIV. for automated checks.
' Tests inserting integer values, negative values, invalid indices, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Insert a positive integer at index 1
STS.CLEAR
ARR.Clm|1
ARR.Sin|1|0|123
ARR.Set INT Array|1|1|456
ARR.Insert INT|1|1|789
'ARR.ShowInt|1
ARR.Get INT Array|1|1|$$RET
$$EXP=789
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Insert a negative integer at index 0
STS.CLEAR
ARR.Clr|2
ARR.Set INT Array|2|0|0
ARR.Insert INT|2|0|-789
ARR.Get INT Array|2|0|$$RET
$$EXP=-789
JIV.$$RET!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT. Test 1.3: Insert a zero value at end of array
STS.CLEAR
ARR.Clr|3
ARR.Set INT Array|3|0|123
ARR.Insert INT|3|1|0
ARR.Get INT Array|3|1|$$RET
$$EXP=0
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 INT Array|4|0|123
ARR.Insert INT|4|-1|456
ARR.Get INT Array|4|0|$$RET
$$EXP=123
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 INT Array|5|0|123
ARR.Insert INT|-1|0|456
ARR.Get INT Array|5|0|$$RET
$$EXP=123
JIV.$$RET!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'-----------------------------------------------------------
:Lab_Next5
PRT. Test 1.6: Invalid integer value (non-numeric)
ARR.Clr|6
ARR.Set INT Array|6|0|123
ARR.Insert INT|6|0|Invalid
ARR.Show Int|6
MBX.!
ARR.Get INT Array|6|0|$$RET
$$EXP=0
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 INT.
- Integer values are stored as strings internally, consistent with MRL’s array storage mechanism, allowing retrieval as numeric strings.
- The command returns a status code (1 for success, 0 for failure) via SL_27, indicating whether the insertion was successful.
- Invalid indices, array numbers, or non-numeric values 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 exactly three parameters; fewer or more parameters result in no operation.
- Non-numeric values for P3 may result in no operation or default to 0, depending on implementation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also: