|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > Array -Commands > !FP-Arrays > Array - Commands |
MiniRobotLanguage (MRL)
ARR.Insert FP
Insert a Floating-Point Value at a Specified Index in a Floating-Point Array
Insert a floating-point value at a specified index in a floating-point array, shifting existing elements and resizing if necessary.
Intention
The ARR.Insert FP command inserts a mandatory floating-point value (P3) at a specified index (P2) in a specified floating-point array (P1). The command shifts existing elements at and after the specified index to the right and automatically resizes the array to accommodate the new element. It is ideal for dynamically modifying floating-point arrays, such as inserting values into sorted lists or updating array contents at specific positions for tasks like scientific calculations or data processing.
The command requires exactly three parameters: the array number, index, and floating-point value. The array is modified in-place, and a status code (1 for success, 0 for failure) is returned. Values are stored as strings internally, consistent with MRL’s array storage mechanism.
•Auto-Dim: The array is automatically resized to accommodate the inserted element.
•Numeric Validation: The value (P3) is resolved to a floating-point number, ensuring proper numeric format.
•Mandatory Value: The floating-point value (P3) is required; omitting it results in no operation.
Schematic (Floating-Point Array Insertion)
Array[1]: ["1.23", "4.56"]
Command: ARR.Insert FP|1|1|7.89
Result: Array[1]: ["1.23", "7.89", "4.56"]
Syntax
ARR.Insert FP|P1|P2|P3
Parameter Explanation
•P1 - Array Number: Specifies the floating-point array number, which can range from 0 to 32.
•P2 - Index: Specifies the 0-based index where the floating-point value will be inserted. Must be a valid non-negative integer.
•P3 - Floating-Point Value: Specifies the floating-point value to insert. Must be a valid numeric string (e.g., "1.23", "-4.56").
Speed in Ticks:
This command typically uses between 150 to 300 ticks, depending on the array size and the number of elements shifted.
Examples
'***********************************
' Example 1: Insert a positive floating-point value at index 1
'***********************************
ARR.Set FP|1|0|1.23
ARR.Set FP|1|1|4.56
ARR.Insert FP|1|1|7.89
' Array 1 now contains: ["1.23", "7.89", "4.56"]
ARR.Get|1|1|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Insert a negative floating-point value at index 0
'***********************************
ARR.Set FP|2|0|0.0
ARR.Insert FP|2|0|-7.89
' Array 2 now contains: ["-7.89", "0.0"]
ARR.Get|2|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Insert a zero value at end of array
'***********************************
ARR.Set FP|3|0|1.23
ARR.Insert FP|3|1|0.0
' Array 3 now contains: ["1.23", "0.0"]
ARR.Get|3|1|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Insert FP
' Purpose: Verify functionality with JIV. for automated checks.
' Tests inserting floating-point values, negative values, invalid indices, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Insert a positive floating-point value at index 1
STS.CLEAR
ARR.Clr|1
ARR.Set FP|1|0|1.23
ARR.Set FP|1|1|4.56
ARR.Insert FP|1|1|7.89
ARR.Get|1|1|$$RET
$$EXP=7.89
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Insert a negative floating-point value at index 0
STS.CLEAR
ARR.Clr|2
ARR.Set FP|2|0|0.0
ARR.Insert FP|2|0|-2.718
ARR.Get|2|0|$$RET
$$EXP=-2.718
JIV.$$RET!$$EXP|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT. Test 1.3: Insert a zero value at end of array
STS.CLEAR
ARR.Clr|3
ARR.Set FP|3|0|1.23
ARR.Insert FP|3|1|0.0
ARR.Get|3|1|$$RET
$$EXP=0.0
JIV.$$RET!$$EXP|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
PRT. Test 1.4: Invalid index (negative)
STS.CLEAR
ARR.Clr|4
ARR.Set FP|4|0|1.23
ARR.Insert FP|4|-1|4.56
ARR.Get|4|0|$$RET
$$EXP=1.23
JIV.$$RET!$$EXP|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'-----------------------------------------------------------
:Lab_Next4
PRT. Test 1.5: Invalid array number (negative)
STS.CLEAR
ARR.Clr|5
ARR.Set FP|5|0|1.23
ARR.Insert FP|-1|0|4.56
ARR.Get|5|0|$$RET
$$EXP=1.23
JIV.$$RET!$$EXP|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'-----------------------------------------------------------
:Lab_Next5
PRT. Test 1.6: Invalid floating-point value (non-numeric)
STS.CLEAR
ARR.Clr|6
ARR.Set FP|6|0|1.23
ARR.Insert FP|6|0|Invalid
ARR.Get|6|0|$$RET
$$EXP=1.23
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 and shifts elements to accommodate the insertion, similar to ARR.Set FP.
- Floating-point values are stored as strings internally, consistent with MRL’s array storage mechanism, allowing retrieval as numeric strings.
- The command returns a status code (1 for success, 0 for failure) via SL_27, indicating whether the insertion was successful.
- Invalid indices, array numbers, or non-numeric values result in no operation and a status code of 0.
Limitations
- Array numbers are limited to 0–32, consistent with other MRL array commands.
- Invalid array numbers (e.g., negative or >32) or invalid indices (e.g., negative or beyond array size) result in no operation.
- The command requires exactly three parameters; fewer or more parameters result in no operation.
- Non-numeric values for P3 may result in no operation or default to 0.0, depending on implementation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also:
• Insert
• Swap
• Delete