|
<< 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.Sum
Calculates the sum of all elements in a two-dimensional array, storing the result in a variable.
Intention
The ARM.Sum command computes the sum of all elements in a two-dimensional (2D) array and stores the result in a specified variable, providing a total aggregation for numeric data analysis. This is a valuable command for numerical operations in MiniRobotLanguage, enabling developers to calculate the total of all values for tasks like summing scores across a game board (e.g., aggregating points on a chessboard-like grid), computing total pixel intensities in an image grid, or aggregating all matrix values 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.Sum supports only numeric arrays (integers or floating-point), returning an error for string arrays. It’s particularly useful in applications requiring overall numerical summarization, such as games, image processing, or data analysis, where understanding the total value helps evaluate states, compute averages, or derive insights. The operation preserves the array’s handle and structure but requires the array to be numeric, as shown in the examples.
Illustration:
➕ 2D Array Total Summation: A chessboard-like grid with handle $$ARI, containing [1, 2; 3, 4] (2x2), has all elements summed to 10 (1 + 2 + 3 + 4), stored in $$SUM.
🔑 Handle: $$ARI remains valid, with the total sum available for further processing.
Syntax
ARM.Sum|$$ARR|$$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 - $$SUM - (Variable, 5 characters max)
The variable where the sum of all elements 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 total sum of all elements in the array.
Examples
'--------------------------------------------------------
' ARM.Sum - Sample 1: Summing All Elements in an Integer Array (Game 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.Sum|$$ARI|$$SUM
JIV.$$SUM!10|Lab_failed
ARM.End|$$ARI
'
'--------------------------------------------------------
' ARM.Sum - Sample 2: Summing All Elements in a Floating-Point Array (Pixel Intensities)
ARM.New|$$ARF|f
ARM.Redim|$$ARF|2|3
' Set values
ARM.Set|$$ARF|1|1|1.5
ARM.Set|$$ARF|1|2|-2.7
ARM.Set|$$ARF|1|3|3.14
ARM.Set|$$ARF|2|1|0.5
ARM.Set|$$ARF|2|2|2.0
ARM.Set|$$ARF|2|3|-1.8
ARM.Sum|$$ARF|$$SUM
JIV.$$SUM!2.64|Lab_failed
ARM.End|$$ARF
'
'--------------------------------------------------------
' ARM.Sum - Sample 3: Summing All Elements in a Matrix After Modifications
ARM.New|$$ARI|i
ARM.Redim|$$ARI|3|2
' Set values
ARM.Set|$$ARI|1|1|10
ARM.Set|$$ARI|1|2|20
ARM.Set|$$ARI|2|1|30
ARM.Set|$$ARI|2|2|40
ARM.Set|$$ARI|3|1|50
ARM.Set|$$ARI|3|2|60
ARM.Sum|$$ARI|$$SUM
JIV.$$SUM!210|Lab_failed
SET|$$POS|2
ARM.InsertRow|$$ARI|$$POS
ARM.Sum|$$ARI|$$SUM
JIV.$$SUM!210|Lab_failed
ARM.End|$$ARI
'
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.Sum. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetType to confirm the array is numeric (type “i” or “f”), as strings cannot be summed (resulting in an error).
- The sum is stored as a numeric value in $$SUM, matching the array’s data type (integer for type “i”, floating-point for type “f”). This allows for precise calculations in applications like summing game scores, pixel intensities, or matrix values, but care must be taken with floating-point precision, as shown in Sample 2.
- The performance of summing all elements 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, summing may introduce linear performance overhead, though this is typically manageable for most practical use cases, such as calculating game totals or image statistics. For large arrays, consider optimizing by summing subsets or using iterative approaches if performance is critical.
- This command is ideal for numerical aggregation in applications like games (summing total scores), image processing (computing total pixel intensities), or scientific computing (aggregating all matrix values for analysis).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to sum an invalid handle may cause runtime errors.
- The array must be of type “i” (integer) or “f” (floating-point); attempting to sum a string array will result in an error, requiring type validation with ARM.GetType before summing.
- Summing very large 2D arrays may introduce performance overhead due to the linear traversal in MRL, though this is typically acceptable for most applications like game boards or small matrices. For large arrays, consider optimizing summation logic or using incremental updates 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.Avg