|
<< 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.Transpose
Transposes a two-dimensional array, swapping its rows and columns.
Intention
The ARM.Transpose command transforms a two-dimensional (2D) array by swapping its rows and columns, effectively rotating the grid so that the original rows become columns and vice versa. This is a key command for data transformation in MiniRobotLanguage, enabling developers to reorient data for matrix operations (e.g., linear algebra), game board rotations (e.g., flipping a chessboard-like grid), or image processing (e.g., rotating pixel grids). 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.Transpose provides a straightforward way to restructure this grid, maintaining the array’s handle and data type (strings, integers, or floating-point numbers). It’s particularly useful in applications requiring data reorientation, such as scientific computing, graphics programming, or game mechanics, where a flipped or rotated grid is needed for analysis or display. The operation preserves all existing values but adjusts the dimensions (e.g., a 2x3 array becomes 3x2), as demonstrated in the examples.
Illustration:
↔️ 2D Array Transposition: A chessboard-like grid with handle $$ARR, originally 2x3 [A1, A2, A3; B1, B2, B3], is transposed to 3x2 [A1, B1; A2, B2; A3, B3].
🔑 Handle: $$ARR remains valid, with rows and columns swapped.
Syntax
ARM.Transpose|$$ARR
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to transpose. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation, with rows and columns swapped.
Examples
'--------------------------------------------------------
' ARM.Transpose - Sample 1: Transposing a String Array (Game Board)
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|3
' Set values
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|1|3|A3
ARM.Set|$$ARR|2|1|B1
ARM.Set|$$ARR|2|2|B2
ARM.Set|$$ARR|2|3|B3
DBP.2D Array (chessboard-like) before transposing: [A1, A2, A3; B1, B2, B3] (2x3)
ARM.Transpose|$$ARR
DBP.2D Array after transposing: [A1, B1; A2, B2; A3, B3] (3x2)
' Verify dimensions and values
ARM.Count|$$ARR|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARR|2|$$COL
JIV.$$COL!2|Lab_failed
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!A1|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!B1|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!A2|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!B2|Lab_failed
ARM.Get|$$ARR|3|1|$$VAL
JIV.$$VAL!A3|Lab_failed
ARM.Get|$$ARR|3|2|$$VAL
JIV.$$VAL!B3|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Transpose - Sample 2: Transposing 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 transposing: [1, 2, 3; 4, 5, 6] (2x3)
ARM.Transpose|$$ARR
DBP.2D Array after transposing: [1, 4; 2, 5; 3, 6] (3x2)
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Transpose - Sample 3: Transposing and Verifying with Resize (Image Pixel Grid)
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|2|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
DBP.2D Array (pixel grid) before transposing: [1.5, -2.7; 3.14, 0.5] (2x2)
ARM.Transpose|$$ARR
DBP.2D Array after transposing: [1.5, 3.14; -2.7, 0.5] (2x2)
ARM.Resize|$$ARR|3|3
' Verify dimensions and values
ARM.Count|$$ARR|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARR|2|$$COL
JIV.$$COL!3|Lab_failed
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!1.5|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!3.14|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!-2.7|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!0.5|Lab_failed
' New elements should be default (0.0 for floating-point)
ARM.Get|$$ARR|3|1|$$VAL
JIV.$$VAL!0.0|Lab_failed
ARM.Get|$$ARR|1|3|$$VAL
JIV.$$VAL!0.0|Lab_failed
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.Transpose. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to verify dimensions before and after transposing.
- Transposing swaps rows and columns, changing the array’s dimensions (e.g., a 2x3 array becomes 3x2). Ensure subsequent operations account for the new dimensions, as shown in the examples using ARM.Count and ARM.Get.
- The performance of transposing a 2D array in MRL, due to its emulation within a one-dimensional structure, may introduce moderate overhead, especially for large arrays, as it requires reorganizing all elements. However, this is typically acceptable for most practical use cases, such as small game boards, pixel grids, or matrices, though frequent transpositions in very large arrays should be minimized for performance optimization.
- This command is ideal for data transformation in applications like games (rotating boards), image processing (flipping or rotating images), or scientific computing (matrix operations like transposing for linear algebra).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to transpose an invalid handle may cause runtime errors.
- Transposing changes the array’s dimensions, which may require adjustments in subsequent operations. Ensure compatibility with other commands like ARM.Resize or ARM.GetDims, as shown in the examples.
- Transposing very large 2D arrays may impact performance due to the emulation and data reorganization in MRL, though this is typically manageable for most applications like game boards or small matrices. For large arrays, consider minimizing transpositions or optimizing data handling if performance is critical.
- 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