MiniRobotLanguage (MRL)
ARR.Sort
Sort an String-Array with Tag-Along Array
Sort a specified array in ascending or descending order, with a tag-along array sorted in parallel.
Intention
The ARR.Sort command sorts a specified array as a string array in ascending (default) or descending order, with a tag-along array sorted in parallel to maintain correspondence between elements. The tag-along array is automatically initialized with string indices ("0", "1", ...) if it is not dimensioned or has a mismatched size; otherwise, its existing content is preserved and sorted. The sorting behavior can be customized using an options string specifying direction (A or D) and case sensitivity (C). A status code (1 for success, 0 for failure) is returned on the Top of Stack (TOS). All array elements are stored as strings.
Can not be used for INT or FP-Arrays!
•Array Restriction: The sort array and tag-along array must be different (0-32).
•Sort Options: Supports ascending (A) or descending (D) order and case-insensitive (C) sorting.
•Return Value: A status code (1 for success, 0 for failure) is pushed to the TOS.
•Tag-Along Array: The tag-along array is initialized with string indices if not dimensioned or mismatched; otherwise, its content is preserved and sorted in sync with the sort array.
Schematic (Array Sorting)
Sort Array: ["banana", "apple", "cherry"]
Tag-Along Array: ["0", "1", "2"] (auto-initialized if not set)
Command: ARR.Sort|0|1|A
Result Sort Array: ["apple", "banana", "cherry"]
Result Tag-Along Array: ["1", "0", "2"]
TOS: 1 (success)
Syntax
ARR.Sort|P1|P2|P3
Parameter Explanation
•P1 - Sort Array Number: The array number (0-32) to sort.
•P2 - Tag-Along Array Number: The array number (0-32) for the tag-along array (must be different from P1).
•P3 - Options: A string containing A (ascending, default), D (descending), and/or C (case-insensitive).
Examples
'***********************************
' Example 1: Sort strings in ascending order
'***********************************
ARR.Clr|0
ARR.Clr|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
ARR.Sort|0|1|A
' Array 0 contains: ["apple", "banana", "cherry"]
' Array 1 contains: ["1", "0", "2"]
ARR.Get|0|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 2: Sort strings in descending order with tag-along
'***********************************
ARR.Clr|0
ARR.Clr|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
ARR.Set|1|0|a
ARR.Set|1|1|b
ARR.Set|1|2|c
ARR.Sort|0|1|D
' Array 0 contains: ["cherry", "banana", "apple"]
' Array 1 contains: ["c", "a", "b"]
ARR.Get|1|0|$$RET
MBX.$$RET
ENR.
'***********************************
' Example 3: Sort strings with tag-along array initialization
'***********************************
ARR.Clr|0
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
ARR.Sort|0|1|A
' Array 0 contains: ["apple", "banana", "cherry"]
' Array 1 contains: ["1", "0", "2"]
ARR.Get|1|0|$$RET
MBX.$$RET
ENR.
'============================================================
' TEST SCRIPT for ARR.Sort
' Purpose: Verify ARR.Sort functionality with JIV for automated checks.
' Tests ascending sort, descending sort, case-insensitive sort, tag-along
' preservation, tag-along initialization, different array numbers, and edge cases.
'============================================================
' Initialize counters
$$PAS=0
$$FAI=0
STS.CLEAR
PRT. ===================================================
PRT. Test 1.1: Sort strings in ascending order (Array 0, Tag Array 1)
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
PRT.----------------
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Sort|0|1|A
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=apple
JIV.$$RET!$$EXP|Lab_Error1
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next1
:Lab_Error1
GSB.Test
'-----------------------------------------------------------
:Lab_Next1
PRT.########################################################
PRT.########################################################
PRT. Test 1.2: Sort strings in descending order with tag-along preservation
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
ARR.Set|1|0|a
ARR.Set|1|1|b
ARR.Set|1|2|c
PRT.----------------
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Sort|0|1|D
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|1|0|$$RET
$$EXP=c
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error2
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next2
:Lab_Error2
GSB.Test
'-----------------------------------------------------------
:Lab_Next2
PRT.########################################################
PRT.########################################################
PRT. Test 1.3: Case-insensitive string sort
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
ARR.Set|0|0|Banana
ARR.Set|0|1|apple
ARR.Set|0|2|CHERRY
PRT.----------------
ARR.Show|0
PRT.----------------
ARR.Sort|0|1|C
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=apple
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error3
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next3
:Lab_Error3
GSB.Test
'-----------------------------------------------------------
:Lab_Next3
PRT.########################################################
PRT.########################################################
PRT. Test 1.4: Sort strings with tag-along initialization
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
ARR.Set|0|2|cherry
PRT.----------------
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Sort|0|1|A
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|1|0|$$RET
$$EXP=1
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error4
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next4
:Lab_Error4
GSB.Test
'-----------------------------------------------------------
:Lab_Next4
PRT. Test 1.5: Sort strings in descending order, case-insensitive
STS.CLEAR
ARR.Clr|0
ARR.Clm|1
ARR.Set|0|0|Banana
ARR.Set|0|1|apple
ARR.Set|0|2|CHERRY
PRT.----------------
ARR.Show|0
PRT.----------------
ARR.Sort|0|1|DC
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=CHERRY
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error5
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next5
:Lab_Error5
GSB.Test
'-----------------------------------------------------------
:Lab_Next5
PRT. Test 1.6: Sort using different array numbers (Array 10, Tag Array 20)
STS.CLEAR
ARR.Clr|10
ARR.Clr|20
ARR.Set|10|0|zebra
ARR.Set|10|1|apple
ARR.Set|10|2|monkey
ARR.Set|20|0|x
ARR.Set|20|1|y
ARR.Set|20|2|z
PRT.----------------
ARR.Show|10
ARR.Show|20
PRT.----------------
ARR.Sort|10|20|A
ARR.Show|10
ARR.Show|20
PRT.----------------
ARR.Get|10|0|$$RET
$$EXP=apple
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error6
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next6
:Lab_Error6
GSB.Test
'-----------------------------------------------------------
:Lab_Next6
PRT. Test 1.7: Empty array handling
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
PRT.----------------
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Sort|0|1|A
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error7
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next7
:Lab_Error7
GSB.Test
'-----------------------------------------------------------
:Lab_Next7
PRT. Test 1.8: Invalid array number (sortArrayNum > 32)
STS.CLEAR
ARR.Clm|0
ARR.Clm|1
ARR.Set|0|0|banana
ARR.Set|0|1|apple
PRT.----------------
ARR.Show|0
PRT.----------------
ARR.Sort|33|1|A
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=banana
JIV.TRIM($$RET)!TRIM($$EXP)|Lab_Error8
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next8
:Lab_Error8
GSB.Test
'-----------------------------------------------------------
:Lab_Next8
PRT. Test 1.9: Same array number for sort and tag-along
STS.CLEAR
ARR.Clr|0
ARR.Set|0|0|banana
ARR.Set|0|1|apple
PRT.----------------
ARR.Show|0
PRT.----------------
ARR.Sort|0|0|A
ARR.Show|0
ARR.Show|1
PRT.----------------
ARR.Get|0|0|$$RET
$$EXP=banana
JIV.$$RET!$$EXP|Lab_Error9
PRT. -> PASS
VIC.$$PAS
JMP.Lab_Next9
:Lab_Error9
GSB.Test
'-----------------------------------------------------------
:Lab_Next9
PRT. ===================================================
PRT. TEST SUMMARY
PRT. ===================================================
CAL.$$TOT=$$PAS+$$FAI
$$MSG=Total Tests: $$TOT
PRT.$$MSG
$$MSG=Passed: $$PAS
PRT.$$MSG
$$MSG=Failed: $$FAI
PRT.$$MSG
JIV.$$FAI=0|Lab_Success
$$MSG=FAILURE: $$FAI of $$TOT tests failed.
MBX.$$MSG|Test Result|16
JMP.Lab_End
:Lab_Success
MBX.SUCCESS: All tests passed!|Test Result|64
:Lab_End
ENR.
:Test
$$MSG= -> FAIL - Result: $$RET (exp: $$EXP)
PRT.$$MSG
VIC.$$FAI
RET.
Remarks
- The command sorts a specified array, with a tag-along array sorted in parallel. The tag-along array is initialized with string indices if not dimensioned or mismatched; otherwise, its content is preserved.
- Use ARR.Swap to move another array to a desired position for sorting.
- Options are case-insensitive (e.g., "D" or "d").
- The TOS returns 1 for success, 0 for failure (e.g., invalid array number).
- Empty arrays return success (TOS = 1) with no changes.
Limitations
- Array numbers are limited to 0–32, and the sort and tag-along arrays must be different.
- Exactly three parameters are required; fewer or more result in no operation.
- No support for multidimensional arrays.
See also:
• ARR.Set
• ARR.Get
• ARR.Clr
• ARR.Swap
• ARR.Dim