idlastro / FITS ASCII & Binary Table I/O: FTSORT

[Source code]

NAME
FTSORT
PURPOSE
Sort a FITS ASCII table according to a specified field
CALLING SEQUENCE
FTSORT,h,tab,[field, REVERSE = ]               ;Sort original table header and array
         or
FTSORT,h,tab,hnew,tabnew,[field, REVERSE =]   ;Create new sorted header
INPUTS
H - FITS header (string array)
TAB - FITS table (byte array) associated with H.  If less than 4
         parameters are supplied, then H and TAB will be updated to 
         contain the sorted table
OPTIONAL INPUTS
FIELD - Field name(s) or number(s) used to sort the entire table.  
        If FIELD is a vector then the first element is used for the 
        primary sort, the second element is used for the secondary
        sort, and so forth.   (A secondary sort only takes effect when
        values in the primary sort  field are equal.)  Character fields
        are sorted using the ASCII collating sequence.  If omitted,
        the user will be prompted for the field name.
OPTIONAL OUTPUTS
HNEW,TABNEW - Header and table containing the sorted tables
EXAMPLE
Sort a FITS ASCII table by the 'DECLINATION' field in descending order
Assume that the table header htab, and array, tab, have already been
read (e.g. with READFITS or FITS_READ):
IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE
OPTIONAL INPUT KEYWORD
REVERSE - If set then the table is sorted in reverse order (maximum
       to minimum.    If FIELD is a vector, then REVERSE can also be
       a vector.   For example, REVERSE = [1,0] indicates that the
       primary sort should be in descending order, and the secondary
       sort should be in ascending order.
EXAMPLE
SIDE EFFECTS
A HISTORY record is added to the table header.
REVISION HISTORY
Written W. Landsman                         June, 1988
Converted to IDL V5.0   W. Landsman   September 1997
New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts
            W. Landsman   May 2000