|
<< 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.SumRow
Calculates the sum of values in a specified row of a two-dimensional array, storing the result in a variable.
Intention
The ARM.SumRow command computes the sum of all values in a specified row of a two-dimensional (2D) array and stores the result in a variable, providing a quick aggregation for numeric data analysis. This is a valuable command for numerical operations in MiniRobotLanguage, enabling developers to calculate row totals for tasks like scoring rows on a game board (e.g., summing points in a chessboard-like grid), analyzing pixel intensities in an image grid, or aggregating matrix rows 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.SumRow supports only numeric arrays (integers or floating-point), returning an error for string arrays. It’s particularly useful in applications requiring row-based calculations, such as games, image processing, or data analysis, where summing values helps evaluate states, compute averages, or derive insights. The operation preserves the array’s handle and structure but requires the row index to be within bounds and the array to be numeric, as shown in the examples.
Illustration:
➕ 2D Array Row Summation: A chessboard-like grid with handle $$ARI, containing [1, 2; 3, 4] (2x2), has row 1 summed to 3 (1 + 2), stored in $$SUM.
🔑 Handle: $$ARI remains valid, with the row sum available for further processing.
Syntax
ARM.SumRow|$$ARR|$$ROW|$$SUM
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to sum. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it must be a numeric array (integers or floating-point); string arrays will result in an error. The handle remains valid after the operation.
P2 - $$ROW - (Variable, 5 characters max)
The row index to sum. This must be a positive integer within the array’s row bounds (e.g., 1 to the number of rows, as retrieved by ARM.Count or ARM.GetDims), representing the vertical position in the grid (e.g., row 1 on a chessboard).
P3 - $$SUM - (Variable, 5 characters max)
The variable where the sum of the specified row will be stored. This must be a valid variable name, limited to 5 characters, and will contain a numeric value (integer or floating-point, matching the array’s type) representing the sum of all values in the row.
Examples
'--------------------------------------------------------
' ARM.SumRow - Sample 1: Summing Rows in an Integer Array (Game Board Scores)
ARM.New|$$ARI|i
ARM.Redim|$$ARI|2|2
' Set values
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.SumRow|$$ARI|1|$$SUM
JIV.$$SUM!3|Lab_failed
ARM.SumRow|$$ARI|2|$$SUM
JIV.$$SUM!7|Lab_failed
ARM.End|$$ARI
'
'--------------------------------------------------------
' ARM.SumRow - Sample 2: Summing Rows in a Floating-Point Array (Pixel Intensities)
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|2
' Set values
ARM.Set|$$ARF|1|1|1.5
ARM.Set|$$ARF|1|2|-2.7
ARM.Set|$$ARF|2|1|3.14
ARM.Set|$$ARF|2|2|0.5
ARM.SumRow|$$ARF|1|$$SUM
JIV.$$SUM!-1.2|Lab_failed
ARM.SumRow|$$ARF|2|$$SUM
JIV.$$SUM!3.64|Lab_failed
ARM.End|$$ARF
'
'--------------------------------------------------------
' ARM.SumRow - Sample 3: Verifying Row Sums with Error Handling for String Array (Invalid Type)
ARM.New|$$ARR|s
ARM.Redim|$$ARR|2|2
' Set values
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.SumRow|$$ARR|1|$$SUM
JIF|$$ERROR|==|1|Lab_failed
ARM.End|$$ARR
'
Remarks
- The array handle must be stored in a variable with a maximum length of 5 characters (e.g., $$ARI, $$ARF) and must be valid (created by ARM.New) before using ARM.SumRow. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetType to confirm it’s a numeric array (type “i” or “f”), as string arrays will cause an error, as shown in Sample 3.
- The row index ($$ROW) must be within the array’s row bounds; out-of-bounds indices will result in errors. Use ARM.Count or ARM.GetDims to determine valid row indices, ensuring they are positive integers starting from 1, as shown in the examples with verification using JIV.
- The sum is calculated as a numeric value matching the array’s type (integer for “i”, floating-point for “f”), stored in $$SUM. For floating-point arrays, the result may include decimal precision, while integer arrays return whole numbers, as demonstrated in the samples.
- The performance of summing a row 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 summations, performance may scale linearly with the number of columns in the row, though this is typically manageable for most practical use cases, such as calculating game scores or pixel totals. For large arrays, consider optimizing by summarizing subsets or caching results if performance is critical.
- This command is ideal for numerical aggregation in applications like games (summing row scores), image processing (calculating row intensities), or scientific computing (aggregating matrix row values).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to sum a row in an invalid handle may cause runtime errors.
- The array must be of type “i” (integer) or “f” (floating-point); attempting to use ARM.SumRow on a string array will result in an error, as shown in Sample 3, requiring type validation with ARM.GetType.
- The row index ($$ROW) must be within bounds; out-of-bounds indices will result in errors or undefined behavior, necessitating bounds checking with ARM.Count or ARM.GetDims.
- Summing very large rows or performing frequent summations on large arrays may introduce performance overhead due to the linear scan in MRL, though this is typically acceptable for most applications like game boards or small matrices. For large arrays, consider optimizing by summarizing subsets or caching results 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
• ARM.Sum