+---------------------------------+
|              ASORT              |
+---------------------------------+
ASORT(<array> [, <expN1> [, <expN2>
        [, <expN3>]]])

-----------------------------------
Sorts memory variable array in ascending or descending order.
Return value - Numeric
-----------------------------------

<array>
        Memory variable array to be sorted.

<expN1>
        Used singly:  element where sorting starts;
        Used with <expN2>: row where sorting starts.

<expN2>
        Number of elements or rows to sort.

<expN3>
        Sort order:
        0 for ascending
        1 for descending

If the sort is successfully executed 1 is returned; if the sort is
unsuccessful -1 is returned.

Note that you may refer to an element in a two-dimensional memory
variable array in two ways.  The first uses two subscripts to specify
the row and column position of the element in the array; the other uses
a single element number.  This function and others that manipulate
two-dimensional arrays require an element number (in ASORT() the numeric
expressions <expN1> and <expN2>).  You may use the AELEMENT() function
to return the proper element number from a two-dimensional array's row
and column subscripts.

+---------------------------------+
|            Examples             |
+---------------------------------+
The example below helps to illustrate how starting element <expN1>
determines how rows in two-dimensional array are sorted. Small array
named MARRAY is created and sorted twice.  First sort begins with first
element of MARRAY - rows are sorted based on values contained in first
column of array.  Second sort begins with fourth element of MARRAY and
rows are sorted based on values contained in second column.  First sort
begins with first row.  Second sort begins with second row.  You can use
DISPLAY MEMORY to display contents of array; in these examples tables
are used to graphically display results of sorts.

DIMENSION marray(3,2)
marray(1) = 'G'
marray(2) = 'A'
marray(3) = 'C'
marray(4) = 'Z'
marray(5) = 'B'
marray(6) = 'N'

An array is created that looks like this:

(Row,Column)    1       2
        1                       G       A
        2                       C       Z
        3                       B       N

Array is then sorted by ASORT() starting with first element (1,1) in
array.  Elements in first column are placed in order by rearranging rows
of array.

Note new order of rows:

=ASORT(marray,1)

(Row,Column)    1       2
        1                       B       N
        2                       C       Z
        3                       G       A

Array is then sorted starting with fourth element (2,2) in array.
Elements in second column are placed in order by rearranging array rows.
Note difference in order of rows in this example:

=ASORT(marray,4)

(Row,Column)    1       2
        1                       B       N
        2                       G       A
        3                       C       Z

The example below copies CUST_ID and COMPANY fields from CUSTOMER
database to memory variable array COMPANIES.  Array is then sorted based
on values in second column starting with fourth row (in other words,
it's sorted starting with element 8).  Program then displays a list
whose options are obtained from second column (company name) of
COMPANIES array.

*** SELECT or USE customer database *** IF USED('customer')
        SELECT customer
ELSE
        USE LOCFILE('customer.dbf','DBF','Where is CUSTOMER.DBF?')
ENDIF

COUNT TO m.count
*** DIMENSION array large enough to hold data *** DIMENSION
companies[m.count,2]

COPY TO ARRAY companies FIELD cust_id,company  && Fill the array

*** Note: first three rows will not be sorted ***

= ASORT(companies, AELEMENT(companies,4,2))  && Sort array

@ 5,30 SAY 'List of Companies:'
@ 7,30 GET m.choice ;
        FROM companies ;
        RANGE 2 ;
        SIZE 10,30 ;
        DEFAULT 1

READ  && Display and GET sorted company data

CLEAR
USE

-----------------------------------

See Also:  ACOPY(), ADEL(), AELEMENT(), AINS(), ASCAN()

-----------------------------------