FORTRAN-Style Format Codes

The FORTRAN-style format codes specify how data should be transferred using a format similar to that in the FORTRAN language.

Example

Use the FORTRAN style to print out three numbers surrounded by brackets:

PRINT, FINDGEN(3), FORMAT = '("The values are: [", 3(" ",f0), "]")'

IDL prints:

The values are: [ 0.000000 1.000000 2.000000]

Syntax

The syntax of a FORTRAN-style format code is:

[n]C[+][-][width]

where:

n	is an optional repeat count (1 ≤ n) specifying the number of times the format code should be processed. If n is not specified, a repeat count of one is used.
C	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, only negative numbers are output with a sign prefix. Non-decimal numeric codes (B, O, and Z) allow the "+" flag, but ignore it.
–	is an optional flag that specifies that string or numeric values should be left-justified on output. Normally, output is right-justified.
width	is an optional width specification. Width specifications and default values are format-code specific, and are described with the format codes below.

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:

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.
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	Transfers character and string values.
:	Terminates format processing if no more items remain in the argument list. No effect if data still remains on the list.
$	On output, suppresses the newline. Ignored on input.
F, D, E, and G	Transfer floating-point values.
B, I, O, and Z	Transfer binary, integer, octal, or hexadecimal values.
Q	On input, returns the number of characters that remain to be transferred. During output, skips the corresponding output list element.
"string" and H	On output, the string contents are written out. Ignored on input.
Tn	Tab to the n-th absolute position in the current record.
TLn	Tab left n characters.
TRn	Tab right n characters.
nX	Skips n character positions.
C()	Transfers calendar data.
C printf-Style	Use a C printf-style format string within a FORTRAN-style format.

A Format Code

The A format code transfers character data.

The syntax is:

[n]A[-][w]

where the parameters “n” and “-” are as described in Syntax and the width specification is as follows:

is an optional width (0 ≤ w) specifying the number of characters to be transferred. If w is not specified, the entire string is transferred. On output, if w is greater than the length of the string, the string is right justified. On input, IDL strings have dynamic length, so w specifies the resulting length of input string variables. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

For example, the IDL statement,

PRINT, FORMAT = '(A6)', '123456789'

generates the following output:

123456

: Format Code

The colon format code terminates format processing if there are no more data remaining in the argument list.

The syntax is:

For example, the IDL statement,

PRINT, FORMAT = '(6(I1, :, ", "))', INDGEN(6)

will output the following comma-separated list of integer values:

0, 1, 2, 3, 4, 5

Using the colon format code prevented a comma from being output following the final item in the argument list.

$ Format Code

When IDL completes output format processing, it normally outputs a newline to terminate the output operation. However, if a “$” format code is found in the format specification, this default newline is not output. The “$” format code is only used on output; it is ignored during input formatting.

The syntax is:

One use for the “$” format code is in prompting for user input in programs that run in a tty rather than in the graphical IDL Workbench. For example, the following simple program show the difference between strings formatted with and without the “$” format code. The first PRINT statement prompts the user for input without forcing the user’s response to appear on a separate line from the prompt; the second PRINT statement makes the user enter the response on a separate line.

IDL> .run

- PRO format_test

- name=''

- age=0

- PRINT, FORMAT='($, "Enter name")'

- READ, name

- PRINT, FORMAT='("Enter age")'

- READ, age

- PRINT, FORMAT='("You are ", I0, " years old, ", A0)', age, name

- END

% Compiled module: FORMAT_TEST.

Running the procedure looks like this:

IDL> format_test

Enter name: Pat

Enter age

: 29

You are 29 years old, Pat

IDL>

where the values in italics were entered by the user in response to the prompts.

F, D, E, and G Format Codes

The F, D, E, and G format codes are used to transfer floating-point values between memory and the specified file.

The syntax is:

[n]F[+][-][w][.d]

[n]D[+][-][w][.d]

[n]E[+][-][w][.d][Ee]

[n]G[+][-][w][.d][Ee]

where the parameters “n”, “+”, and “-” are as described in Syntax and the width specification is as follows:

