|
<< 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.Set
Sets a value at a specific (row, column) position in a two-dimensional array.
Intention
The ARM.Set command assigns a specified value to a particular (row, column) position within a two-dimensional (2D) array, enabling developers to populate or update data in a structured grid. This is a fundamental command for data manipulation in MiniRobotLanguage, essential for tasks like placing pieces on a game board (e.g., positioning a king on a chessboard at [1,1]), setting pixel values in an image grid, or updating 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.Set provides precise control over individual cells in this grid. It’s widely used in applications requiring dynamic data entry, such as games, image processing, or scientific computing, ensuring accurate data placement while respecting the array’s dimensions and data type (strings, integers, or floating-point numbers).
Illustration:
✍️ 2D Array Update: A chessboard-like grid with handle $$ARR has a value (e.g., 99) set at position [2,3], updating the grid (e.g., [..., 99, ...] in a 3x4 structure).
🔑 Handle: $$ARR remains valid, with the new value integrated into the grid.
Syntax
ARM.Set|$$ARR|$$ROW|$$COL|$$VAL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to update. 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 where the value will be set. 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 2 on a chessboard).
P3 - $$COL - (Variable, 5 characters max)
The column index where the value will be set. 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 3 on a chessboard).
P4 - $$VAL - (Variable, 5 characters max)
The value to set at the specified (row, column) position. This must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); attempting to set an incompatible type will result in an error (e.g., setting a number in a string array).
Examples
'***********************************
' ARM.Set - Sample 1: Setting a Game Piece on a Board
'***********************************
ARM.New|$$ARR
SET|$$ROW|1
SET|$$COL|1
SET|$$VAL|King
ARM.Set|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (chessboard-like) after setting: [King, “; ...] (3x3)
ARM.End|$$ARR
'
'***********************************
' ARM.Set - Sample 2: Setting a Pixel Value in an Image
'***********************************
ARM.New|$$ARR|f
SET|$$ROW|1
SET|$$COL|1
SET|$$VAL|1.5
ARM.Set|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (pixel grid) after setting: [1.5, 0.0; ...] (2x2)
ARM.End|$$ARR
'
'***********************************
' ARM.Set - Sample 3: Updating a Matrix Value
'***********************************
ARM.New|$$ARR|i
SET|$$ROW|1
SET|$$COL|1
SET|$$VAL|100
ARM.Set|$$ARR|$$ROW|$$COL|$$VAL
DBP.2D Array (matrix) after setting: [100, 0; ...] (2x2)
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.Set. 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 value ($$VAL) must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); setting an incompatible type (e.g., a number in a string array) will cause an error. Use ARM.GetType to verify the array’s type if unsure.
- The performance of setting values in a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally fast with minimal overhead. However, frequent updates to very large arrays may introduce slight performance impact, though this is typically negligible for most practical use cases, such as updating game boards or pixel grids.
- This command is foundational for dynamic data manipulation, enabling precise updates in applications like games (placing pieces), image processing (setting pixel values), or scientific computing (updating matrix elements).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to set a value in 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 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, frequent setting 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.Get