$FUNCNAME$
  ASORT()
$CATEGORY$
  ARRAY
$SUMMARY$
   Sort an array
$LANG_RU$
    .
$SYNTAX$
     ASORT(<aTarget>, [<nStart>],[<nCount>], [<bOrder>]) --> aTarget
$LANG_RU$
     ASORT(< >, [< >], [<- >], [< >]) -->  
$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.
$LANG_RU$
     < > -   .
     < > -    . 
     < >  ,    
      .
     <- > -  ,  
     .  <- >  ,  
       ,    < > 
       .
     < > -   ,  
       .    ,   
           .
$RETURNS$
     ASORT() returns a reference to the <aTarget> array.
$LANG_RU$
     ASORT()     < >.
$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.
$LANG_RU$
     ASORT() -   ,    ,
        ,   .  
      ,     CHARACTER, DATE, LOGICAL 
     NUMERIC.

       < >  ,   
         .   
          ( ),   
             
     ( ).

       < >    ,  
       .     
          .  
       ,    ""
     (.T.).        
          (.  ).

            
      ASCII,    ,  
     ""(.F.)   ,    
       ,    -    
     .

      :
          xClipper   
        ,  ASORT()    .
            ,
         .
$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} }
$LANG_RU$
              
            ,  ,  
        ,  :

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

             
         ,     
        .    
       ,       
       :

       aArray := { "", "K", "", "" }
       ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) } )

            
        :

       aKids := { {"", 14}, {"", 23}, {"", 16} }
       aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })
       //
       //  : { {"", 14}, {"", 16}, {"", 23} }
$SEEALSO$
  ASCAN(),EVAL()
$END$
