|
<< 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.Get
Retrieves a value from a specific (row, column) position in a two-dimensional array, storing it in a variable.
Intention
The ARM.Get command retrieves a value from a specified (row, column) position within a two-dimensional (2D) array and stores it in a variable, enabling developers to read data from a structured grid for further processing. This is a fundamental command for data retrieval in MiniRobotLanguage, essential for tasks like checking piece positions on a game board (e.g., reading a king’s position on a chessboard at [1,1]), accessing pixel values in an image grid, or querying elements in a mathematical matrix. 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.Get provides precise access to individual cells in this grid. It’s widely used in applications requiring dynamic data reading, such as games, image processing, or scientific computing, ensuring accurate data extraction while respecting the array’s dimensions and data type (strings, integers, or floating-point numbers).
Illustration:
👁️ 2D Array Read: A chessboard-like grid with handle $$ARR has a value (e.g., “King”) retrieved from position [1,1], stored in $$VAL for further use.
🔑 Handle: $$ARR remains valid, with the retrieved value available in $$VAL.
Syntax
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to read from. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$ROW - (Variable, 5 characters max)
The row index from which to retrieve the value. This must be a positive integer within the array’s row bounds (e.g., 1 to the number of rows, as retrieved by ARM.GetDims), representing the vertical position in the grid (e.g., row 1 on a chessboard).
P3 - $$COL - (Variable, 5 characters max)
The column index from which to retrieve the value. This must be a positive integer within the array’s column bounds (e.g., 1 to the number of columns, as retrieved by ARM.GetDims), representing the horizontal position in the grid (e.g., column 1 on a chessboard).
P4 - $$VAL - (Variable, 5 characters max)
The variable where the retrieved value will be stored. This must be a valid variable name, limited to 5 characters, and will contain the value at the specified (row, column) position, matching the array’s data type (strings, integers, or floating-point, as specified during ARM.New).
Examples
'***********************************
' ARM.Get - Sample 1: Reading a Game Piece from a Board
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
SET|$$ROW|1
SET|$$COL|1
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (chessboard-like) value at [1,1]: $$VAL (e.g., “King”)
ARM.End|$$ARR
'
'***********************************
' ARM.Get - Sample 2: Reading a Pixel Value from an Image
'***********************************
ARM.New|$$ARR|f
ARM.Set|$$ARR|1|1|1.5
SET|$$ROW|1
SET|$$COL|1
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (pixel grid) value at [1,1]: $$VAL (e.g., 1.5)
ARM.End|$$ARR
'
'***********************************
' ARM.Get - Sample 3: Reading a Matrix Value
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
SET|$$ROW|1
SET|$$COL|1
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (matrix) value at [1,1]: $$VAL (e.g., 100)
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.Get. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to check row and column bounds to avoid index errors.
- Row ($$ROW) and column ($$COL) indices must be within the array’s current dimensions; out-of-bounds indices will result in errors. Ensure indices are positive integers starting from 1, matching the grid structure (e.g., 1 to 8 for a chessboard).
- The retrieved value (stored in $$VAL) will match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); use ARM.GetType to verify the array’s type if needed for processing.
- The performance of retrieving values from a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally fast with minimal overhead. However, frequent reads from very large arrays may introduce slight performance impact, though this is typically negligible for most practical use cases, such as reading game boards or pixel grids.
- This command is foundational for data retrieval, enabling precise reading in applications like games (checking piece positions), image processing (accessing pixel values), or scientific computing (querying matrix elements).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to get a value from an invalid handle may cause runtime errors.
- Row ($$ROW) and column ($$COL) indices must be within bounds, as determined by ARM.GetDims; out-of-bounds indices will result in errors or undefined behavior.
- The variable for the value ($$VAL) must be a valid variable name, limited to 5 characters; invalid variable names may result in errors or undefined behavior.
- For very large 2D arrays, frequent get operations 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.Set