w	is an optional width specification (0 ≤ w ≤ 255). The variable w specifies the number of digits to be transferred. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.
d	is an optional width specification (1 ≤ d < w). For the F, D, and E format codes, d specifies the number of positions after the decimal point. For the G format code, d specifies the number of significant digits displayed.
e	is an optional width (1 ≤ e ≤ 255) specifying the width of exponent part of the field. IDL ignores this value—it is allowed for compatibility with FORTRAN.

On input, the F, D, E, and G format codes all transfer w characters from the external field and assign them as a real value to the corresponding input/output argument list datum.

The F and D format codes are used to output values using fixed-point notation. The value is rounded to d decimal positions and right-justified into an external field that is w characters wide. The value of w must be large enough to include a minus sign when necessary, at least one digit to the left of the decimal point, the decimal point, and d digits to the right of the decimal point. The code D is identical to F (except for its default values for w and d) and exists in IDL primarily for compatibility with FORTRAN.

The E format code is used for scientific (exponential) notation. The value is rounded to d decimal positions and right-justified into an external field that is w characters wide. The value of w must be large enough to include a minus sign when necessary, at least one digit to the left of the decimal point, the decimal point, d digits to the right of the decimal point, a plus or minus sign for the exponent, the character “e” or “E”, and at least two characters for the exponent.

Note: IDL uses the standard C library function snprintf() to format numbers and their exponents. As a result, different platforms may print different numbers of exponent digits.

The G format code uses the F output style when reasonable and E for other values, but displays exactly d significant digits rather than d digits following the decimal point.

Overflow

On output, if the field provided is not wide enough, it is filled with asterisks (*) to indicate the overflow condition.

Default Values of the w, d, and e Parameters

If w, d, or e are omitted, the values specified in the following table are used.

