|
<< 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.Clear
Clears all contents of a two-dimensional array while preserving its structure and handle.
Intention
The ARM.Clear command removes all data from a two-dimensional (2D) array, resetting its contents to default values (0 for integers/floating-point, empty string for strings) while retaining its structure (rows and columns) and handle. This is a key command for memory efficiency and reuse in MiniRobotLanguage, allowing developers to reset a 2D array for a new task without recreating it, such as clearing a game board for a new match, resetting a pixel grid for a new image, or initializing a matrix for fresh 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.Clear ensures the array remains valid and usable, saving the overhead of creating a new array with ARM.New. It’s particularly useful in dynamic applications like games, image processing, or scientific computing where arrays need frequent reuse without structural changes.
Illustration:
🧹 2D Array Clearing: A chessboard-like grid with handle $$ARR, originally containing data (e.g., [King, Queen; ...]), is emptied to [0, 0; ...] or [“, “; ...], preserving its structure (e.g., 3x3 grid).
🔑 Handle: $$ARR remains valid and ready for reuse with the same dimensions.
Syntax
ARM.Clear|$$ARR
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to be cleared. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after clearing, retaining its structure but with all values reset to defaults.
Examples
'***********************************
' ARM.Clear - Sample 1: Clearing a Game Board
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
DBP.2D Array (chessboard-like) before clearing: [King, Queen; ...] (3x3)
ARM.Clear|$$ARR
DBP.2D Array after clearing: [“, “; “, “; “, “] (3x3, empty strings)
ARM.End|$$ARR
'
'***********************************
' ARM.Clear - Sample 2: Clearing 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 clearing: [1.5, -2.7; ...] (2x2)
ARM.Clear|$$ARR
DBP.2D Array after clearing: [0.0, 0.0; 0.0, 0.0] (2x2, zeros)
ARM.End|$$ARR
'
'***********************************
' ARM.Clear - Sample 3: Clearing a Matrix
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
DBP.2D Array (matrix) before clearing: [100, 200; ...] (2x2)
ARM.Clear|$$ARR
DBP.2D Array after clearing: [0, 0; 0, 0] (2x2, zeros)
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.Clear. Use ARM.Validate to verify the handle if there’s any doubt.
- Clearing a 2D array resets all values to default (0 for integers/floating-point, empty string for strings), but the structure (rows and columns) and handle remain intact, making it efficient for reuse in applications like games (resetting a board), image processing (clearing a pixel grid), or scientific computing (reinitializing a matrix).
- The performance of clearing 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, clearing may take slightly longer, though this is typically negligible for most practical use cases, such as small game boards or pixel grids.
- This command is more efficient than destroying and recreating an array with ARM.End and ARM.New, as it preserves the array’s structure and handle, reducing memory allocation overhead in dynamic applications.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to clear an invalid handle may cause runtime errors.
- Clearing does not change the array’s dimensions; use ARM.Redim if structural changes are needed, which may lead to data loss or padding if dimensions are altered.
- For very large 2D arrays, clearing 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.End