3. Script Language > Arrays and Data-Structures > !ARM. - Multidimensional Dynamic Arrays

Array Operations Overview

Previous Top Next

MiniRobotLanguage (MRL)

Array Operations

Comprehensive Guide to Managing Two-Dimensional Arrays in MiniRobotLanguage (MRL) Using the ARM Command Set

Overview

The ARM (Array Management) commands in MiniRobotLanguage (MRL) form a robust and versatile toolkit designed for creating, manipulating, querying, and transforming two-dimensional (2D) arrays. These arrays are conceptualized as grid-like structures—imagine a chessboard with rows and columns numbered from [1,1] to [8,8]—emulated within a one-dimensional framework in MRL. This design supports three fundamental data types: strings (“s”), integers (“i”), and floating-point numbers (“f”), making it adaptable to a wide range of use cases. The ARM commands empower developers to perform tasks such as setting individual elements, deleting or inserting rows, sorting data, rotating grids, and calculating sums, catering to diverse applications including:

- Game Development: Managing game boards like chess, tic-tac-toe, or puzzles by setting pieces, finding positions, or reversing layouts.
- Image Processing: Handling pixel grids for transformations such as filling regions, rotating images, or transposing layouts.
- Scientific Computing: Performing matrix operations, including summing elements, sorting rows, or reorienting data for analysis.
- Data Management: Organizing tabular data for dynamic resizing, querying, or swapping values in real-time applications.

This guide provides an exhaustive exploration of each ARM command, detailing its purpose, syntax, parameters, practical examples, remarks, limitations, and related commands. All array indices in MRL are 1-based, aligning with the intuitive grid structure, and operations require a valid array handle created with ARM.New. Given MRL’s emulation of 2D arrays as 1D structures, performance considerations are highlighted, especially for large datasets where linear overhead may occur. Each command is accompanied by sample code to illustrate typical use cases, ensuring developers can quickly grasp and apply these tools effectively.

Commands

1. ARM.DeleteRow

Deletes a specified row from a 2D array, shifting all subsequent rows upward and reducing the total row count by one. This operation is useful for dynamically resizing grids or removing unwanted data.

Syntax

ARM.DeleteRow|$$ARR|$$ROW

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to modify.
$$ROW - (Variable, max 5 characters) The 1-based row index to delete, must be within the array’s current row count.

Examples
' Example 1: Deleting a Row from a String Array (Game Board)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|2
' Populate the array
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|2|1|B1
ARM.Set|$$ARR|2|2|B2
ARM.Set|$$ARR|3|1|C1
ARM.Set|$$ARR|3|2|C2
' Delete row 2
SET|$$ROW|2
ARM.DeleteRow|$$ARR|$$ROW
ARM.Count|$$ARR|1|$$CNT
JIV.$$CNT!2|Lab_failed ' Verify row count is now 2
ARM.Get|$$ARR|2|1|$$VAL
JIV.$$VAL!C1|Lab_failed ' Row 3 shifted to row 2
ARM.End|$$ARR

' Example 2: Deleting a Row from an Integer Array (Matrix)
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|3
' Populate the array
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|1|3|3
ARM.Set|$$ARI|2|1|4
ARM.Set|$$ARI|2|2|5
ARM.Set|$$ARI|2|3|6
' Delete row 1
SET|$$ROW|1
ARM.DeleteRow|$$ARI|$$ROW
ARM.Count|$$ARI|1|$$CNT
JIV.$$CNT!1|Lab_failed ' Verify row count is now 1
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!4|Lab_failed ' Row 2 shifted to row 1
ARM.End|$$ARI

Remarks
- After deletion, remaining rows shift upward, preserving the array’s column count and data type.
- Use ARM.Count to confirm the updated row count post-operation.
- Ideal for scenarios like removing a completed row in a game (e.g., Tetris) or trimming a matrix in scientific data processing.
- For large arrays, shifting elements may introduce noticeable performance overhead due to MRL’s 1D emulation.
- The operation is destructive; deleted data is not recoverable unless a backup array is maintained.

