|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > !ARM. - Multidimensional Dynamic Arrays > Array Management > ARM. - Array Operations |
MiniRobotLanguage (MRL)
ARM.Redim
Redimensions an existing two-dimensional array, adjusting its size (rows and columns).
Intention
The ARM.Redim command redimensions an existing two-dimensional (2D) array, allowing developers to change its size by specifying new numbers of rows and columns. This is a vital command for dynamic resizing during runtime in MiniRobotLanguage, accommodating growing or shrinking datasets, such as expanding a game board (e.g., adding rows to a chessboard-like grid), resizing a pixel grid for image processing, or adjusting a matrix for mathematical calculations. 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.Redim enables flexibility for applications requiring adaptive data structures. Existing data may be preserved, truncated, or padded with default values (typically 0 or empty strings) depending on the new dimensions, making it essential for simulations, real-time applications, or data management tasks where array size fluctuates.
Illustration:
🔄 2D Array Resizing: A chessboard-like grid with handle $$ARR, originally 3x3, is resized to 5x4, potentially truncating or padding cells (e.g., [King, Queen; ...] becomes a larger or smaller grid).
🔑 Handle: $$ARR remains valid but reflects the new dimensions.
Syntax
ARM.Redim|$$ARR|$$ROW|$$COL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to be redimensioned. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after resizing.
P2 - $$ROW - (Variable, 5 characters max)
The new number of rows for the 2D array. This must be a positive integer, determining the vertical size of the grid (e.g., 5 for a 5-row chessboard-like structure).
P3 - $$COL - (Variable, 5 characters max)
The new number of columns for the 2D array. This must be a positive integer, determining the horizontal size of the grid (e.g., 4 for a 4-column chessboard-like structure).
Examples
'***********************************
' ARM.Redim - Sample 1: Resizing a Game Board
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
DBP.2D Array (chessboard-like) before resizing: [King, Queen; ...] (3x3)
SET|$$ROW|5
SET|$$COL|4
ARM.Redim|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [King, Queen, 0, 0; ...] (5x4, padded with 0)
ARM.End|$$ARR
'
'***********************************
' ARM.Redim - Sample 2: Resizing an Image Pixel Grid
'***********************************
ARM.New|$$ARR|f
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
DBP.2D Array (pixel grid) before resizing: [1.5, -2.7; ...] (2x2)
SET|$$ROW|4
SET|$$COL|3
ARM.Redim|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [1.5, -2.7, 0.0; ...] (4x3, padded with 0.0)
ARM.End|$$ARR
'
'***********************************
' ARM.Redim - Sample 3: Resizing a Matrix
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
DBP.2D Array (matrix) before resizing: [100, 200; ...] (2x2)
SET|$$ROW|3
SET|$$COL|3
ARM.Redim|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [100, 200, 0; ...] (3x3, padded with 0)
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.Redim.
- Existing data in the 2D array may be preserved, truncated, or padded with default values (0 for integers/floating-point, empty string for strings) based on the new dimensions. Use ARM.GetDims to check current dimensions before resizing to avoid unexpected data loss.
- The performance of resizing a 2D array in MRL, due to its emulation within a one-dimensional structure, may introduce minor overhead, but this is typically negligible for most use cases, such as resizing small game boards or pixel grids. For very large arrays, consider minimizing resize operations to optimize performance.
- This command is particularly useful in dynamic applications like games (e.g., expanding a level map), image processing (e.g., scaling an image), or scientific computing (e.g., adjusting matrix dimensions for new calculations).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to redimension an invalid handle may cause runtime errors.
- Rows ($$ROW) and columns ($$COL) must be positive integers; negative or zero values will result in errors or undefined behavior.
- Resizing very large 2D arrays frequently may impact performance due to the emulation in MRL, though this is typically minor for most practical applications like game boards or small matrices.
- Data outside the new dimensions may be lost irreversibly; ensure the new dimensions meet application needs before resizing.
See also:
• ARM.New
• ARM.End