5.6.1.3 Proposed TSORTKEY Convention

The purpose of this convention is to provide information on the ordering of rows in a FITS ASCII or binary table. How the table has been ordered is useful information for users; indeed, it may be necessary for some data processing operations. Usually, the rows are in order of increasing values in a particular column in the table, for example, time or right ascension. To specify the order used in a particular FITS table, a new keyword is used:

TSORTKEY (character) lists the name of the primary sort column, given by the value of the TTYPEn keyword, followed, optionally, by the names of secondary sort columns. The names must be separated by a comma; there may be zero or more spaces between a comma and the next column name.

The default order for sorting in this convention is ascending order; if the sort is in descending order, the name of the column is preceded by a minus sign.

This convention prescribes the following ascending sort order for the FITS data types:

Integer and floating point

In numerical order for both ASCII and binary tables; ASCII tables are not sorted in order of the internal ASCII representation of their contents.

Complex

In numerical order of the real component first; rows with the same value of the real component are sorted in order of the imaginary component.

Bit

Zero or ``unset'' bits precede ``set'' bits.

Logical

False (F) values precede true (T) values.

Character and string

In order of the ASCII collating sequence; for a string, first in order of the first character, then in order of the second character, than in order of following characters in sequence.

In an ascending order search, null or undefined characters follow all defined values.

The convention also provides a sort order for vector columns. If the order is not otherwise specified, rows are sorted first on the order of the value of the first element, then in order of the value of the second element, and on in sequence. Other columns may be used for sorting. If the column ARRAY is being sorted first on element i, then on element j, and then on element k, then

TSORTKEY~='ARRAY(i),ARRAY(j),ARRAY(k)'

If the sorting is on consecutive columns $m \ldots n$, then

TSORTKEY~='ARRAY(m:n)', ARRAY(k)'

A string is treated as a vector of characters. When sorting strings, a blank element precedes any characters. For an ascending order default sort, shorter strings precede longer ones: ``FORM '' precedes ``FORMAT''.

This convention can be used only if the values of the TTYPEn keywords labelling the columns of the table obey the following restrictions:

• There must be a TTYPEn for every column, and the name of every column (value of TTYPEn) must be unique.
• The first character of a column name must not be a minus sign.
• No column name may contain a comma (hexadecimal 2C), or an open or close parenthesis (hexadecimal 28 and 29).
• Embedded blank characters are discouraged, with the underscore recommended to link separate words in a column name.