Limitations
- $$ROW must be within the array’s current row bounds (1 to row count); out-of-bounds indices trigger runtime errors.
- Deleting from very large arrays can be slow due to the need to shift all subsequent elements.
- Does not support partial row deletion; the entire row is removed.

See Also
ARM.InsertRow, ARM.Count, ARM.New

2. ARM.Fill

Fills an entire 2D array or a specified rectangular region with a single value. This command is versatile, supporting all array types (strings, integers, floats), and is perfect for initialization or resetting purposes.

Syntax

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to fill.
$$VAL - (Variable/String, max 5 characters) The value to fill the array with, must match the array’s data type.
$$STARTROW - (Variable, max 5 characters, optional) 1-based starting row index; defaults to 1 if omitted.
$$STARTCOL - (Variable, max 5 characters, optional) 1-based starting column index; defaults to 1 if omitted.
$$ENDROW - (Variable, max 5 characters, optional) 1-based ending row index; defaults to last row if omitted.
$$ENDCOL - (Variable, max 5 characters, optional) 1-based ending column index; defaults to last column if omitted.

Examples
' Example 1: Filling an Entire Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
ARM.Fill|$$ARI|0 ' Fill entire array with 0
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARI|2|2|$$VAL
JIV.$$VAL!0|Lab_failed
ARM.End|$$ARI

' Example 2: Filling a Region of a String Array (Game Board)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|3
' Set initial values
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
ARM.Set|$$ARR|1|3|Pawn
' Fill rows 2-3, columns 2-3 with "Empty"
SET|$$STARTROW|2
SET|$$STARTCOL|2
SET|$$ENDROW|3
SET|$$ENDCOL|3
ARM.Fill|$$ARR|Empty|$$STARTROW|$$STARTCOL|$$ENDROW|$$ENDCOL
ARM.Get|$$ARR|2|2|$$VAL
JIV.$$VAL!Empty|Lab_failed
ARM.Get|$$ARR|3|3|$$VAL
JIV.$$VAL!Empty|Lab_failed
ARM.Get|$$ARR|1|1|$$VAL ' Verify unaffected area
JIV.$$VAL!King|Lab_failed
ARM.End|$$ARR

Remarks
- When optional parameters are omitted, the entire array is filled with $$VAL.
- Supports all data types; $$VAL must match the array’s type (e.g., “0” for integers, “Empty” for strings).
- Useful for initializing game boards, resetting pixel grids, or preparing matrices with default values.
- Partial fills (specifying a region) leave elements outside the range unchanged.
- Performance scales with the number of elements filled; large regions or arrays may introduce delays.

Limitations
- Indices must be within bounds; out-of-bounds values (e.g., $$ENDROW > row count) cause errors.
- $$VAL type mismatches (e.g., string in an integer array) result in runtime errors.
- No support for pattern-based or conditional fills; all elements in the range receive the same value.

See Also
ARM.Set, ARM.Get, ARM.New

3. ARM.Find

Searches a 2D array for the first occurrence of a specified value and returns its row and column position. This is invaluable for locating specific elements in grids or matrices.

Syntax

ARM.Find|$$ARR|$$VAL|$$ROW|$$COL

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to search.
$$VAL - (Variable/String, max 5 characters) The value to find, must match the array’s data type.
$$ROW - (Variable, max 5 characters) Receives the 1-based row index of the first match.
$$COL - (Variable, max 5 characters) Receives the 1-based column index of the first match.

Examples
' Example 1: Finding a String in a Game Board
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|Queen
ARM.Set|$$ARR|2|1|Pawn
ARM.Set|$$ARR|2|2|Bishop
ARM.Find|$$ARR|Queen|$$ROW|$$COL
JIV.$$ROW!1|Lab_failed
JIV.$$COL!2|Lab_failed
ARM.End|$$ARR

