|
<< 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.Find
Searches a two-dimensional array for the first occurrence of a specified value, returning its row and column position.
Intention
The ARM.Find command searches a two-dimensional (2D) array for the first occurrence of a specified value, returning its row and column position if found, or indicating no match if the value is not present. This is a key command for data location in MiniRobotLanguage, enabling developers to locate specific elements in a grid for tasks like finding a game piece on a board (e.g., locating a king on a chessboard-like grid), identifying pixel values in an image grid, or pinpointing values in a matrix for scientific 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.Find provides an efficient way to navigate this grid, respecting the array’s data type (strings, integers, or floating-point numbers). It’s particularly useful in applications requiring data retrieval, such as games, image processing, or data analysis, where identifying the position of a specific value is critical. The search starts from the top-left corner (row 1, column 1) and proceeds row by row, returning the first match or no match if the value isn’t found, as shown in the examples.
Illustration:
🔍 2D Array Search: A chessboard-like grid with handle $$ARR [A1, A2; A2, A3] (2x2) is searched for “A2”, returning the first occurrence at position [1,2].
🔑 Handle: $$ARR remains valid, with row and column positions stored in $$RO1 and $$COL for further processing.
Syntax
ARM.Find|$$ARR|$$VAL|$$ROW|$$COL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to search. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$VAL - (Variable, 5 characters max)
The value to search for in the 2D array. This must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); attempting to search for an incompatible type (e.g., a number in a string array) will result in an error.
P3 - $$ROW - (Variable, 5 characters max)
The variable where the row position of the first occurrence will be stored. This must be a valid variable name, limited to 5 characters. If the value is found, $$ROW contains the row index (starting from 1); if not found, $$ROW is set to 0.
P4 - $$COL - (Variable, 5 characters max)
The variable where the column position of the first occurrence will be stored. This must be a valid variable name, limited to 5 characters. If the value is found, $$COL contains the column index (starting from 1); if not found, $$COL is set to 0.
Examples
'--------------------------------------------------------
' ARM.Find - Sample 1: Finding Multiple Occurrences of a String in a Game Board
'--------------------------------------------------------
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
' Set values with multiple “A2”
ARM.Set|$$ARR|1|1|A1
ARM.Set|$$ARR|1|2|A2
ARM.Set|$$ARR|2|1|A2
ARM.Set|$$ARR|2|2|A3
DBP.2D Array (chessboard-like) content: [A1, A2; A2, A3] (2x2)
' Find “A2”, should return first occurrence (1,2)
SET|$$VAL|A2
ARM.Find|$$ARR|$$VAL|$$RO1|$$COL
JIV.$$RO1!1|Lab_failed
JIV.$$COL!2|Lab_failed
' Find “A3”
SET|$$VAL|A3
ARM.Find|$$ARR|$$VAL|$$RO1|$$COL
JIV.$$RO1!2|Lab_failed
JIV.$$COL!2|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Find - Sample 2: Finding a Numeric Value in a Matrix
'--------------------------------------------------------
ARM.New|$$ARR|i
ARM.Redim|$$ARR|3|2
' Set values with multiple 5s
ARM.Set|$$ARR|1|1|1
ARM.Set|$$ARR|1|2|5
ARM.Set|$$ARR|2|1|3
ARM.Set|$$ARR|2|2|5
ARM.Set|$$ARR|3|1|7
ARM.Set|$$ARR|3|2|9
DBP.2D Array (matrix) content: [1, 5; 3, 5; 7, 9] (3x2)
' Find 5, should return first occurrence (1,2)
SET|$$VAL|5
ARM.Find|$$ARR|$$VAL|$$RO1|$$COL
JIV.$$RO1!1|Lab_failed
JIV.$$COL!2|Lab_failed
ARM.End|$$ARR
'
'--------------------------------------------------------
' ARM.Find - Sample 3: Finding a Floating-Point Value in a Pixel Grid (No Match)
'--------------------------------------------------------
ARM.New|$$ARR|f
ARM.Redim|$$ARR|2|2
' Set values
ARM.Set|$$ARR|1|1|1.5
ARM.Set|$$ARR|1|2|-2.7
ARM.Set|$$ARR|2|1|3.14
ARM.Set|$$ARR|2|2|0.5
DBP.2D Array (pixel grid) content: [1.5, -2.7; 3.14, 0.5] (2x2)
' Try to find 4.0 (not present)
SET|$$VAL|4.0
ARM.Find|$$ARR|$$VAL|$$RO1|$$COL
JIV.$$RO1!0|Lab_failed
JIV.$$COL!0|Lab_failed
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.Find. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to understand the array’s structure for search optimization.
- The search value ($$VAL) must match the array’s data type (strings, integers, or floating-point, as specified during ARM.New); attempting to search for an incompatible type (e.g., a number in a string array) will result in an error. Use ARM.GetType to verify the array’s type if unsure.
- The search begins from the top-left corner (row 1, column 1) and proceeds row by row, returning the first occurrence’s position in $$ROW and $$COL (1-based indices). If the value isn’t found, both $$ROW and $$COL are set to 0, as shown in Sample 3, allowing for easy error handling or continuation with ARM.FindNext for subsequent occurrences.
- The performance of finding a value in a 2D array in MRL, due to its emulation within a one-dimensional structure, is generally efficient for small to medium-sized arrays. However, for very large arrays or frequent searches, performance may degrade linearly with array size, though this is typically manageable for most practical use cases, such as locating game pieces or pixel values. For large arrays, consider optimizing searches by narrowing the search area or using ARM.FindNext for iterative searches.
- This command is ideal for data location in applications like games (finding board positions), image processing (identifying pixel values), or scientific computing (locating matrix elements).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to find in an invalid handle may cause runtime errors.
- The search value ($$VAL) must match the array’s data type; type mismatches will cause errors, requiring type consistency as set during ARM.New.
- The variables for row ($$ROW) and column ($$COL) must be valid variable names, limited to 5 characters; invalid variable names may result in errors or undefined behavior.
- Searching very large 2D arrays may introduce performance overhead due to the linear search approach in MRL, though this is typically acceptable for most applications like game boards or small matrices. For large arrays with multiple occurrences, use ARM.FindNext to continue searching after the first match, as shown in the context of multiple “A2” occurrences in Sample 1.
- 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