MiniRobotLanguage (MRL)
ARR.Clr Array
Clear Array Content and Retain Dimensions
Clear all elements in a specified array, setting them to empty strings while retaining the array’s dimensions.
Intention
The ARR.Clr Array command clears all elements in a specified array (P1), setting them to empty strings while preserving the array’s dimensions. This command is useful for resetting an array’s content to an initial state without reallocating memory, allowing subsequent operations to reuse the existing structure.
The command requires exactly one parameter: the array number. It modifies the array in-place, setting all elements to empty strings, 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: Sets all elements in the specified array (P1) to empty strings.
•Dimension Retention: Retains the array’s dimensions, keeping the allocated memory structure intact.
•Status Code: Returns 1 for success or 0 for failure via SL_27.
Schematic (Array Clearing)
Array[1]: ["Apple", "Banana", "Orange"]
Command: ARR.Clr Array|1
Result: Array[1]: ["", "", ""]
Syntax
ARR.Clr Array|P1
ARR.CLR|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.Dim Array|1|3
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Clr Array|1
' Array 1 now contains: ["", "", ""]
ARR.Get|1|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Clear an integer array
'***********************************
ARR.Dim Array|2|2
ARR.Set INT|2|0|123
ARR.Set INT|2|1|456
ARR.Clr Array|2
' Array 2 now contains: ["", ""]
ARR.Get|2|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Clear an empty array
'***********************************
ARR.Dim Array|3|0
ARR.Clr Array|3
' Array 3 now contains: []
ARR.Get|3|0|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Clr 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.Dim Array|1|3
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Clr 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.Dim Array|2|0
ARR.Clr 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.Dim Array|3|2
ARR.Set|3|0|Test
ARR.Clr 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.Dim Array|4|2
ARR.Set|4|0|Test
ARR.Clr 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 to empty strings, retaining the array’s dimensions, in contrast to ARR.Clm Array, which also frees 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.
- If the array number is invalid, no error is shown, but the timeout flag may be set, and the operation has no effect.
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