Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.
ASORT()
This function sorts the elements in an array. You can sort the entire array or a consecutive subset. In a two-dimensional array, sorting can be based on any column. Either ascending or descending order can be specified. Beginning in VFP 7, you can also perform case-insensitive sorts.
Usage
nSuccess = ASORT( ArrayName [, nStartPos [, nNumElems
[, nSortOrder [, nCase ] ] ] ] )
|
Parameter |
Value |
Meaning |
|
ArrayName |
Name |
The array to be sorted. |
|
nStartPos |
Negative number or omitted |
Sort the entire array. The use of any value other than –1 for this purpose is undocumented. |
|
Numeric |
Begin sorting at the specified element. In a two-dimensional array, sort based on the column containing nStartPos. |
|
|
nNumElems |
0, Negative number, or Omitted |
Sort from nStartPos to the end of the array. Note that inclusion of any value other than –1 for this purpose is undocumented. |
|
Positive number |
For a one-dimensional array, sort the number of elements specified. For a two-dimensional array, sort the number of rows specified. |
|
|
nSortOrder |
0, Negative number, or Omitted |
Sort in ascending order. |
|
Positive number |
Sort in descending order. |
|
|
nCase |
0 or Omitted |
Perform a case-sensitive sort. |
|
1 |
Perform a case-insensitive sort. |
|
|
nSuccess |
1 |
Sort successful. |
|
–1 |
Sort unsuccessful. We've never seen this result. |
|
Note that positive values for nSortOrder sort in descending order, while negative values sort in ascending order. Talk about confusing. In fact, it's so confusing that earlier versions of the Visual FoxPro Help file got it wrong. |
In order to specify sort order, you have to provide the starting element and number of elements or rows to sort. Starting element isn’t so hard, since it’s usually 1, but providing the number of elements is a pain—ALEN() can be handy here. Fortunately, you can also specify –1 (or 0 or any other negative number) to indicate all elements.
Similarly, you have to specify the starting element in order to indicate the number of elements or rows to sort. This one makes sense, though, since the two are related.
With two-dimensional arrays, it’s a little tricky to specify the starting element sometimes. The key is that it should be the element in the column you want to sort on, in the row where you want to start sorting. Say you have a 5x3 array and you want to sort the first three rows based on the second column. The starting element is 2. If you want to sort the last three rows based on the second column, the starting element is 12. AELEMENT() can give you a hand here.
FoxPro does not perform what’s known in math as a “stable sort.” In a stable sort, when two items have the same value in the column you’re sorting on, they retain the same relative position they had before the sort. So, for example, if you have a two-column array containing last names and first names, a stable sort would allow you to sort them on first name, then on last name, and know they were completely ordered. FoxPro doesn’t do this. We suspect it’s because unstable sorts are much faster. Use a cursor and index it if you need to sort on multiple columns.
Example
ADIR( aFiles, "*.DBF") && Get a list of DBFs
ASORT( aFiles) && Put in name order
ASORT( aFiles, 1, -1, 1) && Put in descending name order
ASORT( aFiles, 2) && Put in size order
ASORT( aFiles, 3, 3) && Put the first 3 rows in date order
ASORT( aFiles, 18, 5) && Put the 4th through 8th rows
&& in date order
ADIR( aFiles, "*.DBF", "*.*", 1) && DBFs with original caps
ASORT( aFiles, -1, -1, -1, 1) && Case-insensitive sort