|
<< 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.New
Creates a new two-dimensional array and returns its handle for further manipulation.
Intention
The ARM.New command initializes a new two-dimensional (2D) array in memory and assigns it a unique handle, which is stored in a variable (limited to 5 characters, e.g., $$ARR). This handle is used to perform subsequent operations on the array, such as adding elements, resizing, or querying its contents. 2D arrays are particularly useful for organizing data in a grid-like structure, such as rows and columns, making them ideal for applications like game boards (e.g., chess or tic-tac-toe), image pixel grids, mathematical matrices, or database tables. The command supports three data types—strings (default), 64-bit integers, and floating-point numbers—offering flexibility for various use cases, including text processing, numerical computations, or binary data storage.
In MiniRobotLanguage, 2D arrays are emulated within a one-dimensional structure, which may result in slightly slower performance compared to native 2D implementations. However, this trade-off is often negligible in practice, especially for most MRL applications. To visualize a 2D array, imagine a chessboard: each cell is uniquely identified by its row and column indices (e.g., [1,1] for the top-left corner, [8,8] for the bottom-right), forming an 8x8 grid—a perfect analogy for how ARM manages 2D arrays.
Illustration:
🌟 New 2D Array Creation: An empty grid appears [[]], representing rows and columns (e.g., a chessboard-like structure).
🔑 Handle: Stored in $$ARR
🔢 Data Type: String (default) or optionally Integer (‘i’) or Floating-Point (‘f’)
Syntax
ARM.New|$$ARR[|P2]
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The variable that will store the handle of the newly created 2D array. This handle is used to reference the array in subsequent ARM commands, such as adding data or resizing the grid.
P2 - (Optional, String)
Specifies the data type of the 2D array. Valid values include:
• "s" - Text/Strings (default, supports any data including binary data, ideal for game board labels or text data in matrices)
• "i" - 64-bit Integer (range: -9.22x10^18 to 9.22x10^18, or -2^63 to 2^63 -1, perfect for numerical game scores or matrix calculations)
• "f" - Floating-point number (range: approximately +/- 3.4*10^-4932 to 1.2*10^4932, with 18 digits of precision, suitable for scientific computations or pixel intensity values)
Examples
'***********************************
' ARM.New - Sample 1: String 2D Array for a Game Board
'***********************************
ARM.New|$$ARR
DBP.New String 2D array created with handle: $$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
DBP.2D Array contents (chessboard-like): [King, Queen; ...]
ARM.End|$$ARR
'
'***********************************
' ARM.New - Sample 2: Integer 2D Array for a Score Matrix
'***********************************
ARM.New|$$ARR|i
DBP.New Integer 2D array created with handle: $$ARR
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|-200
ARM.Set|$$ARR|2|1|300
DBP.2D Array contents (matrix): [100, -200; 300, 0]
ARM.End|$$ARR
'
'***********************************
' ARM.New - Sample 3: Floating-Point 2D Array for Image Pixels
'***********************************
ARM.New|$$ARR|f
DBP.New Floating-Point 2D array created with handle: $$ARR
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.Set|$$ARR|2|1|3.14
DBP.2D Array contents (pixel grid): [1.5, -2.7; 3.14, 0.0]
ARM.End|$$ARR
'
Remarks
- The array handle must be stored in a variable with a maximum length of 5 characters (e.g., $$ARR, $$TMP).
- Always use ARM.End to free memory when a 2D array is no longer needed to prevent memory leaks, especially in long-running applications like games or image editors.
- The performance of 2D arrays in MRL, due to their emulation within a one-dimensional structure, may be slightly slower than native 2D implementations, but this is typically negligible for most use cases, such as initializing small game boards or pixel grids.
Limitations
- The array handle variable must not exceed 5 characters.
- The data type must be explicitly specified if not using the default (strings); mismatched types in subsequent operations (e.g., numeric operations on string arrays) may cause errors.
- Large 2D arrays may experience minor performance overhead due to the emulation, but this is rarely significant for typical applications like game boards or small matrices.
See also:
• ARM.End