MiniRobotLanguage (MRL)
ARR.Add Element INT
Append a Large Integer Value to the End of an Integer Array
Add a large integer value to the end of a specified integer array, automatically resizing if necessary.
Intention
The ARR.Add Element INT command appends a mandatory large integer value (P2) to the end of a specified integer array (P1). The command automatically resizes the array to accommodate the new element, making it ideal for dynamically building arrays of numeric data in tasks like counters, indexing, or large integer calculations. The value is stored as a string internally, consistent with MRL’s array storage mechanism.
The command requires exactly two parameters: the array number and the integer value. 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.
•Numeric Validation: The value (P2) is resolved to an integer, ensuring proper numeric format.
•Mandatory Value: The integer value (P2) is required; omitting it results in no operation.
Schematic (Integer Array Append)
Array[1]: ["123", "456"]
Command: ARR.Add Element INT|1|789
Result: Array[1]: ["123", "456", "789"]
Syntax
ARR.Add Element INT|P1|P2
Parameter Explanation
•P1 - Array Number: Specifies the integer array number, which can range from 0 to 32.
•P2 - Integer Value: Specifies the large integer value to append to the array. Must be a valid numeric string (e.g., "123", "-456").
Examples
'***********************************
' Example 1: Add a positive integer value to an array
'***********************************
ARR.Set INT|1|0|123
ARR.Add Element INT|1|456
' Array 1 now contains: ["123", "456"]
ARR.Get|1|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Add a negative integer value
'***********************************
ARR.Set INT|2|0|0
ARR.Add Element INT|2|-789
' Array 2 now contains: ["0", "-789"]
ARR.Get|2|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Add a zero value
'***********************************
ARR.Add Element INT|3|0
' Array 3 now contains: ["0"]
ARR.Get|3|0|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Add Element INT
' Purpose: Verify functionality with JIV. for automated checks.
' Tests adding integer values, negative values, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Add a positive integer value
STS.CLEAR
ARR.Clr|1
ARR.Add Element INT|1|123
ARR.Get|1|0|$$RET
$$EXP=123
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Add a negative integer value
STS.CLEAR
ARR.Clr|2
ARR.Add Element INT|2|-456
ARR.Get|2|0|$$RET
$$EXP=-456
JIV.$$RET!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT. Test 1.3: Add a zero value
STS.CLEAR
ARR.Clr|3
ARR.Add Element INT|3|0
ARR.Get|3|0|$$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 array number (negative)
STS.CLEAR
ARR.Clr|4
ARR.Add Element INT|-1|123
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 INT|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: Invalid integer value (non-numeric)
STS.CLEAR
ARR.Clr|6
ARR.Add Element INT|6|Invalid
ARR.Get|6|0|$$RET
$$EXP=
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 if necessary, similar to the auto-dimensioning behavior of ARR.Set INT.
- Integer values are stored as strings internally, consistent with MRL’s array storage mechanism, allowing retrieval as numeric strings.
- The command modifies the array in-place and does not return a value.
- Invalid integer values (e.g., non-numeric strings) may result in no operation or default to 0, depending on implementation.
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 exactly two parameters; fewer or more parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
- Non-numeric values for P2 may result in no operation or undefined behavior.
See also: