|
<< 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.InsertRow
Inserts a new row at a specified position in a two-dimensional array, shifting existing rows downward.
Intention
The ARM.InsertRow command adds a new row at a specified position within a two-dimensional (2D) array, shifting all existing rows below that position downward to accommodate the insertion. This is a key command for dynamically expanding data structures in MiniRobotLanguage, enabling developers to grow a 2D array during runtime, such as adding a new row to a game board (e.g., extending a chessboard-like grid), expanding a pixel grid for image processing, or enlarging a matrix for mathematical 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 ARM.InsertRow provides flexibility for applications requiring adaptive data storage, such as real-time simulations, games, or data management tasks. The new row is initialized with default values (0 for integers/floating-point, empty string for strings), and the array’s handle and structure (columns) remain intact, making it ideal for dynamic growth without recreation.
Illustration:
➕ 2D Array Row Insertion: A chessboard-like grid with handle $$ARR, originally 3x4, has a new row inserted at position 2, shifting rows downward (e.g., [King, Queen; ...] becomes [King, Queen; 0, 0; Pawn, Bishop; ...] in a 4x4 structure).
🔑 Handle: $$ARR remains valid, with the new row added and existing data shifted.
Syntax
ARM.InsertRow|$$ARR|$$POS
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array where the row will be inserted. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$POS - (Variable, 5 characters max)
The position (row index) where the new row will be inserted. This must be a positive integer within the range 1 to the current number of rows + 1 (as retrieved by ARM.GetDims), representing the insertion point in the grid (e.g., 2 to insert a row after row 1 on a chessboard).
Examples
'***********************************
' ARM.InsertRow - Sample 1: Adding a Row to a Game Board
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
DBP.2D Array (chessboard-like) before insertion: [King, Queen; ...] (3x2)
SET|$$POS|2
ARM.InsertRow|$$ARR|$$POS
DBP.2D Array after insertion: [King, Queen; “, “; Pawn, Bishop] (4x2, new row with defaults)
ARM.End|$$ARR
'
'***********************************
' ARM.InsertRow - Sample 2: Adding a Row to 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 insertion: [1.5, -2.7; ...] (2x2)
SET|$$POS|2
ARM.InsertRow|$$ARR|$$POS
DBP.2D Array after insertion: [1.5, -2.7; 0.0, 0.0; 3.14, 4.2] (3x2, new row with defaults)
ARM.End|$$ARR
'
'***********************************
' ARM.InsertRow - Sample 3: Adding a Row to a Matrix
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
DBP.2D Array (matrix) before insertion: [100, 200; ...] (2x2)
SET|$$POS|2
ARM.InsertRow|$$ARR|$$POS
DBP.2D Array after insertion: [100, 200; 0, 0; 300, 400] (3x2, new row with defaults)
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.InsertRow. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to check current dimensions for proper positioning.
- The position ($$POS) must be within the range 1 to the current number of rows + 1; out-of-bounds positions will result in errors. Ensure $$POS is a positive integer, matching the grid structure (e.g., 1 to insert at the top of a chessboard, or current rows + 1 to append at the bottom).
- The new row is initialized with default values (0 for integers/floating-point, empty string for strings), which can be updated later with ARM.Set. This behavior is ideal for applications like games (adding new level rows), image processing (expanding pixel grids), or scientific computing (growing matrices dynamically).
- The performance of inserting a row in a 2D array in MRL, due to its emulation within a one-dimensional structure, may introduce moderate overhead, especially for large arrays, as existing data must be shifted. However, this is typically acceptable for most practical use cases, such as small game boards or pixel grids, though frequent insertions in very large arrays should be minimized for performance optimization.
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to insert a row into an invalid handle may cause runtime errors.
- The position ($$POS) must be within bounds (1 to current rows + 1); out-of-bounds positions will result in errors or undefined behavior.
- Inserting rows into very large 2D arrays frequently may impact performance due to data shifting in the emulation, though this is typically manageable for most applications like game boards or small matrices. For large arrays, consider batching insertions or using alternative data structures if performance is critical.
- 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