5.2.2 Arrays of Strings

 A user may wish to include a series of strings rather than one single string in a field of type A. To distinguish the component strings from the complete string field, they will be described as substrings in the remainder of this section. The convention discussed in this section allows a reader to use the value of the TFORMn keyword to tell whether a character string field contains a single string or a series of substrings. The convention provides for a simple fixed length case, where all substrings are of the same length, and a variable length option, where the length of the substrings may vary. The convention makes use of the fact that additional characters are permitted after the data type code in the value of TFORMn. It is signaled by the presence of a string of the form 'rA:SSTRw[/nnn]' in the value field of the TFORMn keyword, with the /nnn present only if the length of the substrings may vary. The :SSTR is the indicator that the substring array convention is in use. A FITS reader that is not able to process substrings under this convention can treat the entire contents of the field as a single string.

In a fixed length field, w is the length of the individual substrings, for example,

TFORM5  = '40A:SSTR8'         /Fixed length substrings

tells the reader that field 5 is comprised of an array of five eight-character substrings. If a substring does not fill its specified subfield, the remainder must be padded with ASCII blanks. In the case above, for example, if the string in the first subfield were only six characters long, then bytes 7 and 8 would be blanks.

If the total length of the field is not an integer multiple of the length of the substring, the remainder of the field is undefined. For

TFORM5  = '14A:SSTR3'         /Fixed length substrings

field 5 contains four substrings of three bytes each followed by two undefined characters.

For a table field composed of substrings of variable length, all substrings but the last are terminated by an ASCII text character deliminator, whose decimal value, which must be in the range 032-126, is provided by the nnn in the value of the TFORMn keyword. Leading zeroes are included in the nnn. The last substring is terminated with an ASCII NULL (decimal 000; hexadecimal 00) regardless of the value of nnn. The value of w is the maximum number of characters in any substring of the array, not including the delimiter. For example, for

TFORM6  = '100A:SSTR8/032'     /Variable length strings

field 6 is 100 characters wide and composed of substrings whose length may vary, so long as no substring is longer than 8 characters. Each substring except the last is terminated by an ASCII BLANK (decimal 032 or hexadecimal 20); the character immediately following this delimiter is the first character of the next substring. The last substring is terminated by an ASCII NULL.

Undefined or null variable length substrings are represented by a string of zero length; the first position of the substring contains the designated delimiter (or an ASCII NULL if it is the last substring of the field). An ASCII NULL in the first position of the field signifies that the field contains no substrings. There is no corresponding representation for an undefined or null substring in an array of fixed length substrings. Possibilities include a blank substring or a user-defined substring, although general FITS readers won't necessarily recognize the special meaning of either. If a distinction needs to be made between undefined and blank substrings, it is better to use the variable length convention.

A possible alternative procedure for representing arrays of fixed length substrings is through the use of the TDIMn multidimensional array convention described in section 5.2.3. The first dimension is the number of characters in a string, and the remaining dimensions are those of the array. This convention must be used if the array of strings is two or more dimensions. CTP recommend use of the substring array convention for a one dimensional array of strings.