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. The most general keyword specification for each argument contains up to six parts:

• position specifier

• flags

• field width

• precision

• word length

• conversion character

Example keywords include %f for floating point, %d for integer, and %s for string format. Use %% to obtain a single percent character. The following 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

d	Signed integer.
u	Unsigned integer.
i	Signed integer. The argument may be in hex (0x) or octal (0) format.
o	Unsigned octal.
x or X	Unsigned hexadecimal. 'x' gives lowercase results.
c	Map from an integer to the ASCII character it represents.
s	A string.
f	Floating point number in the format a.b.
e or E	Floating point number in scientific notation, a.bE+-c.
g or G	Floating 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

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:

Table 4-5. Format flags

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

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 only became useful in Tcl 8.4 where wide integer support was added. Otherwise Tcl maintains all floating point values in double-precision, and all integers as long words. Wide integers are a minimum of 64-bits wide. By adding the l (long) word length specifier, we can see the difference between regular and wide integers.

format %u -1
=> 4294967295
format %lu -1
=> 18446744073709551615