231 lines
11 KiB
HTML
231 lines
11 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - format manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="format.htm#M2" NAME="L403">NAME</A>
|
|
<DL><DD>format - Format a string in the style of sprintf</DL>
|
|
<DD><A HREF="format.htm#M3" NAME="L404">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>format </B><I>formatString </I>?<I>arg arg ...</I>?
|
|
</DL>
|
|
<DD><A HREF="format.htm#M4" NAME="L405">INTRODUCTION</A>
|
|
<DD><A HREF="format.htm#M5" NAME="L406">DETAILS ON FORMATTING</A>
|
|
<DL>
|
|
<DD><A HREF="format.htm#M6" NAME="L407"><B>-</B></A>
|
|
<DD><A HREF="format.htm#M7" NAME="L408"><B>+</B></A>
|
|
<DD><A HREF="format.htm#M8" NAME="L409"><I>space</I></A>
|
|
<DD><A HREF="format.htm#M9" NAME="L410"><B>0</B></A>
|
|
<DD><A HREF="format.htm#M10" NAME="L411"><B>#</B></A>
|
|
</DL>
|
|
<DL>
|
|
<DD><A HREF="format.htm#M11" NAME="L412"><B>d</B></A>
|
|
<DD><A HREF="format.htm#M12" NAME="L413"><B>u</B></A>
|
|
<DD><A HREF="format.htm#M13" NAME="L414"><B>i</B></A>
|
|
<DD><A HREF="format.htm#M14" NAME="L415"><B>o</B></A>
|
|
<DD><A HREF="format.htm#M15" NAME="L416"><B>x</B> or <B>X</B></A>
|
|
<DD><A HREF="format.htm#M16" NAME="L417"><B>c</B></A>
|
|
<DD><A HREF="format.htm#M17" NAME="L418"><B>s</B></A>
|
|
<DD><A HREF="format.htm#M18" NAME="L419"><B>f</B></A>
|
|
<DD><A HREF="format.htm#M19" NAME="L420"><B>e</B> or <B>e</B></A>
|
|
<DD><A HREF="format.htm#M20" NAME="L421"><B>g</B> or <B>G</B></A>
|
|
<DD><A HREF="format.htm#M21" NAME="L422"><B>%</B></A>
|
|
</DL>
|
|
<DD><A HREF="format.htm#M22" NAME="L423">DIFFERENCES FROM ANSI SPRINTF</A>
|
|
<DL>
|
|
</DL>
|
|
<DD><A HREF="format.htm#M23" NAME="L424">SEE ALSO</A>
|
|
<DD><A HREF="format.htm#M24" NAME="L425">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
format - Format a string in the style of sprintf
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>format </B><I>formatString </I>?<I>arg arg ...</I>?<BR>
|
|
<H3><A NAME="M4">INTRODUCTION</A></H3>
|
|
This command generates a formatted string in the same way as the
|
|
ANSI C <B>sprintf</B> procedure (it uses <B>sprintf</B> in its
|
|
implementation).
|
|
<I>FormatString</I> indicates how to format the result, using
|
|
<B>%</B> conversion specifiers as in <B>sprintf</B>, and the additional
|
|
arguments, if any, provide values to be substituted into the result.
|
|
The return value from <B>format</B> is the formatted string.
|
|
|
|
<H3><A NAME="M5">DETAILS ON FORMATTING</A></H3>
|
|
The command operates by scanning <I>formatString</I> 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 <B>%</B> then it is not copied to the result string.
|
|
Instead, the characters following the <B>%</B> character are treated as
|
|
a conversion specifier.
|
|
The conversion specifier controls the conversion of the next successive
|
|
<I>arg</I> 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 additional <I>arg</I>.
|
|
The <B>format</B> command must be given enough <I>arg</I>s to meet the needs
|
|
of all of the conversion specifiers in <I>formatString</I>.
|
|
<P>
|
|
Each conversion specifier may contain up to six different parts:
|
|
an XPG3 position specifier,
|
|
a set of flags, a minimum 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 paragraphs below discuss each of these fields in turn.
|
|
<P>
|
|
If the <B>%</B> is followed by a decimal number and a <B>$</B>, as in
|
|
``<B>%2$d</B>'', 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 <I>arg</I>.
|
|
If the conversion specifier requires multiple arguments because
|
|
of <B>*</B> characters in the specifier then
|
|
successive arguments are used, starting with the argument
|
|
given by the number.
|
|
This follows the XPG3 conventions for positional specifiers.
|
|
If there are any positional specifiers in <I>formatString</I>
|
|
then all of the specifiers must be positional.
|
|
<P>
|
|
The second portion of a conversion specifier may contain any of the
|
|
following flag characters, in any order:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M6"><B>-</B></A><DD>
|
|
Specifies that the converted argument should be left-justified
|
|
in its field (numbers are normally right-justified with leading
|
|
spaces if needed).
|
|
<P><DT><A NAME="M7"><B>+</B></A><DD>
|
|
Specifies that a number should always be printed with a sign,
|
|
even if positive.
|
|
<P><DT><A NAME="M8"><I>space</I></A><DD>
|
|
Specifies that a space should be added to the beginning of the
|
|
number if the first character isn't a sign.
|
|
<P><DT><A NAME="M9"><B>0</B></A><DD>
|
|
Specifies that the number should be padded on the left with
|
|
zeroes instead of spaces.
|
|
<P><DT><A NAME="M10"><B>#</B></A><DD>
|
|
Requests an alternate output form. For <B>o</B> and <B>O</B>
|
|
conversions it guarantees that the first digit is always <B>0</B>.
|
|
For <B>x</B> or <B>X</B> conversions, <B>0x</B> or <B>0X</B> (respectively)
|
|
will be added to the beginning of the result unless it is zero.
|
|
For all floating-point conversions (<B>e</B>, <B>E</B>, <B>f</B>,
|
|
<B>g</B>, and <B>G</B>) it guarantees that the result always
|
|
has a decimal point.
|
|
For <B>g</B> and <B>G</B> conversions it specifies that
|
|
trailing zeroes should not be removed.
|
|
<P></DL>
|
|
<P>
|
|
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 printouts.
|
|
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 <B>0</B> and <B>-</B> 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 <B>*</B> rather than
|
|
a number, then the next argument to the <B>format</B> command
|
|
determines the minimum field width; it must be a numeric string.
|
|
<P>
|
|
The fourth portion of a conversion specifier is a precision,
|
|
which consists of a period followed by a number.
|
|
The number is used in different ways for different conversions.
|
|
For <B>e</B>, <B>E</B>, and <B>f</B> conversions it specifies the number
|
|
of digits to appear to the right of the decimal point.
|
|
For <B>g</B> and <B>G</B> 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 <B>#</B> flag has been specified).
|
|
For integer conversions, it specifies a minimum number of digits
|
|
to print (leading zeroes will be added if necessary).
|
|
For <B>s</B> 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 <B>*</B> rather than a number
|
|
then the next argument to the <B>format</B> command determines the precision;
|
|
it must be a numeric string.
|
|
<P>
|
|
The fifth part of a conversion specifier is a length modifier,
|
|
which must be <B>h</B> or <B>l</B>.
|
|
If it is <B>h</B> it specifies that the numeric value should be
|
|
truncated to a 16-bit value before converting.
|
|
This option is rarely useful.
|
|
The <B>l</B> modifier is ignored.
|
|
<P>
|
|
The last thing in a conversion specifier is an alphabetic character
|
|
that determines what kind of conversion to perform.
|
|
The following conversion characters are currently supported:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M11"><B>d</B></A><DD>
|
|
Convert integer to signed decimal string.
|
|
<P><DT><A NAME="M12"><B>u</B></A><DD>
|
|
Convert integer to unsigned decimal string.
|
|
<P><DT><A NAME="M13"><B>i</B></A><DD>
|
|
Convert integer to signed decimal string; the integer may either be
|
|
in decimal, in octal (with a leading <B>0</B>) or in hexadecimal
|
|
(with a leading <B>0x</B>).
|
|
<P><DT><A NAME="M14"><B>o</B></A><DD>
|
|
Convert integer to unsigned octal string.
|
|
<P><DT><A NAME="M15"><B>x</B> or <B>X</B></A><DD>
|
|
Convert integer to unsigned hexadecimal string, using digits
|
|
``0123456789abcdef'' for <B>x</B> and ``0123456789ABCDEF'' for <B>X</B>).
|
|
<P><DT><A NAME="M16"><B>c</B></A><DD>
|
|
Convert integer to the Unicode character it represents.
|
|
<P><DT><A NAME="M17"><B>s</B></A><DD>
|
|
No conversion; just insert string.
|
|
<P><DT><A NAME="M18"><B>f</B></A><DD>
|
|
Convert floating-point number to signed decimal string of
|
|
the form <I>xx.yyy</I>, where the number of <I>y</I>'s is determined by
|
|
the precision (default: 6).
|
|
If the precision is 0 then no decimal point is output.
|
|
<P><DT><A NAME="M19"><B>e</B> or <B>e</B></A><DD>
|
|
Convert floating-point number to scientific notation in the
|
|
form <I>x.yyy</I><B>e±</B><I>zz</I>, where the number of <I>y</I>'s is determined
|
|
by the precision (default: 6).
|
|
If the precision is 0 then no decimal point is output.
|
|
If the <B>E</B> form is used then <B>E</B> is
|
|
printed instead of <B>e</B>.
|
|
<P><DT><A NAME="M20"><B>g</B> or <B>G</B></A><DD>
|
|
If the exponent is less than -4 or greater than or equal to the
|
|
precision, then convert floating-point number as for <B>%e</B> or
|
|
<B>%E</B>.
|
|
Otherwise convert as for <B>%f</B>.
|
|
Trailing zeroes and a trailing decimal point are omitted.
|
|
<P><DT><A NAME="M21"><B>%</B></A><DD>
|
|
No conversion: just insert <B>%</B>.
|
|
<P></DL>
|
|
<P>
|
|
For the numerical conversions the argument being converted must
|
|
be an integer or floating-point string; format converts the argument
|
|
to binary and then converts it back to a string according to
|
|
the conversion specifier.
|
|
|
|
<H3><A NAME="M22">DIFFERENCES FROM ANSI SPRINTF</A></H3>
|
|
The behavior of the format command is the same as the
|
|
ANSI C <B>sprintf</B> procedure except for the following
|
|
differences:
|
|
<P>
|
|
<DL>
|
|
<P><DT>[1]<DD>
|
|
<B>%p</B> and <B>%n</B> specifiers are not currently supported.
|
|
<P><DT>[2]<DD>
|
|
For <B>%c</B> conversions the argument must be a decimal string,
|
|
which will then be converted to the corresponding character value.
|
|
<P><DT>[3]<DD>
|
|
The <B>l</B> modifier is ignored; integer values are always converted
|
|
as if there were no modifier present and real values are always
|
|
converted as if the <B>l</B> modifier were present (i.e. type
|
|
<B>double</B> is used for the internal representation).
|
|
If the <B>h</B> modifier is specified then integer values are truncated
|
|
to <B>short</B> before conversion.
|
|
|
|
<P></DL>
|
|
<H3><A NAME="M23">SEE ALSO</A></H3>
|
|
<B>sprintf</B>, <B><A HREF="../TkCmd/string.htm">string</A></B>
|
|
<H3><A NAME="M24">KEYWORDS</A></H3>
|
|
<A href="../Keywords/C.htm#conversion specifier">conversion specifier</A>, <A href="../Keywords/F.htm#format">format</A>, <A href="../Keywords/S.htm#sprintf">sprintf</A>, <A href="../Keywords/S.htm#string">string</A>, <A href="../Keywords/S.htm#substitution">substitution</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|