; FAS_Sort2DArray
; ---------------
; Index based sorting of a 2D array by one or more columns
; Returns the sorting index as a DllStruct/array of integers
; FAS_Sort2DArray( _
;     $aArray, _           ; The 2D array to be sorted by index
;                          ; Or 0/"" if array is stored in VB code, 0) in docu
;     $aCompare, _         ; Info about columns used in sorting, see 1) in docu
;     $bDelArray = 1, _    ; Delete array (stored as global array) in VB code
;     $bSortByIndex = 0, _ ; Sort duplicates by array index (asc), 2) in docu
;     $bDuplicates = 0, _  ; Information about duplicate rows, 3) in docu
;     $bProgress = 0 )     ; Calculate progress info while sorting


; 0) $aArray parameter
; Use $aArray = 0/"" to sort an array that is stored as a global variable in compiled code. If the array is
; stored as a global in compiled code, it's unnecessary to transfer array from AutoIt code to compiled code.
; Especially if it's a large array (more than one million elements), much time can be saved.


; 1) $aCompare parameter
; The $aCompare parameter contains information about the columns in $aArray to be used for sorting. The generel
; format of $aCompare is a 2D array with one row of information for each column that's included in the sorting.
;
; The purpose of using multiple columns in the sorting is to be able to handle duplicates. If there are dupli-
; cates in the first sorting column, the duplicates can be sorted by the second sorting column. If there are
; duplicates in the first and second sorting columns, the duplicates can be sorted by third sorting column.
;
; Each row in $aCompare consists of 3 fields: The zero based column index, an indication of whether the column
; should be sorted as numbers or strings, and an indication of ascending or descending sorting order.
;
; In the example below an array is sorted by the three first columns. The second column is used only on dupli-
; cates in first column. The third column is used only on duplicates in both first and second columns.
;
; Local $aCompare = [ _
;     [ 0, 1, 0 ], _ ; Column 0: Compare as strings, ascending order
;     [ 1, 0, 0 ], _ ; Column 1: Compare as numbers, ascending order
;     [ 2, 0, 0 ] ]  ; Column 2: Compare as numbers, ascending order
;
; The second field in each row in $aCompare indicates whether the column should be sorted as numbers or strings.
; 0 or "" means that the column is sorted as numbers. Everything else means that it's sorted as strings.
;
; The third field indicates whether the column should be sorted in ascending or descending order. 0 or "" means
; that the column is sorted in ascending order. Everything else means that it's sorted in descending order.
;
; Because of default values in an array, the example above can be written slightly shorter this way:
;
; Local $aCompare = [ _
;     [ 0, 1 ], _ ; Column 0: Compare as strings, ascending order
;     [ 1    ], _ ; Column 1: Compare as numbers, ascending order
;     [ 2    ] ]  ; Column 2: Compare as numbers, ascending order
;
;
; If an array is to be sorted by multiple columns and all columns are sorted as numbers in ascending order,
; $aCompare can be specified as a 1D array:
;
; Local $aCompare = [ 1, 2, 3 ]
;
; Here an array is sorted by second, third and fourth column as numbers in ascending order.
;
;
; If an array is to be sorted by a single column as numbers in ascending order $aCompare can be specified
; simply as the column index:
;
; Local $aCompare = 1 ; Sort an array by second column as numbers in ascending order.


; 2) $bSortByIndex parameter
; If there are still duplicates when the rows have been compared by all sorting columns, the rows can be further
; compared by array index. This can be done by setting $bSortByIndex = 1. Because the array indices are unique
; integers this will result in a unique sorting and eliminate the rest of the duplicates.
;
; Sorting by $bSortByIndex is always in ascending order. The rest of the duplicates will be inserted in the sort-
; ing index as a continuous group with the row with the smallest array index as the first row and the row with the
; largest array index as the last row.


; 3) $bDuplicates parameter
; Set $bDuplicates = 1 to collect information about duplicates during the sorting. The information collected is the
; number of duplicates as well as the value of duplicates in the sorting columns and the array indices of duplicates.
