ArraySort

Performs an in-place sort of arrays with one or two dimensions.

Syntax:

ArraySort( array, [options, [sort-column, [start-sub, [end-sub]]]] )

Parameters:

(a) array: array to sort.

(i) options: [optional] specifies sort direction and comparison method. See below.

(i) sort-column: [optional] subscript of column to sort on for two-dimensional arrays. The default is 0.

(i) start-sub: [optional] subscript of first row to include in sort. The default is 0.

(i) end-sub: [optional] subscript of last row to include in sort. The default is ArrInfo( array, 1 ) - 1

Returns:

(i)  returns 1.

Important: this function performs an in-place sort of an array. 'ArraySort' does not make any promises about preserving the existing order of rows with the same sort column value. It simply sorts exclusively on the content of the user indicated array dimension in an efficient manner.

Options

One directional option can be combined with one sort comparison method option using the WIL bitwise OR(|) operator.

The function sorts using "WIL relational operator" style comparisons when an optional sort comparison method is not indicated.  WIL relational operator comparisons may produce an unexpected sort order when sorting an array with mixed numeric and string elements.  This is because numeric elements will be treated as numbers when compared to numbers and will be treated as strings when compared to non-numeric strings.

Notes on the default WIL relational operator array sort:

1. Arrays sorted using the default comparison method may not be suitable for fast binary searches when the array contains both numeric and string elements.

2. Arrays of numeric elements are numerically sorted, then negative numeric values are sorted before positive numeric values (when performing the default ascending sort): -1,0,1,+1,1.0,1.1

3. Arrays of string elements are "word sorted", also known as a "dictionary sort".

4. A word value is any value that contains any non numeric value:
   a. Numeric values with trailing space are treated as words: "123 "
   b. Numeric values with thousands separator are treated as words: "1,234"

5. Lowercase words are sorted before uppercase words: a,A,b,B,c,C

6. Decimal separators, plus signs, the letter 'E', and minus signs are treated as numeric when associated with elements that otherwise contain only digits.

Note1: The @STRINGSORT or @LOGICALSORT options are the best choice when sorting an array of mixed numeric and string elements for later fast searching with the ArraySearch function.

Multidimensional arrays in WinBatch use 'Row Major' format. For Example: arrMyArray[ row_index , column_index ]

Note 2: This function can not be used on arrays containing embedded arrays or maps.

Example:

; Ascending Sort First Column of a Single Dimension Array
strList = 'a b c A B C 1 0 -1'
outfile = DirScript() : 'ArraySort.txt'
;Create an array to sort
arrList = Arrayize( strList, ' ' )
; Sort the array using an ascending intuitive sort
ArraySort( arrList, @ASCENDING, 0, 0, ArrInfo(arrList,1)-1 )
; Write Results out to a file
ArrayFilePut( outfile, arrList )
; Display results
Run( outfile, '' )
; Clean up
FileDelete( outfile )
Exit

; Descending Sort Third Column of a Two Dimensional Array
strCsv = 'column1,column2,column3,column4' : @CRLF
strCsv = strCsv : 'r1c1,r1c2,r1c3,r1c4': @CRLF
strCsv = strCsv : 'r2c1,r2c2,r2c3,r2c4': @CRLF
strCsv = strCsv : 'r3c1,r3c2,r3c3,r3c4'
csvfilein = DirScript(): 'TestIn.csv'
csvfileout = DirScript(): 'TestOut.csv'
FilePut( csvfilein, strCsv )
arrCsv = ArrayFileGetCSV(csvfilein, 0 )
headingrow = 1
ArraySort( arrCsv, @DESCENDING, 2, headingrow, ArrInfo(arrCsv,1)-1  ) ; skips heading row
ArrayFilePutCSV(csvfileout, arrCsv)
Run('notepad.exe',csvfileout)

See Also:

Arrays, ArrayFileGet, ArrayFileGetCsv, ArrayFilePut, ArrayFilePutCsv, ArrayFromStr, ArrayInsert, ArrayItemize, Arrayize, ArrayLocate, ArrayRedim, ArrayRemove, ArrayReverse, ArraySearch, ArraySwapElements, ArrayToStr, ArrDimension, ArrInfo, ArrInitalize, Drop, ItemSort