format(n) Tcl Built-In Commands format(n)_________________________________________________________________NAMEformat - Format a string in the style of sprintf
SYNOPSISformat formatString ?arg arg ...?
_________________________________________________________________INTRODUCTION
This command generates a formatted string in the same way
as the ANSI C sprintf procedure (it uses sprintf in its
implementation). FormatString indicates how to format the
result, using % conversion specifiers as in sprintf, and
the additional arguments, if any, provide values to be
substituted into the result. The return value from format
is the formatted string.
DETAILS ON FORMATTING
The command operates by scanning formatString from left to
right. Each character from the format string is appended
to the result string unless it is a percent sign. If the
character is a % then it is not copied to the result
string. Instead, the characters following the % character
are treated as a conversion specifier. The conversion
specifier controls the conversion of the next successive
arg to a particular format and the result is appended to
the result string in place of the conversion specifier.
If there are multiple conversion specifiers in the format
string, then each one controls the conversion of one addi-
tional arg. The format command must be given enough args
to meet the needs of all of the conversion specifiers in
formatString.
Each conversion specifier may contain up to six different
parts: an XPG3 position specifier, a set of flags, a mini-
mum field width, a precision, a length modifier, and a
conversion character. Any of these fields may be omitted
except for the conversion character. The fields that are
present must appear in the order given above. The para-
graphs below discuss each of these fields in turn.
If the % is followed by a decimal number and a $, as in
``%2$d'', then the value to convert is not taken from the
next sequential argument. Instead, it is taken from the
argument indicated by the number, where 1 corresponds to
the first arg. If the conversion specifier requires mul-
tiple arguments because of * characters in the specifier
then successive arguments are used, starting with the
argument given by the number. This follows the XPG3 con-
ventions for positional specifiers. If there are any
positional specifiers in formatString then all of the
Tcl 1
format(n) Tcl Built-In Commands format(n)
specifiers must be positional.
The second portion of a conversion specifier may contain
any of the following flag characters, in any order:
- Specifies that the converted argument should be
left-justified in its field (numbers are nor-
mally right-justified with leading spaces if
needed).
+ Specifies that a number should always be printed
with a sign, even if positive.
space Specifies that a space should be added to the
beginning of the number if the first character
isn't a sign.
0 Specifies that the number should be padded on
the left with zeroes instead of spaces.
# Requests an alternate output form. For o and O
conversions it guarantees that the first digit
is always 0. For x or X conversions, 0x or 0X
(respectively) will be added to the beginning of
the result unless it is zero. For all floating-
point conversions (e, E, f, g, and G) it guaran-
tees that the result always has a decimal point.
For g and G conversions it specifies that trail-
ing zeroes should not be removed.
The third portion of a conversion specifier is a number
giving a minimum field width for this conversion. It is
typically used to make columns line up in tabular print-
outs. If the converted argument contains fewer characters
than the minimum field width then it will be padded so
that it is as wide as the minimum field width. Padding
normally occurs by adding extra spaces on the left of the
converted argument, but the 0 and - flags may be used to
specify padding with zeroes on the left or with spaces on
the right, respectively. If the minimum field width is
specified as * rather than a number, then the next argu-
ment to the format command determines the minimum field
width; it must be a numeric string.
The fourth portion of a conversion specifier is a preci-
sion, which consists of a period followed by a number.
The number is used in different ways for different conver-
sions. For e, E, and f conversions it specifies the num-
ber of digits to appear to the right of the decimal point.
For g and G conversions it specifies the total number of
digits to appear, including those on both sides of the
decimal point (however, trailing zeroes after the decimal
point will still be omitted unless the # flag has been
specified). For integer conversions, it specifies a
Tcl 2
format(n) Tcl Built-In Commands format(n)
minimum number of digits to print (leading zeroes will be
added if necessary). For s conversions it specifies the
maximum number of characters to be printed; if the string
is longer than this then the trailing characters will be
dropped. If the precision is specified with * rather than
a number then the next argument to the format command
determines the precision; it must be a numeric string.
The fifth part of a conversion specifier is a length modi-
fier, which must be h or l. If it is h it specifies that
the numeric value should be truncated to a 16-bit value
before converting. This option is rarely useful. The l
modifier is ignored.
The last thing in a conversion specifier is an alphabetic
character that determines what kind of conversion to per-
form. The following conversion characters are currently
supported:
d Convert integer to signed decimal string.
u Convert integer to unsigned decimal string.
i Convert integer to signed decimal string; the
integer may either be in decimal, in octal (with
a leading 0) or in hexadecimal (with a leading
0x).
o Convert integer to unsigned octal string.
x or X Convert integer to unsigned hexadecimal string,
using digits ``0123456789abcdef'' for x and
``0123456789ABCDEF'' for X).
c Convert integer to the 8-bit character it repre-
sents.
s No conversion; just insert string.
f Convert floating-point number to signed decimal
string of the form xx.yyy, where the number of
y's is determined by the precision (default: 6).
If the precision is 0 then no decimal point is
output.
e or e Convert floating-point number to scientific
notation in the form x.yyye+-zz, where the num-
ber of y's is determined by the precision
(default: 6). If the precision is 0 then no
decimal point is output. If the E form is used
then E is printed instead of e.
g or G If the exponent is less than -4 or greater than
or equal to the precision, then convert
Tcl 3
format(n) Tcl Built-In Commands format(n)
floating-point number as for %e or %E. Other-
wise convert as for %f. Trailing zeroes and a
trailing decimal point are omitted.
% No conversion: just insert %.
For the numerical conversions the argument being converted
must be an integer or floating-point string; format con-
verts the argument to binary and then converts it back to
a string according to the conversion specifier.
DIFFERENCES FROM ANSI SPRINTF
The behavior of the format command is the same as the ANSI
C sprintf procedure except for the following differences:
[1] %p and %n specifiers are not currently supported.
[2] For %c conversions the argument must be a decimal
string, which will then be converted to the corre-
sponding character value.
[3] The l modifier is ignored; integer values are
always converted as if there were no modifier pre-
sent and real values are always converted as if the
l modifier were present (i.e. type double is used
for the internal representation). If the h modi-
fier is specified then integer values are truncated
to short before conversion.
KEYWORDS
conversion specifier, format, sprintf, string, substitu-
tion
Tcl 4