The C printf-style format codes specify how data should be transferred using a format similar to that of the C printf function.

Example

Use the C printf-style to print out three numbers surrounded by brackets:

PRINT, FINDGEN(3), FORMAT = 'The values are: 'The values are: [ %f %f %f]'

IDL prints:

The values are: [ 0.000000 1.000000 2.000000]

Syntax

The syntax of a C printf-style format code is:

%[-][+][0][width]C

Where:

%

marks the beginning of a format code.
– optional, left justify the output argument.
+ optional, always print the sign (positive or negative), even for positive numbers.
0 optional, adds zero-padding on the left to match the width.

width

an optional width specification. Width specifications and default values are format-code specific, and are described with the format codes below.

C

is the format code. See below.

Supported “%” Codes

The following table lists the % format codes allowed within a printf-style quoted string format code, as well as their correspondence to the standard format codes that do the same thing. In addition to the format codes described in the table, the special sequence %% causes a single % character to be written to the output. This % is treated as a regular character instead of as a format code specifier. Finally, the flags and the width padding options described in Syntax are also available when using printf-style format codes.

Printf-Style

Description

%%

Insert a single % character.

%b, %B

%wb, %wB

%w.mb, %w.mB

Transfer data in binary notation, w is the total width, m is the minimum number of non-blank digits. There is no difference between the lowercase and uppercase forms.

%d, %D

%wd, %wD

%w.md, %w.mD

%i, %I

%wi, %wI

%w.mi, %w.mI

Transfer integer data, w is the total width, m is the minimum number of non-blank digits. There is no difference between the lowercase and uppercase forms. The %d forms are identical to the %i forms and are provided for programmers familiar with C's printf.

%e, %E

%we, %wE

%w.de, %w.dE

Transfer data in exponential notation, w is the total width, d is the number of digits after the decimal. Either a lowercase "e" or uppercase "E" will be used depending upon the code.

%f, %F

%wf, %wF

%w.df, %w.dF

Transfer data in floating-point notation, w is the total width, d is the number of digits after the decimal. There is no difference between the lowercase and uppercase forms.

%g, %G

%wg, %wG

%w.dg, %w.dG

Transfer data in either floating-point or exponential notation, w is the total width, d is the total number of significant digits. Use %e or %E if exponent is less than –4 or greater than or equal to the precision, otherwise use %f.

%o, %O

%wo, %wO

%w.mo, %w.mO

Transfer data in octal notation, w is the total width, m is the minimum number of non-blank digits. There is no difference between the lowercase and uppercase forms.

%s, %S

%ws, %wS

Transfer character data until either a null byte (\0) or the total width w is reached.

%x, %X

%wx, %wX

%w.mx, %w.mX

%z, %Z

%wz, %wZ

%w.mz, %w.mZ

Transfer data in hexadecimal notation, w is the total width, m is the minimum number of non-blank digits. The lowercase %x or %z will give lowercase hexadecimal digits, while the uppercase %X or %Z will give uppercase.

Backslash Character Escapes

IDL supports the following "escape sequences" within the format string:

Escape Sequence

ASCII code

\a, \A

BEL (7B)

\b, \B

Backspace (8B)

\f, \F

Formfeed (12B)

\n, \N

Linefeed (10B)

\r, \R

Carriage Return (13B)

\t, \T

Horizontal Tab (9B)

\v, \V

Vertical Tab (11B)

\ooo

Octal value ooo (Octal value of 1-3 digits)

\xXX

Hexadecimal value XX (Hex value of 1-2 digits)

Note: If a character not specified in this table is preceded by a backslash, the backslash is removed and the character is inserted without any special interpretation. For example, you could use \% to insert a percent character, or \" to insert a double-quote character.

Differences Between C printf and IDL printf

  • The IDL PRINT and PRINTF procedures implicitly add an end-of-line character to the end of the line. Using \n at the end of the format string to end the line is not necessary or recommended.
  • Only the % format sequences listed above are understood by IDL. Most C printf functions accept more codes than these, but those codes are not supported or not necessary. For example, the C printf/scanf functions require using the %u format code to indicate an unsigned value, and also use type modifiers (h, l, ll) to indicate the size of the data being processed. IDL uses the type of the arguments being substituted into the format to determine this information. Therefore, the u, h, l, and ll codes are not required in IDL and are not accepted.
  • The C printf function allows using %n$d notation to specify that arguments should be substituted into the format string in a different order than they are listed. IDL does not support this.
  • The C printf function allows using %*d notation to indicate that the field width will be supplied by the next argument, and the argument following that supplies the actual value. IDL does not support this.