MiniRobotLanguage (MRL)
ARR.Swap
Swap the Contents of Two Arrays
Swap the entire contents of two specified arrays, exchanging all elements.
Intention
The ARR.Swap command exchanges the entire contents of two arrays identified by their array numbers (P1 and P2). All elements of the first array are transferred to the second array, and vice versa, preserving the structure and content of each array. This command is useful for tasks like reordering data, implementing sorting algorithms, or swapping temporary and primary data sets.
The command requires exactly two parameters: the numbers of the two arrays to swap. It modifies both arrays in-place and returns a status code (1 for success, 0 for failure). The swap operation works with any array type (string, integer, or floating-point), as all arrays are stored as strings internally in MRL.
•Array Validation: Both array numbers (P1 and P2) must be valid (0–32); invalid numbers result in failure.
•Complete Swap: The entire content of both arrays, including all elements, is swapped.
•Status Code: Returns 1 for success or 0 for failure via SL_27.
Schematic (Array Swap)
Array[1]: ["Apple", "Banana"]
Array[2]: ["Orange", "Mango"]
Command: ARR.Swap|1|2
Result: Array[1]: ["Orange", "Mango"]
Array[2]: ["Apple", "Banana"]
Syntax
ARR.Swap|P1|P2
Parameter Explanation
•P1 - First Array Number: Specifies the number of the first array to swap, ranging from 0 to 32.
•P2 - Second Array Number: Specifies the number of the second array to swap, ranging from 0 to 32.
Examples
'***********************************
' Example 1: Swap two string arrays
'***********************************
ARR.Set|1|0|Apple
ARR.Set|1|1|Banana
ARR.Set|2|0|Orange
ARR.Swap|1|2
' Array 1 now contains: ["Orange"]
' Array 2 now contains: ["Apple", "Banana"]
ARR.Get|1|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Swap an integer and floating-point array
'***********************************
ARR.Set INT|3|0|123
ARR.Set FP|4|0|1.23
ARR.Swap|3|4
' Array 3 now contains: ["1.23"]
' Array 4 now contains: ["123"]
ARR.Get|3|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Swap an array with an empty array
'***********************************
ARR.Set|5|0|Mango
ARR.Clr|6
ARR.Swap|5|6
' Array 5 now contains: []
' Array 6 now contains: ["Mango"]
ARR.Get|6|0|$$RET
MBX.$$RET
ENR.
'============================================================
' SELF-VALIDATING TEST SCRIPT for ARR.Swap
' Purpose: Verify functionality with JIV. for automated checks.
' Tests swapping arrays, identical array numbers, invalid array numbers, and invalid parameters.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Swap two string arrays
STS.CLEAR
ARR.Clr|1
ARR.Clr|2
ARR.Set|1|0|Apple
ARR.Set|2|0|Orange
ARR.Swap|1|2
ARR.Get|1|0|$$RET
$$EXP=Orange
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT. Test 1.2: Swap an array with itself
STS.CLEAR
ARR.Clr|3
ARR.Set|3|0|Mango
ARR.Swap|3|3
ARR.Get|3|0|$$RET
$$EXP=Mango
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|4
ARR.Set|4|0|Test
ARR.Swap|4|-1
ARR.Get|4|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|5
ARR.Set|5|0|Test
ARR.Swap|5
ARR.Get|5|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 swaps the entire contents of the specified arrays, preserving their structure and element count.
- Arrays are stored as strings internally, allowing swapping between different array types (e.g., string, integer, floating-point) without type restrictions.
- The command returns a status code (1 for success, 0 for failure) via SL_27, indicating whether the swap was successful.
- Swapping an array with itself has no effect but is considered a valid operation.
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 two parameters; fewer or more parameters result in no operation.
- No support for multidimensional arrays; use other commands for complex array structures.
See also: