MiniRobotLanguage (MRL)
ARR.Get FP Array
Retrieves the value of a specific element in a specified floating-point array.
Retrieves a floating-point value from a specified array element.
Intention
The ARR.Get FP Array command is designed to retrieve the value of a specific element in a specified floating-point array.
This is useful for accessing stored numerical data within an array, particularly when high precision is required. The command retrieves the value at the specified index (P2) from the array (P1) and stores it in the output variable (P3) or places it on the Top Of Stack (TOS) if P3 is omitted.
•Element Retrieval: Retrieves the value of the element at the specified index (P2) in the specified array (P1).
•Data Types: The value retrieved is an extended-precision floating-point number, offering 18 digits of precision and requiring 10 bytes of storage.
•Result Placement: If P3 is omitted, the value is placed on the Top Of Stack (TOS).
•Auto Stop: If the specified index has not been set, the result will be 0.
Schematic (Floating-Point Array Retrieval)
Array[5]: ["3.14159", "2.71828", "-99.5"]
Command: ARR.Get FP Array|5|1|$$RES
Result: $$RES = "2.71828"
Syntax
ARR.Get FP Array|P1|P2[|P3]
ARR.GFP|P1|P2[|P3]
Parameter Explanation
•P1 - Array Number: Specifies the array number, which can range from 0 to 32.
•P2 - Array Index: Specifies the index of the element within the array to retrieve.
•P3 - Output Variable (Optional): Specifies the variable that will receive the value of the element at the given index. If omitted, the result is placed on the Top Of Stack (TOS).
Speed in Ticks:
Putting the Result on TOS is even a bit faster then using a Variable.
Examples
'***********************************
' Example 1: Retrieve a floating-point array element to a variable
'***********************************
ARR.Set FP|5|0|3.14159
ARR.Get FP Array|5|0|$$RES
MBX.$$RES
ENR.
'***********************************
' Example 2: Retrieve to TOS
'***********************************
ARR.Set FP|5|1|2.71828
ARR.Get FP Array|5|1
POP.$$RES
MBX.$$RES
ENR.
'***********************************
' Example 3: Retrieve from unset index
'***********************************
ARR.Clr|5
ARR.Get FP Array|5|10|$$RES
MBX.$$RES
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Get FP Array
' Purpose: Verify functionality with JIV. for automated checks.
' Tests retrieving elements, unset indices, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Retrieve a floating-point element
STS.CLEAR
ARR.Clr|1
ARR.Set FP|1|0|3.14
ARR.Get FP Array|1|0|$$RET
$$EXP=3.14
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Retrieve from unset index
STS.CLEAR
ARR.Clr|2
ARR.Get FP Array|2|0|$$RET
$$EXP=0
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.Get FP Array|-1|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 parameter count (too few)
STS.CLEAR
ARR.Clr|4
ARR.Get FP Array|4
POP.$$RET
$$EXP=0
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 retrieves values as strings, consistent with MRL’s internal array storage.
- Using the TOS for output is slightly faster than using a variable, as shown in the Speed in Ticks section.
- The command does not modify the source array.
- Invalid indices or array numbers return 0, ensuring safe operation.
Limitations
- Array numbers are limited to 0–32, consistent with other MRL array commands.
- Invalid array numbers (e.g., negative or >32) or indices result in a return value of 0.
- The command requires at least two parameters; fewer parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also:
• Insert
• Swap
• Delete