Using Free Format Input/Output

Use of formatted data is most appropriate when the data must be in human readable form, such as when it is to be prepared or modified with a text editor. Formatted data also are highly portable between various computers and operating systems.

In addition to the PRINT, PRINTF, READ, and READF routines already discussed, the STRING function can be used to generate formatted output that is sent to a string variable instead of a file. The READS procedure can be used to read formatted input from a string variable.

The exact format of the character data may be specified to these routines by providing a format string via the FORMAT keyword. If no format string is given, default formats for each type of data are applied. This method of formatted input/output is called free format. Free format input/output is suitable for most applications involving formatted data. It is designed to provide input/output abilities with a minimum of programming.

Structures and Free Format Input/Output

IDL structures present a special problem for default formatted input and output. The default format for displaying structure data is to surround the structure with curly braces ({}). For example, if you define an anonymous structure: 

struct = { A:2, B:3, C:'A String' }

and then use default formatted output via the PRINT command: 

PRINT, struct

IDL prints: 

{       2       3 A String}

You might suppose that default formatted input would recognize that the curly braces are part of the formatting and ignore them. This is not the case, however. By default, to read the third field in the structure (the string field) IDL will read from the "A" to the end of the line, including the closing brace.

This behavior, while unsymmetric, seems to be the best choice for default behavior—displaying the result of the PRINT statement on the computer screen. We recommend that you use explicitly formatted input/output when reading and writing structures to disk files, so as not to have to explicitly code around the possibility that your structure may include strings.

Free Format Input

The following rules are used by IDL to perform free format input:

  1. Input is performed on scalar variables. Array and structure variables are treated as collections of scalar variables. For example,
    2.      A = INTARR(5) 
     READ, A 
 
    causes IDL to read five separate values to fill each element of the variable A.
  2. If the current input line is empty and there are variables left requiring input, read another line.
  3. If the current input line is not empty but there are no variables left requiring input, the remainder of the line is ignored.
  4. Input data must be separated by commas or white space (tabs, spaces, or new lines).
  5. When reading into a variable of type string, all characters remaining in the current input line are placed into the string.
  6. When reading into numeric variables, every effort is made to convert the input into a value of the expected type. Decimal points are optional and exponential (scientific) notation is allowed. If a floating-point datum is provided for an integer variable, the value is truncated.
  7. When reading into a variable of complex type, the real and imaginary parts are separated by a comma and surrounded by parentheses. If only a single value is provided, it is taken as the real part of the variable, and the imaginary part is set to zero. For example:
    8. ;Create a complex variable. 
A = COMPLEX(0) 
 
;IDL prompts for input with a colon: 
READ, A 
 
;The user enters "(3,4)" and A is set to COMPLEX(3, 4). 
:(3, 4) 
 
;IDL prompts for input with a colon:  
READ, A 
 
;The user enters "50" and A is set to COMPLEX(50, 0). 
:50

Free Format Output

The following rules are used by IDL to perform free format output:

  1. The format used to output numeric data is determined by the data type. The formats used are summarized in the table below. The formats are specified in the FORTRAN-like style used by IDL for explicitly formatted input/output.

    2. Table 18-2: Formats Used for Free-Format Output

    Data Type
    Format

    Byte

    I4

    Int, UInt

    I8

    Long, ULong

    I12

    Float

    G13.6

    Long64, ULong64

    I22

    Double

    G16.8

    Complex

    '(', G13.6, ',', G13.6, ')'

    Double-precision Complex

    '(', G16.8, ',', G16.8, ')'

    String

    Output full string on current line.

  2. The current output line is filled with characters until one of the following happens:
    1. There is no more data to output.
    2. The output line is full. When output is to a file, the default line width is 80 columns (you can override this default by setting the WIDTH keyword to the OPEN procedure). When the output is to the standard output, IDL uses the current width of your tty or command log window.
    3. An entire row is output in the case of multidimensional arrays.
  3. When outputting a structure variable, its contents are bracketed with "{" and "}" characters.

Example: Free Format Input/Output

IDL free format input/output is extremely easy to use. The following IDL statements demonstrate how to read into a complicated structure variable and then print the results: 

;Create a structure named "types" that contains seven of the basic  
;IDL data types, as well as a floating-point array. 
A = {TYPES, A:0B, B:0, C:0L, D:1.0, E:1D, $ 
  F:COMPLEX(0), G: 'string', E:FLTARR(5)} 
 
;Read free-formatted data from input 
READ, A  
 
;IDL prompts for input with a colon. We enter values for the first  
;six numeric fields of A and the string.  
: 1 2 3 4 5 (6,7) EIGHT

Notice that the complex value was specified as (6, 7). If the parentheses had been omitted, the complex field of A would have received the value COMPLEX(6, 0), and the 7 would have been input for the next field. When reading into a string variable, IDL starts from the current point in the input and continues to the end of the line. Thus, we do not enter values intended for the rest of the structure on this line. 

;There are still fields of A that have not received data, so IDL  
;prompts for another line of input. 
: 9 10 11 12 13 
 
;Show the result. 
PRINT, A

Executing these statements results in the following output: 

{   1       2           3      4.00000       5.0000000 
(      6.00000,      7.00000)  eight 
      9.00000      10.0000      11.0000      12.0000     13.0000 
}

When producing the output, IDL uses default rules for formatting the values and attempts to place as many items as possible onto each line. Because the variable A is a structure, braces {} are placed around the output. As noted above, when IDL reads strings it continues to the end of the line. For this reason, it is usually convenient to place string variables at the end of the list of variables to be input.

For example, if S is a string variable and I is an integer: 

;Read into the string first. 
READ, S, I 
 
;IDL prompts for input. We enter a string value followed by an  
;integer. 
: Hello World 34 
 
;The entire previous line was placed into the string variable S,  
;and I still requires input. IDL prompts for another line. 
: 34