Sorts elements in an array in ascending or descending order.
Syntax
ASORT(ArrayName [, nStartElement [, nNumberSorted [, nSortOrder]]])
Returns
Numeric
Arguments
ArrayName
Specifies the name of the array to sort.
nStartElement
Specifies the starting element of the sort. If you omit nStartElement, the array is sorted starting with the first array element by default. If the array is one-dimensional, the sort includes nStartElement. If the array is two-dimensional, the starting element nStartElement determines both the row where the sort begins and the column that determines the sort order of the rows.
Note You can refer to an element in a two-dimensional array in one of two ways. The first method uses two subscripts to specify the row and column position of the element in the array; the other method uses an element number. This function and others that manipulate two-dimensional arrays require element numbers (in ASORT( ) the numeric expressions nStartElement and nNumberSorted). You can use AELEMENT( ) to return the element number from row and column subscripts in a two-dimensional array.
The following example illustrates that the starting element nStartElement determines how the rows in a two-dimensional array are sorted. A small array named gaArray is created and sorted twice. The first sort begins with the first element of gaArray; the rows are sorted based on the values contained in the first column of the array. The second sort begins with the fourth element of gaArray; the rows are sorted based on the values contained in the second column.
The first sort begins with the first row. The second sort begins with the second row. You can use DISPLAY MEMORY to display the contents of the array; in these examples tables are used to graphically display the results of the sorts.
These commands create the array named gaArray:
DIMENSION gaArray(3,2)
gaArray(1) = 'G'
gaArray(2) = 'A'
gaArray(3) = 'C'
gaArray(4) = 'Z'
gaArray(5) = 'B'
gaArray(6) = 'N'
gaArray looks like this:
| Column 1 | Column 2 | |
| Row 1 | G | A |
| Row 2 | C | Z |
| Row 3 | B | N |
The array is then sorted by ASORT( ) starting with the first element (1,1) in the array. The elements in the first column are placed in ascending order by rearranging the rows of the array.
=ASORT(gaArray,1)
Note the new order of the rows:
| Column 1 | Column 2 | |
| Row 1 | B | N |
| Row 2 | C | Z |
| Row 3 | G | A |
The array is then sorted starting with the fourth element (2,2) in the array. The elements in the second column are placed in order by rearranging the array rows.
=ASORT(gaArray,4)
Note the difference in the order of the rows:
| Column 1 | Column 2 | |
| Row 1 | B | N |
| Row 2 | G | A |
| Row 3 | C | Z |
nNumberSorted
Specifies the number of elements that are sorted in a one-dimensional array, or the number of rows that are sorted in a two-dimensional array. For example, if the array is one-dimensional and nStartElement is 2, indicating that the sort starts with the second array element, and nNumberSorted is 3, indicating that the sort should include three elements, the second, third and fourth array elements are sorted. If nNumberSorted is –1 or is omitted, all array elements from the starting element nStartElement through the last element in the array are sorted.
If the array is two-dimensional, nNumberSorted designates the number of rows to sort, beginning with the row containing the starting element nStartElement. For example, if nStartElement is 2 and nNumberSorted is 3, the row containing the second array element and the following two rows are sorted. If nNumberSorted is –1 or is omitted, all array rows beginning with the row containing the starting element nStartElement through the last array row are sorted.
nSortOrder
Specifies the sort order (ascending or descending) for the elements in the array. By default, array elements are sorted in ascending order. If nSortOrder is 0 or is omitted, the array elements are sorted in ascending order. If nSortOrder is 1 or any nonzero value, the array elements are sorted in descending order.
Remarks
All elements included in the sort must be of the same data type. One-dimensional arrays are sorted by their elements; two-dimensional arrays are sorted by their rows. When a two-dimensional array is sorted, the order of the rows in the array is changed so that the elements in a column of the array are in ascending or descending order.
If the sort is successful, 1 is returned; otherwise –1 is returned.