|
<< 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.Fill
Fills all elements of a two-dimensional array with a specified value, overwriting existing data.
Intention
The ARM.Fill command replaces all elements in a two-dimensional (2D) array with a specified value, overwriting any existing data while preserving the array’s structure (rows and columns) and handle. This is a key command for initialization or reset in MiniRobotLanguage, enabling developers to quickly populate a 2D array for tasks like setting up a uniform game board (e.g., filling a chessboard-like grid with a default value), initializing a pixel grid with a uniform color, or preparing a matrix with a constant value for 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.Fill provides an efficient way to set all cells to a single value, matching the array’s data type (strings, integers, or floating-point numbers). It’s particularly useful in applications requiring uniform data initialization, such as games, image processing, or scientific computing, where a clean slate or consistent value is needed before further manipulation.
Illustration:
🖌️ 2D Array Filling: A chessboard-like grid with handle $$ARR, originally [King, Queen; Pawn, Bishop] (2x2), is filled with “Fill”, becoming [Fill, Fill; Fill, Fill].
🔑 Handle: $$ARR remains valid, with all elements set to the specified value.
Syntax
ARM.Fill|$$ARR|$$VAL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to fill. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$VAL - (Variable, 5 characters max)
The value to fill all elements of the 2D array. This must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); attempting to use an incompatible type (e.g., a number in a string array) will result in an error.
Examples
'--------------------------------------------------------
' ARM.Fill - Sample 1: Filling a String Array (Game Board) with “Fill”
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
' Fill with “Fill”
SET|$$VAL|Fill
ARM.Fill|$$ARR|$$VAL
DBP.2D Array (chessboard-like) after filling: [Fill, Fill; Fill, Fill] (2x2)
' Check all elements
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!Fill|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!Fill|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!Fill|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!Fill|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Fill - Sample 2: Filling a Numeric Array (Matrix) with 0
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|3|2
' Fill with 0
SET|$$VAL|0
ARM.Fill|$$ARR|$$VAL
DBP.2D Array (matrix) after filling: [0, 0; 0, 0; 0, 0] (3x2)
' Check all elements
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARR|3|1|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARR|3|2|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Fill - Sample 3: Filling a Floating-Point Array (Image Pixel Grid) with 1.0
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|2|3
' Fill with 1.0
SET|$$VAL|1.0
ARM.Fill|$$ARR|$$VAL
DBP.2D Array (pixel grid) after filling: [1.0, 1.0, 1.0; 1.0, 1.0, 1.0] (2x3)
' Check all elements
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!1.0|Lab_failed
ARM.Get|$$ARR|1|2|$$VAL
JIV.$$VAL!1.0|Lab_failed
ARM.Get|$$ARR|1|3|$$VAL
JIV.$$VAL!1.0|Lab_failed
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!1.0|Lab_failed
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!1.0|Lab_failed
ARM.Get|$$ARR|2|3|$$VAL
JIV.$$VAL!1.0|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.Fill. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to verify the array’s structure before filling.
- The fill value ($$VAL) must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); attempting to use an incompatible type (e.g., a number in a string array) will result in an error. Use ARM.GetType to verify the array’s type if unsure.
- Filling overwrites all existing data, so ensure this action is intentional, especially in applications like games (resetting a board), image processing (setting a uniform color), or scientific computing (initializing a matrix). Use ARM.Get to back up data if needed before filling, as shown in the examples with verification steps.
- The performance of filling a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally fast with minimal overhead. However, for very large arrays, filling may take slightly longer, though this is typically negligible for most practical use cases, such as initializing game boards or pixel grids.
- This command is ideal for uniform initialization in applications like games (setting default board states), image processing (filling with a background color), or scientific computing (setting constant matrix values).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to fill an invalid handle may cause runtime errors.
- The fill value ($$VAL) must match the array’s data type; type mismatches will cause errors, requiring type consistency as set during ARM.New.
- For very large 2D arrays, filling 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
• ARM.Get