|
<< 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.GetDims
Retrieves the dimensions (rows and columns) of a two-dimensional array, storing them in variables.
Intention
The ARM.GetDims command retrieves the current dimensions (number of rows and columns) of a two-dimensional (2D) array and stores them in specified variables. This is a critical command for dynamic programming in MiniRobotLanguage, enabling developers to determine the size of a 2D array during runtime, which is essential for tasks like iterating over a game board (e.g., checking a chessboard’s rows and columns), verifying image dimensions for pixel processing, or understanding matrix sizes 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.GetDims provides the necessary information to navigate or manipulate this grid effectively. It’s particularly useful in applications requiring adaptive data handling, such as games, image processing, or scientific simulations, where array dimensions may change or need validation before operations like resizing or accessing elements.
Illustration:
📏 2D Array Dimensions: A chessboard-like grid with handle $$ARR, measuring 3 rows and 4 columns, has its dimensions stored in $$ROW (3) and $$COL (4).
🔑 Handle: $$ARR remains valid, with dimensions accessible for further processing.
Syntax
ARM.GetDims|$$ARR|$$ROW|$$COL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array whose dimensions are to be retrieved. 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 variable where the number of rows in the 2D array will be stored. This must be a valid variable name, limited to 5 characters, and will contain a positive integer representing the vertical size of the grid (e.g., 3 for a 3-row chessboard-like structure).
P3 - $$COL - (Variable, 5 characters max)
The variable where the number of columns in the 2D array will be stored. This must be a valid variable name, limited to 5 characters, and will contain a positive integer representing the horizontal size of the grid (e.g., 4 for a 4-column chessboard-like structure).
Examples
'***********************************
' ARM.GetDims - Sample 1: Checking Game Board Dimensions
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
ARM.GetDims|$$ARR|$$ROW|$$COL
DBP.2D Array (chessboard-like) dimensions: $$ROW rows, $$COL columns (e.g., 3x3)
ARM.End|$$ARR
'
'***********************************
' ARM.GetDims - Sample 2: Checking Image Pixel Grid Dimensions
'***********************************
ARM.New|$$ARR|f
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.GetDims|$$ARR|$$ROW|$$COL
DBP.2D Array (pixel grid) dimensions: $$ROW rows, $$COL columns (e.g., 2x2)
ARM.End|$$ARR
'
'***********************************
' ARM.GetDims - Sample 3: Checking Matrix Dimensions
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
ARM.GetDims|$$ARR|$$ROW|$$COL
DBP.2D Array (matrix) dimensions: $$ROW rows, $$COL columns (e.g., 2x2)
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.GetDims. Use ARM.Validate to ensure the handle is valid if there’s any doubt.
- The dimensions retrieved (rows in $$ROW, columns in $$COL) are positive integers reflecting the current structure of the 2D array, which can be used for looping, resizing, or validating array size in applications like games (e.g., iterating over a chessboard), image processing (e.g., checking image resolution), or scientific computing (e.g., verifying matrix size).
- The performance of retrieving dimensions in MRL, due to the emulation of 2D arrays within a one-dimensional structure, is typically fast with minimal overhead. However, for very large arrays, frequent dimension checks may add slight performance impact, though this is generally negligible for most practical use cases, such as small game boards or pixel grids.
- This command is essential for dynamic programming, allowing developers to adaptively handle 2D arrays in real-time, such as resizing with ARM.Redim or accessing elements with ARM.Get and ARM.Set based on current dimensions.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to retrieve dimensions of an invalid handle may cause runtime errors.
- The variables for rows ($$ROW) and columns ($$COL) must be valid variable names, limited to 5 characters; invalid variable names may result in errors or undefined behavior.
- For very large 2D arrays, frequent dimension retrievals 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