.-
help for ^qsort^ and ^qsortidx^                      (STB-45: ip14.1)
.-

Sorts a list of words
---------------------

        ^qsort^ list, {^ascend^ | ^descend^ } ^alpha^ ] 

        ^qsortidx^ list1 [ ^\ *^|list2 ^\^ ...] [^,^ {^ascend^ | ^descend^ } ^alpha^ ] 


Description
-----------

^qsort^ sorts the words in a list in ascending or descending order, and returns
the ordered list in ^S_1^. (Words are seperated by white space.)
 
^qsortidx^ sorts the words in list1 in ascending or descending order, and applies
the same permutation to the words of list2, list3 etc. All specified lists 
should have the same number n of words. ^*^ is expanded in 1..n. The ordered 
versions of string_i is returned in ^S_i^.

The ordering may be in numeric or alphanumeric order.
  

Options
------- 

^ascend^|^descend^ specifies that the words in list (list1) are sorted in 
    ^ascend^ing (increasing) or or ^descend^ing (decreasing) order. In 
    accordance with ^sort^-ing observations, ^qsort^ and ^qsortidx^ default 
    to ^ascend^.
    
^alpha^ specified that the words are compared alpha-numerically. The default is 
    to compare the words numerically.

^display^ specifies that the transformations are displayed. This option is 
    useful mostly while debugging.


Remarks 
-------

^qsort^ and ^qsortidx^ sort using a non-recursive quicksort algorithmn as described in 

        Wirth, N. (1976)
                Algorithms + Data Structures = Programs.
                Englewood Cliffs, N.J.: Prentice Hall. p: 80-82.
                
quicksort is a "stable" sorting algorithm, implying that the relative ordering of 
elements that are tied on the sorting keys is unchanged.
                
Examples
--------

   . ^global A  "3 1 5 4 2"^
   . ^global B  "1 4 9 16 25"^
   . ^global C  "a b c dd ever"^
   
   . ^qsort $A^                (then: ^S_1 = 1 2 3 4 5^)
   . ^qsort $A , a^            (then: ^S_1 = 1 2 3 4 5^)
   . ^qsort $A , d^            (then: ^S_1 = 5 4 3 2 1^)

   . ^qsortidx $A \ $B, d^     (then: ^S_1 = 5 4 3 2 1    S_2 = 9 16 1 25 4^)
   . ^qsortidx $A \ $C, d^     (then: ^S_1 = 5 4 3 2 1    S_2 = c dd a ever b^)

Quicksort is a "stable" sorting algorithm:

   . qsortidx 1 3 2 3 1 \ a b c d e 
                             (then: ^S_1 = 1 1 2 3 3    S_2 = a e c b d^)
   
To obtain a alphabetcially ordered lists of variables

   . ^local varlist "opt"^      (setup for ^parse^)
   . ^parse "_all"^             (parse ^_all^ into varlist with all variables)
   . ^qsort `varlist', alpha^   (sort varlist in alphabetic order)
   . ^local varlist "$S_1"^     (assign sorted list back to varlist)
  

Author
------

      Jeroen Weesie
      Utrecht University, Netherlands
      weesie@@weesie.fsw.ruu.nl


Also See
--------

    STB:  ip14.1 (STB-45)
 Manual:  [R] sort
On-line:  ^help^ for @sort@, @gsort@