Using Explicitly Formatted Input/Output

The FORMAT keyword can be used with the formatted input/output routines to explicitly specify the appearance of the data. The standard syntax of IDL format strings is similar to that used in FORTRAN; a C printf()-style syntax is also supported, as described in C printf-Style Quoted String Format Code.

Note
IDL uses the standard I/O function sprintf to do its formatting. Different platforms implement this function in different ways, which may lead to slight inconsistencies in the appearance of the output.

The format string specifies the format in which data is to be transferred as well as the data conversion required to achieve that format. The format specification strings supplied by the FORMAT keyword have the form: 

FORMAT = '(q1f1s1f2s2 ... fnqn)'

where q, f, and s are described below.

Record Terminators

q is zero or more slash (/) record terminators. On output, each record terminator causes the output to move to a new line. On input, each record terminator causes the next line of input to be read.

Format Codes

f is a format code. Some format codes specify how data should be transferred while others control some other function related to how input/output is handled. The code f can also be a nested format specification enclosed in parentheses. This is called a group specification and has the following form: 

...[n](q1f1s1f2s2 ... fnqn) ...

A group specification consists of an optional repeat count n followed by a format specification enclosed in parentheses. Use of group specifications allows more compact format specifications to be written. For example, the format specification: 

FORMAT = '("Result: ", "<",I5,">", "<",I5,">")'

can be written more concisely using a group specification: 

FORMAT = '("Result: ", 2("<",I5,">"))'

If the repeat count is 1 or is not given, the parentheses serve only to group format codes for use in format reversion (discussed in the next section). Format codes and their syntax are described in detail in Format Codes.

Field Separators

s is a field separator. A field separator consists of one or more commas (,) and/or slash record terminators (/). The only restriction is that two commas cannot occur side-by-side.

The arguments provided in a call to a formatted input/output routine are called the argument list. The argument list specifies the data to be moved between memory and the file. All data are handled in terms of basic IDL components. Thus, an array is considered to be a collection of scalar data elements, and a structure is processed in terms of its basic components. Complex scalar values are treated as two floating-point values.

Rules for Explicitly Formatted Input/Output

IDL uses the following rules to process explicitly formatted input/output:

  1. Traverse the format string from left to right, processing each record terminator and format code until an error occurs or no data is left in the argument list. The comma field separator serves no purpose except to delimit the format codes.
  2. It is an error to specify an argument list with a format string that does not contain a format code that transfers data to or from the argument list because an infinite loop would result.
  3. When a slash record terminator (/) is encountered, the current record is completed, and a new one is started. For output, this means that a new line is started. For input, it means that the rest of the current input record is ignored, and the next input record is read.
  4. When a format code that does not transfer data to or from the argument list is encountered, process it according to its meaning. The format codes that do not transfer data to or from the argument list are summarized here.

    5. Table 18-3: Format Codes That Do Not Transfer Data 

    Code
    Action

    Quoted String

    On output, the contents of the string are written out. On input, quoted strings are ignored.

    :

    The colon format code in a format string terminates format processing if no more items remain in the argument list. It has no effect if data still remains on the list.

    $

    On output, if a $ format code is placed anywhere in the format string, the new line implied by the closing parenthesis of the format string is suppressed. On input, the $ format code is ignored.

    nH

    FORTRAN-style Hollerith string. Hollerith strings are treated exactly like quoted strings.

    nX

    Skips n character positions.

    Tn

    Tab. Sets the character position of the next item to the n-th position in the current record.

    TLn

    Tab Left. Specifies that the next character to be transferred to or from the current record is the n-th character to the left of the current position.

    TRn

    Tab Right. Specifies that the next character to be transferred to or from the current record is the n-th character to the right of the current position.

  5. When a format code that transfers data to or from the argument list is encountered, it is matched up with the next datum in the argument list. The format codes that transfer data to or from the argument list are summarized in the following table.

    6. Table 18-4: Format Codes That Transfer Data

    Code
    Action

    A

    Transfer character data.

    B

    Transfer binary data.

    C()

    Transfer calendar (Julian date and/or time) data.

    D

    Transfer double-precision, floating-point data.

    E

    Transfer floating-point data using scientific (exponential) notation.

    F

    Transfer floating-point data.

    G

    Use F or E format depending on the magnitude of the value being processed.

    I

    Transfer integer data.

    O

    Transfer octal data.

    Q

    Obtain the number of characters in the input record remaining to be transferred during a read operation. In an output statement, the Q format code has no effect except that the corresponding input/output list element is skipped.

    Z

    Transfer Hexadecimal data.

  6. On input, read data from the file and format it according to the format code. If the data type of the input data does not agree with the data type of the variable that is to receive the result, do the type conversion if possible; otherwise, issue a type conversion error and stop.
  7. On output, write the data according to the format code. If the data type does not agree with the format code, do the type conversion prior to doing the output if possible. If the type conversion is not possible, issue a type conversion error and stop.
  8. If the last closing parenthesis of the format string is reached and there are no data left on the argument list, then format processing terminates. If, however, there are still data to be processed on the argument list, then part or all of the format specification is reused. This process is called format reversion.

Format Reversion

In format reversion, the current record is terminated, a new one is initiated, and format control reverts to the group repeat specification whose opening parenthesis matches the next-to-last closing parenthesis of the format string. If the format does not contain a group repeat specification, format control returns to the initial opening parenthesis of the format string. For example, the IDL command: 

PRINT, FORMAT = '("The values are: ", 2("<", I1, ">"))', $ 
   INDGEN(6)

results in the output 

The values are: <0><1> 
<2><3> 
<4><5>

The process involved in generating this output is as follows:

  1. Output the string "The values are: ".
  2. Process the group specification and output the first two values. The end of the format specification is encountered, so end the output record. Data are remaining, so move back to the group specification
           2("<", I1, ">")
    by format reversion.
  3. Repeat Step 2 until no data remain. End the output record. Format processing is complete.