C printf-Style Quoted String Format Code

IDL's explicitly formatted specifications, which are based on those found in the FORTRAN language, are extremely powerful and capable of specifying almost any desired output. However, they require fairly verbose specifications, even in simple cases. In contrast, the C language (and the many languages influenced by C) have a different style of format specification used by functions such as printf() and snprintf(). Most programmers are very familiar with such formats. In this style, text and format codes (prefixed by a % character) are intermixed in a single string. User-supplied arguments are substituted into the format in place of the format specifiers. Although less powerful, this style of format is easier to read and write in common simple cases.

IDL supports the use of printf-style formats within format specifications, using a special variant of the Quoted String Format Code (discussed in Quoted String and H Format Codes) in which the opening quote starts with a % character (e.g. %" or %' rather than " or '). The presence of this % before the opening quote (with no whitespace between them) tells IDL that this is a printf-style quoted string and not a standard quoted string.

As a simple example, consider the following IDL statement that uses normal quoted string format codes:

PRINT, FORMAT='("I have ", I0, " monkeys, ", A, ".")', $ 
   23, 'Scott'

Executing this statement yields the output:

I have 23 monkeys, Scott.

Using a printf-style quoted string format code instead, this statement could be written:

PRINT, FORMAT='(%"I have %d monkeys, %s.")', 23, 'Scott'

These two statements are completely equivalent in their action. In fact, IDL compiles both into an identical internal representation before processing them.

The printf-style quoted string format codes can be freely mixed with any other format code, so hybrid formats like the following are allowed:

PRINT, $ 
   FORMAT='(%"I have %d monkeys, %s,", " and ", I0, " parrots.")',$ 
   23, 'Scott', 5

This generates the output:

I have 23 monkeys, Scott, and 5 parrots.

Supported "%" Formats

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 of Format Codes are also available when using printf-style format codes.

Table 18-11: Supported "%" Formats
Printf-Style	Normal-Style	Normal Style Described in Section
%[w.d]e or %[w.d]E	e[w.d] or E[w.d]	F, D, E, and G Format Codes
%[w.d]e or %[w.d]E	e[w.d] or E[w.d]	F, D, E, and G Format Codes
%[w]b or %[w]B %[w.m]b or %[w.m]B	B[w] B[w.m]	B, I, O, and Z Format Codes



%[w]d or %[w]D %[w.m]D or %[w.m]D %[w]i or %[w]I %[w.m]i or %[w.m]I	I[w] I[w.m] I[w] I[w.m]	B, I, O, and Z Format Codes



%[w]f or %[w]F %[w.d]f or %[w.d]F	F[w] F[w.d]	F, D, E, and G Format Codes
%[w]g or %[w]G %[w.d]g or %[w.d]G	g[w] or G[w] g[w.d] or G[w.d]	F, D, E, and G Format Codes
%[w]g or %[w]G %[w.d]g or %[w.d]G	g[w] or G[w] g[w.d] or G[w.d]	F, D, E, and G Format Codes
%[w]o or %[w]O %[w.m]o or %[w.m]O	O[w] O[w.m]	B, I, O, and Z Format Codes
%[w]o or %[w]O %[w.m]o or %[w.m]O	O[w] O[w.m]	B, I, O, and Z Format Codes
%[w]s or %[w]S	A[w]	A Format Code
%[w]x or %[w]X %[w.m]x or %[w.m]X %[w]z or %[w]Z %[w.m]z or %[w.m]Z	Z[w] Z[w.m] Z[w] Z[w.m]	B, I, O, and Z Format Codes

As indicated in the above table, there is a one to one correspondence between each printf-style % format code and one of the normal format codes documented earlier in this chapter. When reading this table, please keep the following considerations in mind:

The %d (or %D) format is identical to the %i (or %I) format. Note that %D does not correspond to the normal-style D format.

The w, d, m, and e parameters listed as optional parameters (i.e. between the square brackets, [ ]) are the same values documented for the normal-style format codes, and behave identically to them.

The default value for the w parameters for printf-style formatting is 0, meaning that printf-style output produces "natural" width by default. For example, a %d format code corresponds to a normal format code of I0 (not I, which would use the default value for w based on the data type). Similarly, a %e format code corresponds to a normal format code of e0 (not e).

The E and G format codes allow the following styles for compatibility with FORTRAN:

E[w.dEe] or e[w.dEe] 
G[w.dEe] or g[w.dEe] 
 These styles are not available using the printf-style format codes. In other words, the following formats are not allowed:
%[w.dEe]E or %[w.dEe]e 
%[w.dEe]G or %[w.dEe]g

Normal-style format codes allow repetition counts (e.g., 5I0). The
printf-style format codes do not allow this. Instead, each printf-style format code has an implicit repetition count of 1.

Like normal format codes (but unlike the C language printf() function), printf-style format codes are allowed to be upper or lower case (e.g. %d and %D mean the same thing). Whether or not case has an influence on the resulting output depends on the specific format code. The specific behavior is the same as with the normal-style version for each code.

Supported "\" Character Escapes

The C programming language allows "escape sequences" that start with the backslash character, \, to appear within strings. These escapes are used in several ways:

To specify characters that have no printed representation. For example, \n means linefeed, and \r means carriage return.

To remove any special meaning that a character might normally have. For example, \" allows you to create a string containing a double-quote character even though double-quote normally delimits a string. Note that backslash can also be used to escape itself, so "\\" corresponds to a string containing a single backslash character.

To introduce arbitrary characters into a string using octal or hexadecimal notation. For example, if the hexadecimal value b1 represents the ± character in the current font, then the following statement:

print, format='(%"I have \xb1%d monkeys")', 5 
 results in the following output:
I have ±5 monkeys

Although IDL does not normally support backslash escapes within strings, the escapes described in the following table are allowed within printf-style quoted string format codes. If a character not specified in this table is preceded by a backslash, the backslash is removed and the character is inserted into the output without any special interpretation. This means that \" puts a single " character into the output and that " does not terminate the string constant. Another useful example is that \% causes a single % character to be placed into the output without starting a format code. Hence, \% and %% mean the same thing: a single % character with no special meaning.

Table 18-12: Supported "\" Character Escapes
Escape Sequence	ASCII code
\a	BEL (7B)
\b	Backspace (8B)
\f	Formfeed (12B)
\n	Linefeed (10B)
\r	Carriage Return (13B)
\t	Horizontal Tab (9B)
\v	Vertical Tab (11B)
\ooo	Octal value `ooo` (Octal value of 1-3 digits)
\xhh	Hexadecimal value `hh` (Hex value of 1-2 digits)

Note
Case is ignored in escape sequences: either "\n" or "\N" specifies a linefeed character.

Differences Between C printf() and IDL printf-Style Formats

IDL's printf-style quoted string format code is very similar to a simplified C language printf() format string. However, there are important differences that an experienced C programmer should be aware of:

The IDL PRINT and PRINTF procedures implicitly add an end-of-line character to the end of the line (unless suppressed by use of the $ format code). Hence, the use of \n at the end of the format string to end the line is neither necessary nor recommended.

Only the % format sequences listed in the table under Supported "%" Formats are understood by IDL. Most C printf functions accept more codes than these, but those codes are not necessary in IDL.

For example, the C printf/scanf functions require the use of 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 % and \ sequences in IDL printf-style strings are case-insensitive. C printf is case-sensitive (e.g. \n and \N do not both mean the linefeed character as they do in IDL).

The C printf function allows the use of %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 the use of %*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.

IDL printf-style formats allow %z for hexadecimal output as well as %x. The C printf() function does not understand %z. This deviation from the usual implementation is allowed by IDL because IDL programmers are used to treating Z as the hexadecimal format code.

IDL printf-style formats allow %b for binary output. The C printf() function does not understand %b.