ASORT()
 Sort an array
------------------------------------------------------------------------------
 Syntax

     ASORT(<aTarget>, [<nStart>],
        [<nCount>], [<bOrder>]) --> aTarget

 Arguments

     <aTarget> is the array to be sorted.

     <nStart> is the first element of the sort.  If not specified, the
     default starting position is one.

     <nCount> is the number of elements to be sorted.  If not specified,
     all elements in the array beginning with the starting element are
     sorted.

     <bOrder> is an optional code block used to determine sorting order.
     If not specified, the default order is ascending.

 Returns

     ASORT() returns a reference to the <aTarget> array.

 Description

     ASORT() is an array function that sorts all or part of an array
     containing elements of a single data type.  Data types that can be
     sorted include character, date, logical, and numeric.

     If the <bOrder> argument is not specified, the default order is
     ascending.  Elements with low values are sorted toward the top of the
     array (first element), while elements with high values are sorted toward
     the bottom of the array (last element).

     If the <bOrder> block argument is specified, it is used to determine the
     sorting order.  Each time the block is evaluated, two elements from the
     target array are passed as block parameters.  The block must return true
     (.T.) if the elements are in sorted order.  This facility can be used to
     create a descending or dictionary order sort.  See the examples below.

     When sorted, character strings are ordered in ASCII sequence; logical
     values are sorted with false (.F.) as the low value; date values are
     sorted chronologically; and numeric values are sorted by magnitude.

 Notes

     .  ASORT() is only guaranteed to produce sorted output (as
        defined by the block), not to preserve any existing natural order in
        the process.

     .  Because Clipper implements multidimensional arrays by
        nesting subarrays within other arrays, ASORT() will not directly sort
        a multidimensional array.  To sort a nested array, you must supply a
        code block which properly handles the subarrays.

 Examples

     .  This example creates an array of five unsorted elements, sorts
        the array in ascending order, then sorts the array in descending
        order using a code block:

        aArray := { 3, 5, 1, 2, 4 }
        ASORT(aArray)
        // Result: { 1, 2, 3, 4, 5 }

        ASORT(aArray,,, { |x, y| x > y })
        // Result: { 5, 4, 3, 2, 1 }

     .  This example sorts an array of character strings in ascending
        order, independent of case.  It does this by using a code block that
        converts the elements to uppercase before they are compared:

        aArray := { "Fred", Kate", "ALVIN", "friend" }
        ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) })

     .  This example sorts a nested array using the second element of
        each subarray:

        aKids := { {"Mary", 14}, {"Joe", 23}, {"Art", 16} }
        aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })

        Result:

        { {"Mary", 14}, {"Art", 16}, {"Joe", 23} }

 Files   Library is EXTEND.LIB.

See Also: ASCAN() EVAL() SORT