IDL format codes

Syntax of Format Codes

---

The syntax of an IDL format code is:

[n]FC[+][-][width]

Where:

n	is an optional repeat count (1 ≤ n) specifying the number of times the format code should be processed. If nis not specified, a repeat count of one is used.
FC	is the format code. See Available Format Codes, below.
+	is an optional flag that specifies that positive numbers should be output with a “+” prefix. The “+” flag is only valid for numeric format codes. Normally, negative numbers are output with a “-” prefix and positive numbers have no sign prefix. Non-decimal numeric codes (B, O, and Z) allow the specification of the “+” flag, but ignore it.
-	is an optional flag that specifies that string or numeric values should be output with the text left-justified. Normally, output is right-justified.
width	is an optional width specification. Width specifications and default values are format-code specific, and are described in detail along with the format code. See Padding and Natural Width Formatting, below, for additional information on how output values are formatted based on the width parameter.

Padding and Natural Width Formatting

The value being formatted may be shorter than the output width specified by the width parameter. When this happens, IDL will adjust either the contents of the output value or the width of the field, using the following mechanisms:

Whitespace Padding

By default, if the value being formatted uses fewer characters than specified by the width parameter, IDL pads the value with whitespace characters on the left to create a string of the specified width. For example, the following IDL statement

PRINT, FORMAT='(I12)', 300

produces the following output:

bbbbbbbbb300

where b represents a space character.

Zero Padding

For numeric format codes, if the first digit of the width parameter is a zero, IDL will pad the value with zeroes rather than blanks. For example:

PRINT, FORMAT='(I08)', 300

produces the following output:

00000300

When padding values with zeroes, note the following:

1. If you specify the “-” flag to left-justify the output, specifying a leading zero in the width parameter has no effect, since there are no unused spaces to the left of the output value.
2. If you specify an explicit minimum width value (via the m width parameter) for an integer format code, specifying a leading zero in the width parameter has no effect, since the output value is already padded with zeroes on the left to create an output value of the specified minimum width.

Natural Width Formatting

If the numeral zero is specified for the width parameter, IDL uses the “natural” width for the value. The value is read or output using a default format without any leading or trailing whitespace, in the style of the standard C library printf()function.

Using a value of zero for the width parameter is useful when reading tables of data in which individual elements may be of varying lengths. For example, if your data reside in tables of the following form:

26.01 92.555 344.2

101.0 6.123 99.845

23.723 200.02 141.93

Setting the format to:

FORMAT = '(3F0)'

ensures that the correct number of digits are read or output for each element.

Available Format Codes

---

IDL supports the following format codes:

Format Code	Description
A Format Code	Transfers character values
: Format Code	Terminates processing
$ Format Code	Suppresses newlines in output
F, D, E, and G Format Codes	Transfer floating-point values
B, I, O, and Z Format Codes	Transfer integer values
Q Format Code	Returns the number of characters that remain to be transferred during a read operation
Quoted String and H Format Codes	Output string values directly
T Format Code	Specifies the absolute position within a record
TL Format Code	Moves the position with a record to the left
TR and X Format Codes	Move the position within a record to the right
C() Format Code	Transfers calendar data
C printf-Style Quoted String Format Code	Provides an alternative syntax for specifying the format of an output string

Format Code Examples

---

For examples using different format codes, see:

• Example: Reading Formatted Table Data

• Example: Reading Records With Multiple Array Elements

  Format Code Examples

  The following table shows the results of the application of various format codes to given data values. Note that normally, the case of the format code is ignored by IDL. However, the case of the E and G format codes determines the case used to output the exponent in scientific notation.

  Format	Internal Value	Formatted Output
  F	100.0	bbbb100.0000000
  F	100.0D	bbbbb100.0000000000000000
  F10.0	100.0	bbbbbb100.
  F10.1	100.0	bbbbb100.0
  F10.4	100.0	bb100.0000
  F2.1	100.0	**
  e11.4	100.0	b1.0000e+02 1.0000e+002 (Windows) Note that “e10.4” displays “**********” under Windows because the extra “0” added after the “e” makes the string longer than 10 characters.
  E11.4	100.0	b1.0000E+02 1.0000E+002 (Windows)
  g10.4	100.0	bbbbb100.0
  g10.4	10000000.0	b1.000e+07 1.000e+007 (Windows)
  G10.4	10000000.0	b1.000E+07 1.000E+007 (Windows)