' Example 2: Finding an Integer in a Matrix
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|3
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|1|3|3
ARM.Set|$$ARI|2|1|2
ARM.Set|$$ARI|2|2|4
ARM.Set|$$ARI|2|3|5
ARM.Find|$$ARI|2|$$ROW|$$COL ' Find first occurrence of 2
JIV.$$ROW!1|Lab_failed
JIV.$$COL!2|Lab_failed
ARM.End|$$ARI

Remarks
- Searches row-by-row, left-to-right, stopping at the first match; $$ROW and $$COL are set to 0 if no match is found.
- Efficient for small arrays but may be slow for large ones due to linear search complexity.
- Perfect for locating game pieces (e.g., finding “King”), pixel values, or matrix elements.
- Case-sensitive for strings; exact matches only.
- Does not support searching for multiple occurrences in a single call.

Limitations
- $$VAL must match the array’s type; type mismatches cause errors.
- Linear search time increases with array size, potentially impacting performance.
- Returns only the first occurrence; additional logic is needed for multiple matches.

See Also
ARM.Get, ARM.Set, ARM.New

4. ARM.Get

Retrieves the value stored at a specified row and column position in a 2D array, providing direct access to grid elements.

Syntax

ARM.Get|$$ARR|$$ROW|$$COL|$$VAL

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array.
$$ROW - (Variable, max 5 characters) 1-based row index.
$$COL - (Variable, max 5 characters) 1-based column index.
$$VAL - (Variable, max 5 characters) Receives the value at the specified position.

Examples
' Example 1: Retrieving a String from a Game Board
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|King
SET|$$ROW|1
SET|$$COL|1
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
JIV.$$VAL!King|Lab_failed
ARM.End|$$ARR

' Example 2: Retrieving a Float from a Matrix
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|2
ARM.Set|$$ARF|2|1|3.14
SET|$$ROW|2
SET|$$COL|1
ARM.Get|$$ARF|$$ROW|$$COL|$$VAL
JIV.$$VAL!3.14|Lab_failed
ARM.End|$$ARF

Remarks
- Provides fast, direct access to any element; constant-time operation regardless of array size.
- Essential for reading game piece positions, pixel values, or matrix data.
- $$VAL retains the array’s data type (string, integer, or float).
- Often paired with ARM.Set for read/write workflows.
- Bounds checking is critical to avoid errors; use ARM.Count to verify dimensions.

Limitations
- Out-of-bounds $$ROW or $$COL values cause errors.
- Returns a single value; no support for retrieving ranges in one call.

See Also
ARM.Set, ARM.Find, ARM.Count

5. ARM.InsertRow

Inserts a new row at a specified position, shifting existing rows downward and increasing the row count by one. New elements are initialized to default values (e.g., 0 for numbers, empty string for strings).

Syntax

ARM.InsertRow|$$ARR|$$POS

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array.
$$POS - (Variable, max 5 characters) 1-based position where the new row is inserted (1 to row count + 1).

Examples
' Example 1: Inserting a Row in an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|2|1|3
ARM.Set|$$ARI|2|2|4
SET|$$POS|2
ARM.InsertRow|$$ARI|$$POS
ARM.Count|$$ARI|1|$$CNT
JIV.$$CNT!3|Lab_failed
ARM.Get|$$ARI|2|1|$$VAL ' New row initialized to 0
JIV.$$VAL!0|Lab_failed
ARM.Get|$$ARI|3|1|$$VAL ' Original row 2 shifted to 3
JIV.$$VAL!3|Lab_failed
ARM.End|$$ARI

' Example 2: Inserting at the End of a String Array
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|1
ARM.Set|$$ARR|1|1|A
ARM.Set|$$ARR|2|1|B
SET|$$POS|3
ARM.InsertRow|$$ARR|$$POS
ARM.Get|$$ARR|3|1|$$VAL
JIV.$$VAL!|Lab_failed ' Empty string as default
ARM.End|$$ARR

