|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > !ARM. - Multidimensional Dynamic Arrays > Array Operations > ARM. - Array Operations |
MiniRobotLanguage (MRL)
ARM.Swap
Swaps the values at two specified positions (row, column) in a two-dimensional array.
Intention
The ARM.Swap command exchanges the values at two specified positions (row, column) within a two-dimensional (2D) array, allowing developers to rearrange data for tasks like reordering game pieces on a board (e.g., swapping a king and queen on a chessboard-like grid), adjusting pixel values in an image grid, or reorganizing matrix elements for scientific computations. 2D arrays, visualized as a grid like a chessboard with rows and columns (e.g., [1,1] to [8,8]), are emulated within a one-dimensional structure in MRL, and ARM.Swap provides precise control over individual cell exchanges, preserving the array’s handle, dimensions, and data type (strings, integers, or floating-point numbers). It’s particularly useful in applications requiring specific data repositioning, such as games, image editing, or data manipulation, where swapping values enhances gameplay, adjusts visuals, or optimizes calculations. The operation swaps the values at the two specified positions, leaving other elements unchanged, as demonstrated in the examples.
Illustration:
🔄 2D Array Swapping: A chessboard-like grid with handle $$ARR, originally [A1, A2; B1, B2] (2x2), has values at [1,1] (A1) and [2,2] (B2) swapped, resulting in [B2, A2; B1, A1].
🔑 Handle: $$ARR remains valid, with only the specified positions swapped.
Syntax
ARM.Swap|$$ARR|$$R1|$$C1|$$R2|$$C2
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array where the swap will occur. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$R1 - (Variable, 5 characters max)
The row index of the first position to swap. This must be a positive integer within the array’s row bounds (e.g., 1 to the number of rows, as retrieved by ARM.Count or ARM.GetDims), representing the vertical position in the grid (e.g., row 1 on a chessboard).
P3 - $$C1 - (Variable, 5 characters max)
The column index of the first position to swap. This must be a positive integer within the array’s column bounds (e.g., 1 to the number of columns, as retrieved by ARM.Count or ARM.GetDims), representing the horizontal position in the grid (e.g., column 1 on a chessboard).
P4 - $$R2 - (Variable, 5 characters max)
The row index of the second position to swap. This must be a positive integer within the array’s row bounds, matching the format of $$R1, representing the vertical position of the second swap target (e.g., row 2 on a chessboard).
P5 - $$C2 - (Variable, 5 characters max)
The column index of the second position to swap. This must be a positive integer within the array’s column bounds, matching the format of $$C1, representing the horizontal position of the second swap target (e.g., column 2 on a chessboard).
Examples
'--------------------------------------------------------
' ARM.Swap - Sample 1: Swapping Values in a String Array (Game Board)
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
' Set values
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|2|1|B1
ARM.Set|$$ARR|2|2|B2
DBP.2D Array (chessboard-like) before swapping: [A1, A2; B1, B2] (2x2)
' Swap values at (1,1) and (2,2)
SET|$$R1|1
SET|$$C1|1
SET|$$R2|2
SET|$$C2|2
ARM.Swap|$$ARR|$$R1|$$C1|$$R2|$$C2
DBP.2D Array after swapping: [B2, A2; B1, A1] (2x2)
' Check values
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!B2|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!A1|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!A2|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!B1|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Swap - Sample 2: Swapping Values in a Numeric Array (Matrix)
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|2|3
' Set values
ARM.Set|$$ARR|1|1|1
ARM.Set|$$ARR|1|2|2
ARM.Set|$$ARR|1|3|3
ARM.Set|$$ARR|2|1|4
ARM.Set|$$ARR|2|2|5
ARM.Set|$$ARR|2|3|6
DBP.2D Array (matrix) before swapping: [1, 2, 3; 4, 5, 6] (2x3)
' Swap values at (1,1) and (2,3)
SET|$$R1|1
SET|$$C1|1
SET|$$R2|2
SET|$$C2|3
ARM.Swap|$$ARR|$$R1|$$C1|$$R2|$$C2
DBP.2D Array after swapping: [6, 2, 3; 4, 5, 1] (2x3)
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Swap - Sample 3: Swapping Values in a Floating-Point Array (Pixel Grid)
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|3|2
' Set values
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.Set|$$ARR|2|1|3.14
ARM.Set|$$ARR|2|2|0.5
ARM.Set|$$ARR|3|1|-1.8
ARM.Set|$$ARR|3|2|4.2
DBP.2D Array (pixel grid) before swapping: [1.5, -2.7; 3.14, 0.5; -1.8, 4.2] (3x2)
' Swap values at (1,1) and (3,2)
SET|$$R1|1
SET|$$C1|1
SET|$$R2|3
SET|$$C2|2
ARM.Swap|$$ARR|$$R1|$$C1|$$R2|$$C2
DBP.2D Array after swapping: [4.2, -2.7; 3.14, 0.5; -1.8, 1.5] (3x2)
ARM.End|$$ARR
'
Remarks
- The array handle must be stored in a variable with a maximum length of 5 characters (e.g., $$ARR, $$TMP) and must be valid (created by ARM.New) before using ARM.Swap. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims or ARM.Count to verify row and column bounds to avoid index errors.
- The row and column indices ($$R1, $$C1, $$R2, $$C2) must be within the array’s current dimensions; out-of-bounds indices will result in errors. Ensure indices are positive integers starting from 1, matching the grid structure (e.g., 1 to 8 for a chessboard), as shown in the examples with verification using ARM.Get.
- Swapping preserves the array’s data type (strings, integers, or floating-point) and dimensions but only exchanges the values at the specified positions, leaving other elements unchanged. This operation is efficient for small-scale rearrangements but can be repeated for complex reordering, as demonstrated in the examples.
- The performance of swapping values in a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally fast with minimal overhead. However, for very large arrays or frequent swaps, performance may scale linearly with array size, though this is typically negligible for most practical use cases, such as swapping game pieces or pixel values.
- This command is ideal for data rearrangement in applications like games (swapping board positions), image processing (adjusting pixel values), or scientific computing (reordering matrix elements for optimization).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to swap in an invalid handle may cause runtime errors.
- The row and column indices ($$R1, $$C1, $$R2, $$C2) must be within bounds, as determined by ARM.Count or ARM.GetDims; out-of-bounds indices will result in errors or undefined behavior.
- Swapping very large 2D arrays frequently may introduce minor performance overhead due to the emulation in MRL, but this is typically insignificant for most applications like game boards or small matrices.
- The command assumes the handle refers to a 2D array; using it on other data types or structures may lead to undefined behavior or errors.
See also:
• ARM.New
• ARM.Set
• ARM.Get