|
<< 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.Sort
Sorts a two-dimensional array by a specified column in ascending order.
Intention
The ARM.Sort command sorts the rows of a two-dimensional (2D) array based on the values in a specified column, always in ascending order, reorganizing the entire grid. This is a powerful command for data organization in MiniRobotLanguage, enabling developers to order data for analysis, display, or processing, such as sorting scores on a game leaderboard (e.g., ordering rows by player points on a chessboard-like grid), arranging pixel intensities in an image grid, or organizing matrix data 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.Sort provides flexibility for applications requiring structured data reordering, such as games, image processing, or data analysis tasks. The sort respects the array’s data type (strings, integers, or floating-point numbers), ensuring consistent ascending ordering (e.g., A–Z for strings, 1–9 for numbers), and the array’s handle and column structure remain intact. For descending order, use ARM.Sort followed by ARM.Reverse if needed.
Illustration:
🔀 2D Array Sorting: A chessboard-like grid with handle $$ARR, originally [King, 100; Queen, 200; Pawn, 150], is sorted by column 2 (scores) in ascending order, becoming [King, 100; Pawn, 150; Queen, 200] in a 3x2 structure.
🔑 Handle: $$ARR remains valid, with rows reordered in ascending order based on the specified column.
Syntax
ARM.Sort|$$ARR|$$COL
Parameter Explanation
P1 - $$ARR - (Variable, 5 characters max)
The handle of the 2D array to sort. This variable, limited to 5 characters, must contain a valid handle created by ARM.New, and it remains valid after the operation.
P2 - $$COL - (Variable, 5 characters max)
The column index by which to sort the array. This must be a positive integer within the array’s column bounds (e.g., 1 to the number of columns, as retrieved by ARM.GetDims), representing the sorting key in the grid (e.g., column 2 for scores on a leaderboard).
Examples
'***********************************
' ARM.Sort - Sample 1: Sorting a Game Leaderboard (Ascending)
'***********************************
ARM.New|$$ARR
ARM.Set|$$ARR|1|1|King
ARM.Set|$$ARR|1|2|100
ARM.Set|$$ARR|2|1|Queen
ARM.Set|$$ARR|2|2|200
ARM.Set|$$ARR|3|1|Pawn
ARM.Set|$$ARR|3|2|150
DBP.2D Array (chessboard-like) before sorting: [King, 100; Queen, 200; Pawn, 150] (3x2)
SET|$$COL|2
ARM.Sort|$$ARR|$$COL
DBP.2D Array after sorting: [King, 100; Pawn, 150; Queen, 200] (3x2, by score ascending)
ARM.End|$$ARR
'
'***********************************
' ARM.Sort - Sample 2: Sorting Pixel Intensities in an Image (Ascending, Then Descending with Reverse)
'***********************************
ARM.New|$$ARR|f
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) before sorting: [1.5, -2.7; 3.14, 0.5] (2x2)
SET|$$COL|1
ARM.Sort|$$ARR|$$COL
DBP.2D Array after ascending sort: [-2.7, 1.5; 0.5, 3.14] (2x2, by first column ascending)
ARM.Reverse|$$ARR
DBP.2D Array after reverse (descending): [3.14, 0.5; 1.5, -2.7] (2x2, by first column descending)
ARM.End|$$ARR
'
'***********************************
' ARM.Sort - Sample 3: Sorting a Matrix by Values (Ascending)
'***********************************
ARM.New|$$ARR|i
ARM.Set|$$ARR|1|1|100
ARM.Set|$$ARR|1|2|200
ARM.Set|$$ARR|2|1|150
ARM.Set|$$ARR|2|2|50
DBP.2D Array (matrix) before sorting: [100, 200; 150, 50] (2x2)
SET|$$COL|2
ARM.Sort|$$ARR|$$COL
DBP.2D Array after sorting: [150, 50; 100, 200] (2x2, by second column ascending)
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.Sort. Use ARM.Validate to ensure the handle is valid if there’s any doubt, and ARM.GetDims to check column bounds for the sort column.
- The column index ($$COL) must be within the array’s column bounds; out-of-bounds indices will result in errors. Ensure $$COL is a positive integer starting from 1, matching the grid structure (e.g., 2 for the second column of a leaderboard).
- Sorting is always performed in ascending order (e.g., A–Z for strings, 1–9 for numbers). For descending order, apply ARM.Sort followed by ARM.Reverse, as shown in the examples. Sorting respects the array’s data type (strings, integers, or floating-point, as specified during ARM.New).
- The performance of sorting a 2D array in MRL, due to its emulation within a one-dimensional structure, may introduce significant overhead, especially for large arrays or many rows, as it requires reordering all rows based on the specified column. However, this is typically manageable for most practical use cases, such as small leaderboards or pixel grids, though sorting very large arrays should be optimized (e.g., batching or using alternative sorting strategies if performance is critical).
- This command is ideal for data organization in applications like games (sorting leaderboards), image processing (ordering pixel data), or scientific computing (arranging matrix rows for analysis).
Limitations
- The array handle variable must not exceed 5 characters and must be valid; attempting to sort an invalid handle may cause runtime errors.
- The column index ($$COL) must be within bounds, as determined by ARM.GetDims; out-of-bounds indices will result in errors or undefined behavior.
- Sorting very large 2D arrays or performing frequent sorts may impact performance due to the emulation and data reordering in MRL, though this is typically acceptable for small to medium-sized arrays like game leaderboards or pixel grids. For large arrays, consider optimizing by sorting subsets or using external sorting algorithms if needed.
- 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