MiniRobotLanguage (MRL)
ARR.Clm Array
Clear Array and Free Memory Used by the Array
Clear all elements in a specified array and free its reserved memory, resetting it to an empty state.
Intention
The ARR.Clm Array command clears all elements in a specified array (P1) and frees its reserved memory, effectively resetting the array to an empty state. This command is useful for memory management in long-running scripts or when an array is no longer needed, ensuring efficient resource usage.
The command requires exactly one parameter: the array number. It modifies the array in-place, removing all elements and releasing allocated memory, and returns a status code (1 for success, 0 for failure). The operation works with any array type (string, integer, or floating-point), as all arrays are stored as strings internally in MRL.
•Element Clearing: Removes all elements from the specified array (P1).
•Memory Release: Frees the reserved memory for the array, resetting its dimensions.
•Status Code: Returns 1 for success or 0 for failure via SL_27.
Schematic (Array Clearing)
Array[1]: ["Apple", "Banana", "Orange"]
Command: ARR.Clm Array|1
Result: Array[1]: []
Syntax
ARR.Clm Array|P1
ARR.CLM|P1
Parameter Explanation
•P1 - Array Number: Specifies the array number, which can range from 0 to 32.
Speed in Ticks:
This command typically uses between 90 to 200 ticks.
Examples
'***********************************
' Example 1: Clear a string array
'***********************************
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Clm Array|1
' Array 1 now contains: []
ARR.Get|1|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Clear an integer array
'***********************************
ARR.Set INT|2|0|123
ARR.Clm Array|2
' Array 2 now contains: []
ARR.Get|2|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Clear an empty array
'***********************************
ARR.Clr|3
ARR.Clm Array|3
' Array 3 now contains: []
ARR.Get|3|0|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Clm Array
' Purpose: Verify functionality with JIV. for automated checks.
' Tests clearing arrays, empty arrays, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Clear a string array
STS.CLEAR
ARR.Clr|1
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Clm Array|1
ARR.Get|1|0|$$RET
$$EXP=
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Clear an empty array
STS.CLEAR
ARR.Clr|2
ARR.Clm Array|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: Invalid array number (negative)
STS.CLEAR
ARR.Clr|3
ARR.Set|3|0|Test
ARR.Clm Array|-1
ARR.Get|3|0|$$RET
$$EXP=Test
JIV.$$RET!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
PRT. Test 1.4: Invalid parameter count (too few)
STS.CLEAR
ARR.Clr|4
ARR.Set|4|0|Test
ARR.Clm Array
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. ===================================================
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 clears all elements and frees memory, resetting the array to an empty state, in contrast to ARR.Clr Array, which may only clear elements without freeing memory.
- Works with any array type (string, integer, or floating-point) due to MRL’s internal string storage.
- Returns a status code (1 for success, 0 for failure) via SL_27, indicating whether the operation was successful.
- While memory cleanup occurs automatically at script termination, this command is useful for explicit memory management in long-running scripts.
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 and a status code of 0.
- The command requires exactly one parameter; fewer or more parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also:
• Insert
• Swap
• Delete