MiniRobotLanguage (MRL)
ARR.Get Dim
Return the Highest Used Array Index (Number of Elements - 1)
Retrieve the highest used index of a specified array, which is the number of elements minus one due to 0-based indexing.
Intention
The ARR.Get Dim command retrieves the highest used index of a specified array (P1), which is the number of elements minus one due to 0-based indexing. The result is stored in an optional output variable (P2) or returned via the system variable SL_27. This command is useful for determining the size of an array for iteration, validation, or dynamic processing.
The command requires at least one parameter (array number) and optionally a second parameter (output variable). It works with any array type (string, integer, or floating-point), as all arrays are stored as strings internally in MRL.
•0-Based Indexing: The returned index is the number of elements minus one (e.g., 4 for an array with 5 elements).
•Output Flexibility: The result can be stored in a variable (P2) or retrieved via SL_27.
•Status Code: Returns 1 for success or 0 for failure via SL_27 when P2 is omitted.
Schematic (Get Array Dimension)
Array[1]: ["Apple", "Banana", "Orange"]
Command: ARR.Get Dim|1|$$RET
Result: $$RET = 2
Syntax
ARR.Get Dim|P1[|P2]
Parameter Explanation
•P1 - Array Number: Specifies the array number, which can range from 0 to 32.
•P2 - Output Variable (Optional): Specifies the variable to store the highest used index. If omitted, the result is returned via SL_27.
Examples
'***********************************
' Example 1: Get dimension of a string array
'***********************************
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Set|1|2|Orange
ARR.Get Dim|1|$$RET
' $$RET now contains: 2
MBX.Array Dimension: $$RET
ENR.
'***********************************
' Example 2: Get dimension of an empty array
'***********************************
ARR.Clr|2
ARR.Get Dim|2|$$RET
' $$RET now contains: -1 or 0 (depending on implementation)
MBX.Array Dimension: $$RET
ENR.
'***********************************
' Example 3: Get dimension without output variable
'***********************************
$$TST=Hallo;wie;geht
ARR.Unpack Array From Var Delimiter|3|;|$$TST
ARR.Get Dim|3
' Result stored in SL_27: 2
VAR.$$RET=$SL_27
MBX.Array Dimension: $$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Get Dim
' Purpose: Verify functionality with JIV. for automated checks.
' Tests getting dimensions for arrays, empty arrays, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Get dimension of a string array
STS.CLEAR
ARR.Clr|1
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Get Dim|1|$$RET
$$EXP=1
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Get dimension of an empty array
STS.CLEAR
ARR.Clr|2
ARR.Get Dim|2|$$RET
$$EXP=-1
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.Get Dim|99|$$RET
$$EXP=0
JIV.$$RET!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
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 returns the highest used index, which is the number of elements minus one due to 0-based indexing.
- Works with any array type (string, integer, or floating-point) due to MRL’s internal string storage.
- If P2 is omitted, the result is returned via SL_27, which also indicates success (1) or failure (0).
- For empty arrays, the command typically returns -1 or 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 and a status code of 0.
- The command requires at least one parameter; fewer or more than two parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also:
• Unpack Array from Var Delimiter