|
<< 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.Count
Retrieves the number of rows or columns in a two-dimensional array, storing the count in a variable.
Intention
The ARM.Count command determines the number of rows or columns in a two-dimensional (2D) array and stores this count in a specified variable, providing essential dimension information for dynamic programming. This is a critical command for size management in MiniRobotLanguage, enabling developers to query the structure of a 2D array for tasks like iterating over a game board (e.g., counting rows and columns on a chessboard-like grid), verifying image dimensions for pixel processing, or understanding matrix sizes for mathematical operations. 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.Count offers a simple way to access this metadata, returning the number of rows or columns based on the specified dimension parameter. It’s particularly useful in applications requiring adaptive data handling, such as games, image processing, or scientific computing, where knowing the array’s size is necessary for looping, resizing, or validation before operations like ARM.InsertRow or ARM.GetDims.
Illustration:
📏 2D Array Dimension Count: A chessboard-like grid with handle $$ARR, measuring 3 rows and 4 columns, has its row count (3) stored in $$ROW and column count (4) in $$COL using ARM.Count.
🔑 Handle: $$ARR remains valid, with dimension counts available for further processing.
Syntax
ARM.Count|$$ARR|$$DIM|$$CNT
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array whose dimensions are to be counted. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$DIM - (Variable, 5 characters max)
The dimension to count, specified as 1 for rows or 2 for columns. This must be a numeric value (1 or 2), determining whether to retrieve the number of rows or columns in the grid (e.g., 1 for counting rows on a chessboard, 2 for counting columns).
P3 - $$CNT - (Variable, 5 characters max)
The variable where the count of the specified dimension will be stored. This must be a valid variable name, limited to 5 characters, and will contain a positive integer representing the number of rows (if $$DIM is 1) or columns (if $$DIM is 2).
Examples
'--------------------------------------------------------
' ARM.Count - Sample 1: Counting Dimensions After Operations on a String Array (Game Board)
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|4
DBP.2D Array (chessboard-like) initial size: 3x4
' Check initial dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!3|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!4|Lab_failed
' Insert a row
SET|$$POS|2
ARM.InsertRow|$$ARR|$$POS
DBP.2D Array after row insertion: 4x4
' Check updated dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!4|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!4|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Count - Sample 2: Counting Dimensions of a Numeric Array (Matrix) After Resizing
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|2|3
DBP.2D Array (matrix) initial size: 2x3
' Check initial dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!2|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!3|Lab_failed
' Resize to 3x2
SET|$$ROW|3
SET|$$COL|2
ARM.Resize|$$ARR|$$ROW|$$COL
DBP.2D Array after resizing: 3x2
' Check updated dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!3|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!2|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Count - Sample 3: Counting Dimensions of a Floating-Point Array (Pixel Grid) After Insertion and Deletion
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|2|2
DBP.2D Array (pixel grid) initial size: 2x2
' Check initial dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!2|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!2|Lab_failed
' Insert a column
SET|$$POS|2
ARM.InsertCol|$$ARR|$$POS
DBP.2D Array after column insertion: 2x3
' Check updated dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!2|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!3|Lab_failed
' Delete the inserted column
ARM.DeleteCol|$$ARR|$$POS
DBP.2D Array after column deletion: 2x2
' Check final dimensions
SET|$$DIM|1
ARM.Count|$$ARR|$$DIM|$$ROW
JIV.$$ROW!2|Lab_failed
SET|$$DIM|2
ARM.Count|$$ARR|$$DIM|$$COL
JIV.$$COL!2|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.Count. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to retrieve both dimensions simultaneously if needed.
- The dimension parameter ($$DIM) must be 1 for rows or 2 for columns; invalid values will result in errors or undefined behavior. The count is returned as a positive integer in $$CNT, reflecting the current size after any modifications like ARM.InsertRow, ARM.Resize, or ARM.DeleteRow, as shown in the examples.
- The performance of counting dimensions in a 2D array in MRL is extremely fast, with negligible overhead, as it simply accesses metadata stored with the array handle. This makes ARM.Count suitable for frequent use in dynamic applications, such as tracking game board sizes, pixel grid dimensions, or matrix sizes during runtime operations.
- This command is essential for dimension-aware programming, enabling developers to adaptively handle 2D arrays in real-time, such as verifying game board sizes, ensuring image dimensions, or validating matrix operations before processing.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to count dimensions of an invalid handle may cause runtime errors.
- The dimension parameter ($$DIM) must be 1 or 2; other values will result in errors or undefined behavior.
- The variable for the count ($$CNT) must be a valid variable name, limited to 5 characters; invalid variable names may result in errors or undefined behavior.
- 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