Data Type	w	d	e
Float, Complex	15	7	2 (3 for Windows)
Double	25	16	2 (3 for Windows)
All Other Types	25	16	2 (3 for Windows)

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`	bbbb`100.0000000`
`F`	`100.0D`	bbbbb`100.0000000000000000`
`F10.0`	`100.0`	bbbbbb`100.`
`F10.1`	`100.0`	bbbbb`100.0`
`F10.4`	`100.0`	bb`100.0000`
`F2.1`	`100.0`	`**`
`e11.4`	`100.0`	b`1.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`	b`1.0000E+02` `1.0000E+002 (Windows)`
`g10.4`	`100.0`	bbbbb`100.0`
`g10.4`	`10000000.0`	b`1.000e+07` `1.000e+007 (Windows)`
`G10.4`	`10000000.0`	b`1.000E+07` `1.000E+007 (Windows)`

B, I, O, and Z Format Codes

The B, I, O, and Z format codes are used to transfer integer values to and from the specified file. The B format code is used to output binary values, I is used for decimal values, O is used for octal values, and Z is used for hexadecimal values.

The syntax is:

[n]B[-][w][.m]

[n]I[+][-][w][.m]

[n]O[-][w][.m]

[n]Z[-][w][.m]

where the parameters “n”, “+”, and “-” are as described in Syntax and the width specification is as follows:

is an optional width specification (0 ≤ w ≤ 255). The variable w specifies the number of digits to be transferred. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

is an optional minimum number (1 ≤ m ≤ 255) of nonblank digits to be shown on output. The field is zero-filled on the left if necessary. If m is omitted or zero, the output is padded with blanks to achieve the specified width.

Note: The m parameter is ignored if w is zero.

Overflow

On output, if the field provided is not wide enough, it is filled with asterisks (*) to indicate the overflow condition.

Default Values of the w Parameter

The default values used by the I, O, and Z format codes if w is omitted are specified in the following table:

Data Type	w
Byte, Int, UInt	7
Long, ULong, Float	12
Long64, ULong64	22
Double	23
All Other Types	12

The default values used by the B format code if w is omitted are specified in the following table:

Data Type	w
Byte	8
Int, UInt	16
Long, ULong	32
Long64, ULong64	64
All Other Types	32

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 Z format codes determines the case used to output the hexadecimal digits A-F.

Format	Internal Value	Formatted Output
B	3000	bbbb101110111000
B15	3000	bbb101110111000
B14.14	3000	00101110111000
I	3000	bbb3000
I6.5	3000	b03000
I5.6	3000	*****
I2	3000	**
O	3000	bbb5670
O6.5	3000	b05670
O5.6	3000	*****
O2	3000	**
z	3000	bbbbbb8
Z	3000	bbbbBB8
Z6.5	3000	b00BB8
Z5.6	3000	*****
Z2	3000	**

Q Format Code

The Q format code returns the number of characters in the input record remaining to be transferred during the current read operation. It is ignored during output formatting.

The syntax is:

Format Q is useful for determining how many characters have been read on a line. For example, the following IDL statements count the number of characters in file demo.dat:

;Open file for reading.

OPENR, 1, "demo.dat"

;Create a longword integer to keep the count.

N = 0L

;Count the characters.

WHILE(~ EOF(1)) DO BEGIN

READF, 1, CUR, FORMAT = '(q)' & N = N + CUR

ENDWHILE

;Report the result.

PRINT, FORMAT = '("counted", N, "characters.")'

;Close file.

CLOSE, 1

Quoted String and H Format Codes

On output, any quoted strings or Hollerith constants are sent directly to the output. On input, they are ignored.

The syntax for a quoted string is:

"string" or 'string'

where string is the string to be output.

Note: Quoted strings must be enclosed in either single or double quotation marks; use the type of quotation mark that is not used to enclose the entire format string.

For example, the IDL statement,

PRINT, FORMAT = '("Value: ", I0)', 23

results in the following output:

Value: 23

Note that it would have been equally correct to use double quotes around the entire format string and single quotes around the quoted string “Value: ”.

Another way to specify a quoted string is with a Hollerith constant.

The syntax for a Hollerith constant is:

nHc₁c₂c₃... c_n

where

n	is the number of characters in the constant (1 ≤ n ≤ 255).
c_i	is the characters that make up the constant. The number of characters must agree with the value provided for n.

For example, the following IDL statement,

PRINT, FORMAT = '(7HValue: , I0)', 23

results in the following output:

Value: 23

See C printf-Style Format Codes for an alternate form that supports C printf-style format capabilities.

T Format Code

The T format code specifies the absolute position in the current record.

The syntax is:

where

n	is the absolute character position within the record to which the current position should be set (1 ≤ n).

The T format code differs from the TL, TR, and X format codes primarily in that it specifies an absolute position rather than an offset from the current position. For example,

PRINT, FORMAT = '("First", 20X, "Last", T10, "Middle")'

produces the following output:

FirstbbbbMiddlebbbbbbbbbbLast

where “b” represents a blank space.

TL Format Code

The TL format code moves the current position in the external record to the left.

The syntax is:

TLn

where

n	is the number of characters to move left from the current position (1 ≤ n). If the value of n is greater than the current position, the current position is moved to column one.

The TL format code is used to move backwards in the current record. It can be used on input to read the same data twice or on output to position the output nonsequentially. For example,

PRINT, FORMAT = '("First", 20X, "Last", TL15, "Middle")'

produces the following output:

FirstbbbbbbbbbMiddlebbbbbLast

where “b” represents a blank space.

TR and X Format Codes

The TR and X format codes move the current position in the record to the right.

The syntax is:

TRn

where

n	is the number of characters to skip (1 ≤ n). On input, n characters in the current input record will be passed over. On output, the current output position is moved n characters to the right.

The TR or X format codes can be used to leave whitespace in the output or to skip over unwanted data in the input. For example, either

PRINT, FORMAT = '("First", 15X, "Last")'

PRINT, FORMAT = '("First", TR15, "Last")'

results in the following output:

FirstbbbbbbbbbbbbbbbLast

where “b” represents a blank space.

These two format codes differ in one way. Using the X format code at the end of an output record will not cause any characters to be written unless it is followed by another format code that causes characters to be output. The TR format code always writes characters in this situation. Thus,

PRINT, FORMAT = '("First", 15X)'

results in the following output:

First

whereas

PRINT, FORMAT = '("First", TR15)'

results in the following output:

Firstbbbbbbbbbbbbbbb

where “b” represents a blank space. The X code does not cause the blanks to be output unless there is additional output following the blanks.

C() Format Code

The C() format code is used to transfer calendar (Julian date and/or time) data.

The syntax is:

[n]C([c₀,c₁,...,c_x])

where the parameter “n” is the repeat parameter and c_i represents optional calendar format subcodes as described below.

If no c_iare provided, the data will be transferred using the standard 24-character system format that includes the day, date, time, and year, as shown in this string:

Thu Aug 13 12:01:32 1979

For input, this default is equivalent to:

C(CDwA, X, CMoA, X, CDI, X, CHI, X, CMI, X, CSI, CYI5)

For output, this default is equivalent to:

C(CDwA, X, CMoA, X, CDI2.2, X, CHI2.2, ":", CMI2.2, ":", CSI2.2, CYI5)

Note: The C() format code represents an atomic data transfer. Nesting within the parentheses is not allowed.

Note: For input using the calendar format codes, a small offset is added to each Julian date to eliminate roundoff errors when calculating the day fraction from hours, minutes, and seconds. This offset is given by the larger of EPS and EPS*Julian, where Julian is the integer portion of the Julian date, and EPS is the EPS field from MACHAR. For typical Julian dates, this offset is approximately 6x10^–10 (which corresponds to 5x10^–5 seconds). This offset ensures that if the Julian date is converted back to hour, minute, and second, then the hour, minute, and second will have the same integer values as were originally input.

Note: Calendar dates must be in the range 1 Jan 4716 B.C.E. to 31 Dec 5000000, which corresponds to Julian values -1095 and 1827933925, respectively.

Calendar Format Subcodes

The following is a list of the subcodes allowed within the parenthesis of the C() format code.

Note: The calendar format subcodes are based on the A, I, and F format codes, and share the same options. See Syntax for additional information on the parameters not described explicitly in this section. Note that the default values of the w and d parameters are different in the calendar format subcodes than in the base A, I, and F format codes.

CMOA Subcodes

The CMOA subcodes transfers the month portion of a date as a string. The format for an all upper case month string is:

CMOA[-][w]

The format for a capitalized month string is:

CMoA[-][w]

The format for an all lower case month string is:

CmoA[-][w]

where:

w	is an optional width (0 ≤ w) specifying the number of characters of the month name to be transferred. If w is not specified, three characters will be transferred. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

Note: The case of the ‘M’ and ‘O’ of these subcodes will be ignored on input, or if the MONTHS keyword for the current routine is explicitly set.

CMOI Subcode

The CMOI subcode transfers the month portion of a date as an integer. The format is as follows:

CMOI[+][-][w][.m]

where:

is an optional width (0 ≤ w ≤ 255) specifying the width of the field in characters. The default width is 2. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

Note: The m parameter is ignored if w is zero.

CDI Subcode

The CDI subcode transfers the day portion of a date as an integer. The format is:

CDI[+][-][w][.m]

where:

Note: The m parameter is ignored if w is zero.

CYI Subcode

The CYI subcode transfers the year portion of a date as an integer. The format is as follows:

CYI[+][-][w][.m]

where:

is an optional width (0 ≤ w ≤ 255) specifying the width of the field in characters. The default width is 4. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

Note: The m parameter is ignored if w is zero.

CHI Subcodes

The CHI subcodes transfer the hour portion of a date as an integer. The format for a 24-hour based integer is:

CHI[+][-][w][.m]

The format for a 12 hour based integer is:

ChI[+][-][w][.m]

where:

Note: The m parameter is ignored if w is zero.

Note: For the ChI (12 hour format), the CAPA Subcodes may be used to specify A.M. versus P.M. For CHI (24 hour format), the CAPA subcode is ignored."

CMI Subcode

The CMI subcode transfers the minute portion of a date as an integer. The format is:

CMI[+][-][w][.m]

where:

Note: The m parameter is ignored if w is zero.

CSI Subcode

The CSI subcode transfers the seconds portion of a date as an integer. The format is:

CSI[+][-][w][.m]

where:

Note: The m parameter is ignored if w is zero.

CSF Subcode

The CSF subcode transfers the seconds portion of a date as a floating-point value. The format is:

CSF[+][-][w][.d]

where:

w	is an optional width specification (0 ≤ w ≤ 255). The variable w specifies the number of characters in the external field; the default is 5. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.
d	is an optional width specification (1 ≤ d < w). The variable d specifies the number of positions after the decimal point; the default is 2.

Overflow

The value of w must be large enough to include at least one digit to the left of the decimal point, the decimal point, and d digits to the right of the decimal point. On output, if the field provided is not wide enough, it is filled with asterisks (*) to indicate the overflow condition.

CDWA Subcodes

The CDWA subcodes transfers the day of week portion of a data as a string. The format for an all upper case day of week string is:

CDWA[-][w]

The format for a capitalized day of week string is:

CDwA[-][w]

The format for an all lower case day of week string is:

CdwA[-][w]

where:

w	is an optional width (0 ≤ w), specifying the number of characters of the day of week name to be transferred. If w is not specified, three characters will be transferred. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

Note: The case of the ‘D’ and ‘W’ of these subcodes will be ignored on input, or if the DAYS_OF_WEEK keyword for the current routine is explicitly set.

CAPA Subcodes

The CAPA subcodes transfers the A.M. or P.M. portion of a date as a string. The format for an all-uppercase A.M. or P.M. string is:

CAPA[-][w]

The format for a capitalized A.M. or P.M. string is:

CApA[-][w]

The format for an all-lowercase A.M. or P.M. string is:

CapA[-][w]

where:

w	is an optional width (0 ≤ w), specifying the number of characters of the A.M. or P.M. string to be transferred. If w is not specified, two characters will be transferred. See Padding and Natural Width Formatting for additional details on the output width of a formatted value.

Note: The case of the first ‘A’ and ‘P’ of these subcodes will be ignored on input, or if the AM_PM keyword for the current routine is explicitly set.

Note: The CAPA subcode is only used if the ChI (12 hour format) subcode is also being used. The CAPA subcode is ignored if the CHI (24 hour format) subcode is being used.

Standard Format Codes Allowed Within a Calendar Specification

None of these subcodes are allowed outside of a C() format specifier. In addition to the subcodes listed above, only quoted strings, “TL”, “TR”, and “X” format codes are allowed inside of the C() format specifier.

Example:

To print the current date in the default format:

PRINT, FORMAT='(C())', SYSTIME(/JULIAN)

The printed result should look something like:

Fri Aug 14 12:34:14 1998

Example:

To print the current date as a two-digit month value followed by a slash followed by a two-digit day value:

PRINT, FORMAT='(C(CMOI,"/",CDI))',SYSTIME(/JULIAN)

The printed result should look something like:

8/14

Example:

To print the current time in hours, minutes, and floating-point seconds, all zero-filled if necessary, and separated by colons:

PRINT, $

FORMAT='(C(CHI2.2,":",CMI2.2,":",CSF05.2))',SYSTIME(/JULIAN)

The printed result should look something like:

09:59:07.00

Note that to do zero-filling for the floating-point seconds, it is necessary to specify a leading 0 in the width to the CSF format code.

C printf-Style Format Code

Normally, to use a C printf-style format string, you specify the format string by itself. However, you can also embed a C printf-style format string within a FORTRAN-style format string by surrounding the format string with quotes and preceding the string with a % character:

%"C printf-style string"

For example:

PRINT, 3, ["See", "Hear", "Speak"], $

FORMAT='(%"I have %d monkeys named ", 3(A,:,", "))'

Executing this statement yields the output:

I have 3 monkeys named See, Hear, Speak

Here we have used a simple C printf-style code for the first part of the sentence:

%"I have %d monkeys named "

and the more powerful FORTRAN-style codes to print out the three strings with commas:

3(A,:,", ")

Here is the same example using just FORTRAN style:

PRINT, 3, ["See", "Hear", "Speak"], $

FORMAT='("I have ", I0, " monkeys named ", 3(A,:,", "))'

And here is the example using just C-style:

PRINT, 3, ["See", "Hear", "Speak"], $

FORMAT="I have %d monkeys named %s, %s, %s'

See C printf-Style Format Codes for a full list of the available C-style format codes.