|
<< 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.Resize
Resizes a two-dimensional array to new dimensions, preserving existing data where possible and padding with default values.
Intention
The ARM.Resize command adjusts the dimensions (rows and columns) of an existing two-dimensional (2D) array to new values, maintaining existing data within the intersection of the old and new sizes and padding any new cells with default values (0 for integers/floating-point, empty string for strings). This is a key command for dynamic resizing in MiniRobotLanguage, enabling developers to grow or shrink a 2D array during runtime, such as expanding a game board (e.g., enlarging a chessboard-like grid), resizing a pixel grid for image processing, or adjusting a matrix for mathematical 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.Resize provides flexibility for applications requiring adaptive data structures, such as real-time simulations, games, or data management tasks. It differs from ARM.Redim by allowing arbitrary resizing, including both expansion and contraction, while preserving data where possible and padding new areas with defaults.
Illustration:
🔄 2D Array Resizing: A chessboard-like grid with handle $$ARR, originally 2x2 [A1, A2; B1, B2], is resized to 3x3 [A1, A2, “; B1, B2, “; “, “, “], preserving existing values and padding new cells with empty strings.
🔑 Handle: $$ARR remains valid, with the new dimensions and padded defaults applied.
Syntax
ARM.Resize|$$ARR|$$ROW|$$COL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to resize. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
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., 3 for a 3-row chessboard-like structure). It can be smaller or larger than the current number of rows, leading to truncation or padding.
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., 3 for a 3-column chessboard-like structure). It can be smaller or larger than the current number of columns, leading to truncation or padding.
Examples
'--------------------------------------------------------
' ARM.Resize - Sample 1: Resizing a String Array (Game Board) from 2x2 to 3x3
'--------------------------------------------------------
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 resizing: [A1, A2; B1, B2] (2x2)
' Resize to 3x3
SET|$$ROW|3
SET|$$COL|3
ARM.Resize|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [A1, A2, “; B1, B2, “; “, “, “] (3x3, padded with empty strings)
' Check dimensions
ARM.Count|$$ARR|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARR|2|$$COL
JIV.$$COL!3|Lab_failed
' Check existing values
ARM.Get|$$ARR|1|1|$$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.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!B2|Lab_failed
' New elements should be default (empty string)
ARM.Get|$$ARR|3|1|$$VAL
JIS.$$VAL|Lab_failed
ARM.Get|$$ARR|1|3|$$VAL
JIS.$$VAL|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Resize - Sample 2: Resizing a Numeric Array (Matrix) from 2x2 to 4x3
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|2|2
' Set values
ARM.Set|$$ARR|1|1|1
ARM.Set|$$ARR|1|2|2
ARM.Set|$$ARR|2|1|3
ARM.Set|$$ARR|2|2|4
DBP.2D Array (matrix) before resizing: [1, 2; 3, 4] (2x2)
' Resize to 4x3
SET|$$ROW|4
SET|$$COL|3
ARM.Resize|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [1, 2, 0; 3, 4, 0; 0, 0, 0; 0, 0, 0] (4x3, padded with 0)
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Resize - Sample 3: Resizing and Shrinking a Floating-Point Array (Image Pixel Grid) from 3x3 to 2x2
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|3|3
' Set values
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.Set|$$ARR|1|3|3.14
ARM.Set|$$ARR|2|1|0.5
ARM.Set|$$ARR|2|2|2.0
ARM.Set|$$ARR|2|3|-1.8
ARM.Set|$$ARR|3|1|4.2
ARM.Set|$$ARR|3|2|-3.0
ARM.Set|$$ARR|3|3|0.0
DBP.2D Array (pixel grid) before resizing: [1.5, -2.7, 3.14; 0.5, 2.0, -1.8; 4.2, -3.0, 0.0] (3x3)
' Resize to 2x2 (shrinking, truncating excess data)
SET|$$ROW|2
SET|$$COL|2
ARM.Resize|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: [1.5, -2.7; 0.5, 2.0] (2x2, preserving top-left data)
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.Resize. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to check current and new dimensions for proper resizing.
- Existing data is preserved within the intersection of old and new dimensions, with new cells padded with default values (0 for integers/floating-point, empty string for strings). Data outside the new dimensions is truncated, as shown in Sample 3, so ensure the new dimensions meet application needs to avoid data loss.
- The performance of resizing a 2D array in MRL, due to its emulation within a one-dimensional structure, may introduce moderate overhead, especially for large arrays or frequent resizes, as it involves reorganizing and padding/truncating data. However, this is typically acceptable for most practical use cases, such as resizing game boards, pixel grids, or matrices, though frequent resizes in very large arrays should be minimized for performance optimization.
- This command is ideal for dynamic applications like games (expanding or shrinking level maps), image processing (scaling images), or scientific computing (adjusting matrix sizes for new calculations), offering more flexibility than ARM.Redim by allowing arbitrary resizing.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to resize 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 or performing frequent resizes 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 resizes or optimizing data handling if performance is critical.
- Data truncation occurs when shrinking the array, and padding with defaults happens when expanding; ensure the new dimensions are carefully chosen to preserve critical data, as shown in the examples with verification steps.
- 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