Remarks
- Shifts existing rows down from $$POS onward; new row elements are initialized to defaults.
- $$POS can be the row count + 1 to append a new row at the end.
- Useful for expanding game boards or adding rows to matrices dynamically.
- Performance overhead increases with array size due to shifting.
- Column count remains unchanged.

Limitations
- $$POS must be between 1 and row count + 1; invalid values cause errors.
- No option to specify initial values for the new row; use ARM.Set afterward.
- Large arrays may slow down due to element shifting.

See Also
ARM.DeleteRow, ARM.Count, ARM.Set

6. ARM.Reverse

Reverses the order of both rows and columns in a 2D array, effectively creating a full mirror image (180-degree flip) of the original grid.

Syntax

ARM.Reverse|$$ARR

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to reverse.

Examples
' Example 1: Reversing a String Array (Game Board)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|2
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|2|1|B1
ARM.Set|$$ARR|2|2|B2
ARM.Set|$$ARR|3|1|C1
ARM.Set|$$ARR|3|2|C2
ARM.Reverse|$$ARR
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!C2|Lab_failed ' [3,2] moves to [1,1]
ARM.Get|$$ARR|3|2|$$VAL
JIV.$$VAL!A1|Lab_failed ' [1,1] moves to [3,2]
ARM.End|$$ARR

' Example 2: Reversing a Numeric Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
ARM.Set|$$ARI|1|1|1
ARM.Set|$$ARI|1|2|2
ARM.Set|$$ARI|2|1|3
ARM.Set|$$ARI|2|2|4
ARM.Reverse|$$ARI
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!4|Lab_failed
ARM.End|$$ARI

Remarks
- Flips the array both vertically (row order) and horizontally (column order).
- Dimensions remain unchanged; only element positions are swapped.
- Useful for mirroring game boards, flipping images, or reversing matrix layouts.
- Operation is in-place and efficient, with complexity proportional to array size.
- Can be undone by applying ARM.Reverse again.

Limitations
- No option to reverse only rows or columns; full reversal only.
- Large arrays may still incur noticeable overhead due to element swaps.

See Also
ARM.Rotate, ARM.Transpose, ARM.Get

7. ARM.Rotate

Rotates a 2D array 90 degrees clockwise, swapping its dimensions (rows become columns, columns become rows) and rearranging elements accordingly.

Syntax

ARM.Rotate|$$ARR

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array to rotate.

Examples
' Example 1: Rotating a Floating-Point Array (2x3 to 3x2)
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|3
ARM.Set|$$ARF|1|1|1.1
ARM.Set|$$ARF|1|2|1.2
ARM.Set|$$ARF|1|3|1.3
ARM.Set|$$ARF|2|1|2.1
ARM.Set|$$ARF|2|2|2.2
ARM.Set|$$ARF|2|3|2.3
ARM.Rotate|$$ARF
ARM.Count|$$ARF|1|$$ROW
JIV.$$ROW!3|Lab_failed
ARM.Count|$$ARF|2|$$COL
JIV.$$COL!2|Lab_failed
ARM.Get|$$ARF|1|1|$$VAL
JIV.$$VAL!2.1|Lab_failed ' [2,1] moves to [1,1]
ARM.End|$$ARF

' Example 2: Rotating a Square Array
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
ARM.Set|$$ARR|1|1|A
ARM.Set|$$ARR|1|2|B
ARM.Set|$$ARR|2|1|C
ARM.Set|$$ARR|2|2|D
ARM.Rotate|$$ARR
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!C|Lab_failed
ARM.End|$$ARR

Remarks
- Transforms an RxC array into a CxR array; e.g., 2x3 becomes 3x2.
- Rotates elements clockwise; apply four times to return to the original state.
- Ideal for rotating game boards (e.g., Tetris pieces) or image orientations.
- Preserves data type and element values, only changing their positions.
- Complexity is proportional to array size, but typically efficient.

Limitations
- Only supports 90-degree clockwise rotation; no counterclockwise or custom angles.
- Dimension swap may require updating downstream logic relying on row/column counts.

