|
<< 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.End
Destroys a specific two-dimensional array, freeing its memory.
Intention
The ARM.End command destroys a specific two-dimensional (2D) array identified by its handle, releasing the memory it occupies. This is a critical command for memory management in MiniRobotLanguage, ensuring that resources are freed when a 2D array is no longer needed, preventing memory leaks in applications like games, image processing, or scientific 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 proper cleanup with ARM.End is essential, especially in long-running programs or resource-constrained environments. This command is typically used after completing tasks involving a 2D array, such as finishing a game level, processing an image, or completing a matrix calculation.
Illustration:
🗑️ 2D Array Destruction: The grid (e.g., a chessboard-like [3x3] array) with handle $$ARR is removed from memory, freeing resources.
🔑 Handle: $$ARR is invalidated and no longer usable.
Syntax
ARM.End|$$ARR
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to be destroyed. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it will be invalidated after execution, rendering the array inaccessible for further operations.
Examples
'***********************************
' ARM.End - Sample 1: Ending a Game Board Array
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
DBP.2D Array (chessboard-like) before ending: [King, Queen; ...]
ARM.End|$$ARR
DBP.Array $$ARR destroyed, memory freed
'
'***********************************
' ARM.End - Sample 2: Ending an Image Pixel Array
'***********************************
ARM.New|$$ARR|f
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
DBP.2D Array (pixel grid) before ending: [1.5, -2.7; ...]
ARM.End|$$ARR
DBP.Array $$ARR destroyed, memory freed
'
'***********************************
' ARM.End - Sample 3: Ending a Matrix After Calculation
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
DBP.2D Array (matrix) before ending: [100, 200; ...]
ARM.End|$$ARR
DBP.Array $$ARR destroyed, memory freed
'
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.End.
- Using ARM.End on an invalid or already destroyed handle may result in errors; always validate the handle with ARM.Validate before destruction if unsure.
- Proper use of ARM.End is crucial for maintaining application performance, especially in resource-constrained environments or long-running programs like games or image editors, where memory leaks could degrade performance over time.
- The performance impact of destroying a 2D array is minimal, but ensuring timely cleanup prevents memory bloat, particularly with multiple arrays in use (e.g., multiple game boards or image layers).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to destroy an invalid handle may cause runtime errors.
- There is no undo for ARM.End; once an array is destroyed, its data is permanently lost, requiring recreation with ARM.New if needed.
- The command assumes the handle refers to a 2D array; using it on other data types or structures may lead to undefined behavior.
See also:
• ARM.New