Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 4.  String Processing in Tcl

The format Command

The format command is similar to the C printf function. It formats a string according to a format specification:

format spec value1 value2 ...

The spec argument includes literals and keywords. The literals are placed in the result as is, while each keyword indicates how to format the corresponding argument. The keywords are introduced with a percent sign, %, followed by zero or more modifiers, and terminate with a conversion specifier. Example keywords include %f for floating point, %d for integer, and %s for string format. Use %% to obtain a single percent character. The most general keyword specification for each argument contains up to six parts:

  • position specifier

  • flags

  • field width

  • precision

  • word length

  • conversion character

These components are explained by a series of examples. The examples use double quotes around the format specification. This is because often the format contains white space, so grouping is required, as well as backslash substitutions like \t or \n, and the quotes allow substitution of these special characters. Table 4-4 lists the conversion characters:

Table 4-4. Format conversions.
dSigned integer.
uUnsigned integer.
iSigned integer. The argument may be in hex (0x) or octal (0) format.
oUnsigned octal.
x or XUnsigned hexadecimal. 'x' gives lowercase results.
cMap from an integer to the ASCII character it represents.
sA string.
fFloating point number in the format a.b.
e or EFloating point number in scientific notation, a.bE+-c.
g or GFloating point number in either %f or %e format, whichever is shorter.

A position specifier is i$, which means take the value from argument i as opposed to the normally corresponding argument. The position counts from 1. If a position is specified for one format keyword, the position must be used for all of them. If you group the format specification with double quotes, you need to quote the $ with a backslash:

set lang 2
format "%${lang}\$s" one un uno
=> un

The position specifier is useful for picking a string from a set, such as this simple language-specific example. The message catalog facility described in Chapter 15 is a much more sophisticated way to solve this problem. The position is also useful if the same value is repeated in the formatted string.

The flags in a format are used to specify padding and justification. In the following examples, the # causes a leading 0x to be printed in the hexadecimal value. The zero in 08 causes the field to be padded with zeros. Table 4-5 summarizes the format flag characters.

format "%#x" 20
=> 0x14
format "%#08x" 10
=> 0x0000000a

Table 4-5. Format flags.
-Left justify the field.
+Always include a sign, either + or -.
spacePrecede a number with a space, unless the number has a leading sign. Useful for packing numbers close together.
0Pad with zeros.
#Leading 0 for octal. Leading 0x for hex. Always include a decimal point in floating point. Do not remove trailing zeros (%g).

After the flags you can specify a minimum field width value. The value is padded to this width with spaces, or with zeros if the 0 flag is used:

format "%-20s %3d" Label 2
=> Label               2

You can compute a field width and pass it to format as one of the arguments by using * as the field width specifier. In this case the next argument is used as the field width instead of the value, and the argument after that is the value that gets formatted.

set maxl 8
format "%-*s = %s" $maxl Key Value
=> Key     = Value

The precision comes next, and it is specified with a period and a number. For %f and %e it indicates how many digits come after the decimal point. For %g it indicates the total number of significant digits used. For %d and %x it indicates how many digits will be printed, padding with zeros if necessary.

format "%6.2f %6.2d" 1 1
=>   1.00     01

The storage length part comes last but it is rarely useful because Tcl maintains all floating point values in double-precision, and all integers as long words.

      Previous section   Next section