Functions and Directives

Function ASort() Foundation

Sorts the elements of an array.

Syntax
ASort( <aArray>, [<nStart>], [<nCount>], [<bOrder|lOrder>] ) --> aArray
Parameters
<aArray>
<aArray> is the array whose elements are sorted.
<nStart>
<nStart> is a numeric value specifying the starting position for the sort within the array <aArray>. The default value is 1.
<nCount>
<nCount> is a numeric value specifying the number of elements sorted starting with <nStart>. If <nCount> is missing, all elements from <nStart> to the last element of <aArray> are sorted.
<bOrder>
The optional code block <bOrder> can be used to specify how the sort will be performed. One dimensional arrays can be sorted without using a code block. In this case, the elements are sorted in ascending order. Sorting multi-dimensional arrays requires <bOrder>. The values of two array elements are passed to this code block. The code block must perform a logical comparison.
<lOrder>
The optional logical value <lOrder> can be used instead of <bOrder> if only the sort direction is to be set. If <lOrder> is set to .T., ASort() will sort descending, otherwise ascending.
Return

The return value of ASort() is a reference to <aArray>.

Description

The array function ASort() sorts the elements of an array. One dimensional arrays are sorted in ascending order by default. This means that smaller values are placed at the beginning of the array, with larger values at the end. Sorting in descending order or sorting multi-dimensional arrays requires that a code block be specified. The code block must contain a logical expression comparing two values. Two values x1 and x2 are passed to the code block from ASort(). To create ascending order, the code block must return the result of evaluating whether x1 < x2. To create descending order, the code block must return the result of evaluating whether X1 > X2.

Character strings are sorted according to their lexical order. Sorting depends on the settings SET EXACT, SET LEXICALand SET COLLATION. Logical values are sorted with .F. (false) being less than .T. (true). Date values are sorted chronologically and numeric values according to their size.

Examples
Sort a one dimensional array

// The example shows the ascending and descending sorting of a 
// one dimensional array. 

PROCEDURE Main 
   LOCAL aArray 
   aArray := {"E","A","D","C","B"} 

                              // sort ascending 
   ASort( aArray )            // aArray is: {"A","B","C","D","E"} 

                              // sort descending 
   ASort( aArray,,, .T. ) 
                              // aArray is: {"E","D","C","B","A"} 
RETURN 
Sort a two dimensional array

// The example shows the ascending and descending sorting of a 
// two dimensional array. 

PROCEDURE Main 
   LOCAL aArray 

   aArray := { ; 
               {"E", 4 }, ; 
               {"A", 3 }, ; 
               {"D", 2 }, ; 
               {"C", 5 }, ; 
               {"B", 1 }  ; 
             } 

                              // first column ascending sort 
   ASort( aArray,,, {|aX,aY| aX[1] < aY[1] } ) 
                              // aArray is: { {"A", 3 }, ; 
                              //              {"B", 1 }, ; 
                              //              {"C", 5 }, ; 
                              //              {"D", 2 }, ; 
                              //              {"E", 4 }  } 

                              // second column descending sort 
   ASort( aArray,,, {|aX,aY| aX[2] > aY[2] } ) 
                              // aArray is: { {"C", 5 }, ; 
                              //              {"E", 4 }, ; 
                              //              {"A", 3 }, ; 
                              //              {"D", 2 }, ; 
                              //              {"B", 1 }  } 
RETURN 

Create an index for an array
// In the example, a UDF AIndex() is shown which creates an 
// index array for a two dimensional data array, analogous to an 
// index file. The index array contains numeric pointers into the data 
// array. The index array is sorted on the basis of the values in 
// the data array. 

#include "Directry.ch" 

PROCEDURE Main 
   LOCAL aData, aNameIndex, aDateIndex 

   aData        := Directory("*.*") 
   aNameIndex   := AIndex( aData, F_NAME ) 
   aDateIndex   := AIndex( aData, F_DATE ) 

** Output of file name and date in normal order 
   AEval( aData, {|a| QOut(a[F_NAME],a[F_DATE]) } ) 

** Output of file name and date sorted by name 
   AEval( aNameIndex, {|n| QOut(aData[n,F_NAME], ; 
                                aData[n,F_DATE]) } ) 

** Output of file name and date sorted by date 
   AEval( aDateIndex, {|n| QOut(aData[n,F_NAME], ; 
                                aData[n,F_DATE]) } ) 

RETURN 

FUNCTION AIndex( aData, nSubScript ) 
   LOCAL aIndex[ Len(aData) ]      // create array index 
                                   // fill index array with 
                                   // numeric pointers 
   AEval( aIndex, {|a,i| aIndex[i]:=i } ) 
                                   // sort index array on the basis 
                                   // of the values in the data array 
RETURN ASort( aIndex,,, {|n1,n2| aData[n1, nSubScript] < ; 
                                 aData[n2, nSubScript] } ) 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.