See Also
ARM.Reverse, ARM.Transpose, ARM.Count

8. ARM.Set

Assigns a value to a specific row and column position in a 2D array, enabling precise updates to grid elements.

Syntax

ARM.Set|$$ARR|$$ROW|$$COL|$$VAL

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array.
$$ROW - (Variable, max 5 characters) 1-based row index.
$$COL - (Variable, max 5 characters) 1-based column index.
$$VAL - (Variable/String, max 5 characters) The value to set, must match the array’s data type.

Examples
' Example 1: Setting a Value in an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
SET|$$ROW|1
SET|$$COL|1
ARM.Set|$$ARI|$$ROW|$$COL|5
ARM.Get|$$ARI|$$ROW|$$COL|$$VAL
JIV.$$VAL!5|Lab_failed
ARM.End|$$ARI

' Example 2: Setting a String in a Game Board
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|3
SET|$$ROW|2
SET|$$COL|2
ARM.Set|$$ARR|$$ROW|$$COL|Knight
ARM.Get|$$ARR|$$ROW|$$COL|$$VAL
JIV.$$VAL!Knight|Lab_failed
ARM.End|$$ARR

Remarks
- Overwrites the existing value at the specified position; constant-time operation.
- Critical for updating game states, pixel grids, or matrix elements.
- $$VAL must match the array’s type; type mismatches are not coerced.
- Often used with ARM.Get for read-modify-write patterns.
- Bounds must be validated to prevent errors.

Limitations
- Out-of-bounds $$ROW or $$COL values cause errors.
- Sets one element at a time; no range-setting capability (use ARM.Fill for that).

See Also
ARM.Get, ARM.Fill, ARM.New

9. ARM.Sort

Sorts the entire 2D array based on a specified column in ascending order, maintaining row integrity (i.e., entire rows are reordered).

Syntax

ARM.Sort|$$ARR|$$COL

Parameters
$$ARR - (Variable, max 5 characters) The handle of the 2D array.
$$COL - (Variable, max 5 characters) 1-based column index to sort by.

Examples
' Example 1: Sorting by Column 1 in an Integer Array
ARM.New|$$ARI|i
ARM.Redim|$$ARI|3|2
ARM.Set|$$ARI|1|1|3
ARM.Set|$$ARI|1|2|10
ARM.Set|$$ARI|2|1|1
ARM.Set|$$ARI|2|2|20
ARM.Set|$$ARI|3|1|2
ARM.Set|$$ARI|3|2|30
SET|$$COL|1
ARM.Sort|$$ARI|$$COL
ARM.Get|$$ARI|1|1|$$VAL
JIV.$$VAL!1|Lab_failed
ARM.Get|$$ARI|3|2|$$VAL
JIV.$$VAL!10|Lab_failed
ARM.End|$$ARI

' Example 2: Sorting a String Array
ARM.New|$$ARR|s
ARM.Redim|$$ARR|3|1
ARM.Set|$$ARR|1|1|C
ARM.Set|$$ARR|2|1|A
ARM.Set|$$ARR|3|1|B
SET|$$COL|1
ARM.Sort|$$ARR|$$COL
ARM.Get|$$ARR|1|1|$$VAL
JIV.$$VAL!A|Lab_failed
ARM.End|$$ARR

Remarks
- Sorts rows based on the values in the specified column; other columns move with their rows.
- Uses ascending order; no descending option (reverse after sorting if needed).
- Works with all data types; strings are sorted lexicographically.
- Useful for ranking game scores, organizing data tables, or preprocessing matrices.
- Complexity depends on the sorting algorithm (typically O(n log n) for n rows).

Limitations
- $$COL must be within bounds; out-of-bounds values cause errors.
- No multi-column sorting or custom comparators.
- Large arrays may experience performance delays.

See Also
ARM.Get, ARM.Set, ARM.Reverse

ARM - Array Operations

ARM - Array Operations

Array Operations Overview

Previous Top Next