|
<< 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.Rotate
Rotates a two-dimensional array 90 degrees clockwise, changing its dimensions and rearranging its elements.
Intention
The ARM.Rotate command rotates a two-dimensional (2D) array 90 degrees clockwise, transforming its dimensions (e.g., from rows × columns to columns × rows) and rearranging its elements accordingly. This is a key command for data transformation in MiniRobotLanguage, enabling developers to reorient grids for tasks like rotating a game board (e.g., turning a chessboard-like grid for a new perspective), adjusting pixel grids in image processing, or reorienting matrices 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.Rotate preserves the array’s handle, data type (strings, integers, or floating-point numbers), and element values but changes the dimensions and layout. It’s particularly useful in applications requiring visual or logical rotation, such as games, graphics programming, or data visualization, where a 90-degree clockwise turn enhances gameplay, adjusts visuals, or aligns data for analysis. The operation transposes the array, swapping rows and columns while rotating elements, as demonstrated in the examples.
Illustration:
↻ 2D Array Rotation: A chessboard-like grid with handle $$ARF, originally 2x3 [1.1, 1.2, 1.3; 2.1, 2.2, 2.3], is rotated 90 degrees clockwise to 3x2 [2.1, 1.1; 2.2, 1.2; 2.3, 1.3].
Difference from ARM.Transpose
While ARM.Rotate rotates the array 90 degrees clockwise, changing both the dimensions and the arrangement of elements (e.g., a 2x3 array becomes 3x2 with a specific clockwise rotation), ARM.Transpose simply swaps rows and columns without rotation, maintaining the same element positions relative to the new orientation but flipping the dimensions (e.g., a 2x3 array becomes 3x2 with elements mirrored across the main diagonal). Specifically:
- ARM.Rotate performs a 90-degree clockwise rotation, moving elements to new positions based on the rotation (e.g., [r,c] → [c, rows-r+1]).
- ARM.Transpose performs a matrix transposition, where [r,c] becomes [c,r], essentially flipping the array over its main diagonal without rotation.
For example, starting with a 2x3 array [1, 2, 3; 4, 5, 6]:
- ARM.Rotate results in [4, 1; 5, 2; 6, 3] (3x2, 90-degree clockwise rotation).
- ARM.Transpose results in [1, 4; 2, 5; 3, 6] (3x2, simple row-column swap).
Illustration for ARM.Transpose:
↔️ 2D Array Transposition: A chessboard-like grid with handle $$ARF, originally 2x3 [1.1, 1.2, 1.3; 2.1, 2.2, 2.3], is transposed to 3x2 [1.1, 2.1; 1.2, 2.2; 1.3, 2.3], swapping rows and columns without rotation.
Syntax
ARM.Rotate|$$ARR
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to rotate. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation, with its dimensions transposed (rows become columns, columns become rows) and elements rotated 90 degrees clockwise.
Examples
'--------------------------------------------------------
' ARM.Rotate - Sample 1: Rotating a Floating-Point Array (2x3 to 3x2) for Extended Arrays
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|3
' Set values
ARM.Set|$$ARF|1|1|1.1
ARM.Set|$$ARF|1|2|1.2
ARM.Set|$$ARF|1|3|1.3
ARM.Set|$$ARF|2|1|2.1
ARM.Set|$$ARF|2|2|2.2
ARM.Set|$$ARF|2|3|2.3
ARM.Rotate|$$ARF
ARM.Count|$$ARF|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARF|2|$$COL
JIV.$$COL!2|Lab_failed
ARM.Get|$$ARF|1|1|$$VAL
JIV.$$VAL!2.1|Lab_failed
ARM.Get|$$ARF|1|2|$$VAL
JIV.$$VAL!1.1|Lab_failed
ARM.Get|$$ARF|2|1|$$VAL
JIV.$$VAL!2.2|Lab_failed
ARM.Get|$$ARF|2|2|$$VAL
JIV.$$VAL!1.2|Lab_failed
ARM.Get|$$ARF|3|1|$$VAL
JIV.$$VAL!2.3|Lab_failed
ARM.Get|$$ARF|3|2|$$VAL
JIV.$$VAL!1.3|Lab_failed
ARM.End|$$ARF
'
'--------------------------------------------------------
' ARM.Rotate - Sample 2: Rotating a Floating-Point Array (1x2 to 2x1) for Extended Arrays
ARM.New|$$ARF|f
ARM.Redim|$$ARF|1|2
' Set values
ARM.Set|$$ARF|1|1|1.1
ARM.Set|$$ARF|1|2|1.2
ARM.Rotate|$$ARF
ARM.Count|$$ARF|1|$$ROW
JIV.$$ROW!2|Lab_failed
ARM.Count|$$ARF|2|$$COL
JIV.$$COL!1|Lab_failed
ARM.Get|$$ARF|1|1|$$VAL
JIV.$$VAL!1.1|Lab_failed
ARM.Get|$$ARF|2|1|$$VAL
JIV.$$VAL!1.2|Lab_failed
ARM.End|$$ARF
'
'--------------------------------------------------------
' ARM.Rotate - Sample 3: Rotating an Integer Array (Game Board) for Symmetry
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
' Set values
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|2|1|3
ARM.Set|$$ARI|2|2|4
ARM.Rotate|$$ARI
ARM.Count|$$ARI|1|$$ROW
JIV.$$ROW!2|Lab_failed
ARM.Count|$$ARI|2|$$COL
JIV.$$COL!2|Lab_failed
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!3|Lab_failed
ARM.Get|$$ARI|1|2|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.Get|$$ARI|2|1|$$VAL
JIV.$$VAL!4|Lab_failed
ARM.Get|$$ARI|2|2|$$VAL
JIV.$$VAL!2|Lab_failed
ARM.End|$$ARI
'
Remarks
- The array handle must be stored in a variable with a maximum length of 5 characters (e.g., $$ARF, $$ARI) and must be valid (created by ARM.New) before using ARM.Rotate. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to verify dimensions before and after rotation.
- Rotation is a 90-degree clockwise turn, transposing the array’s dimensions (e.g., a 2x3 array becomes 3x2) and rearranging elements. This preserves the array’s data type (strings, integers, or floating-point) but changes the layout, as shown in the examples with verification using ARM.Count and ARM.Get. In contrast, ARM.Transpose performs a simple row-column swap without rotation, maintaining element positions relative to the new orientation but flipping the dimensions, as illustrated earlier.
- The performance of rotating 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 and transposing dimensions. Similarly, ARM.Transpose may have comparable overhead for large arrays, but both are typically acceptable for most practical use cases, such as rotating game boards, pixel grids, or matrices. For very large arrays, minimize rotations or transpositions and optimize data handling if performance is critical.
- This command is ideal for data transformation in applications like games (rotating boards for new perspectives), image processing (rotating images for visual effects), or scientific computing (reorienting matrices for analysis or visualization), while ARM.Transpose is better suited for matrix operations requiring a simple row-column swap without rotation.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to rotate an invalid handle may cause runtime errors.
- Rotation changes the array’s dimensions, so ensure subsequent operations account for the new structure (e.g., using ARM.Count or ARM.GetDims), as shown in the examples. The same applies to ARM.Transpose, but it does not involve rotation, only dimension flipping.
- Rotating or 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 these operations 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, similar to ARM.Transpose.
See also:
• ARM.New