1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: format.n,v 1.20 2007/12/13 15:22:32 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH format n 8.1 Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
14 | .SH NAME |
---|
15 | format \- Format a string in the style of sprintf |
---|
16 | .SH SYNOPSIS |
---|
17 | \fBformat \fIformatString \fR?\fIarg arg ...\fR? |
---|
18 | .BE |
---|
19 | |
---|
20 | .SH INTRODUCTION |
---|
21 | .PP |
---|
22 | This command generates a formatted string in a fashion similar to the |
---|
23 | ANSI C \fBsprintf\fR procedure. |
---|
24 | \fIFormatString\fR indicates how to format the result, using |
---|
25 | \fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional |
---|
26 | arguments, if any, provide values to be substituted into the result. |
---|
27 | The return value from \fBformat\fR is the formatted string. |
---|
28 | .SH "DETAILS ON FORMATTING" |
---|
29 | .PP |
---|
30 | The command operates by scanning \fIformatString\fR from left to right. |
---|
31 | Each character from the format string is appended to the result |
---|
32 | string unless it is a percent sign. |
---|
33 | If the character is a \fB%\fR then it is not copied to the result string. |
---|
34 | Instead, the characters following the \fB%\fR character are treated as |
---|
35 | a conversion specifier. |
---|
36 | The conversion specifier controls the conversion of the next successive |
---|
37 | \fIarg\fR to a particular format and the result is appended to |
---|
38 | the result string in place of the conversion specifier. |
---|
39 | If there are multiple conversion specifiers in the format string, |
---|
40 | then each one controls the conversion of one additional \fIarg\fR. |
---|
41 | The \fBformat\fR command must be given enough \fIarg\fRs to meet the needs |
---|
42 | of all of the conversion specifiers in \fIformatString\fR. |
---|
43 | .PP |
---|
44 | Each conversion specifier may contain up to six different parts: |
---|
45 | an XPG3 position specifier, |
---|
46 | a set of flags, a minimum field width, a precision, a size modifier, |
---|
47 | and a conversion character. |
---|
48 | Any of these fields may be omitted except for the conversion character. |
---|
49 | The fields that are present must appear in the order given above. |
---|
50 | The paragraphs below discuss each of these fields in turn. |
---|
51 | .PP |
---|
52 | If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in |
---|
53 | .QW \fB%2$d\fR , |
---|
54 | then the value to convert is not taken from the next sequential argument. |
---|
55 | Instead, it is taken from the argument indicated by the number, |
---|
56 | where 1 corresponds to the first \fIarg\fR. |
---|
57 | If the conversion specifier requires multiple arguments because |
---|
58 | of \fB*\fR characters in the specifier then |
---|
59 | successive arguments are used, starting with the argument |
---|
60 | given by the number. |
---|
61 | This follows the XPG3 conventions for positional specifiers. |
---|
62 | If there are any positional specifiers in \fIformatString\fR |
---|
63 | then all of the specifiers must be positional. |
---|
64 | .PP |
---|
65 | The second portion of a conversion specifier may contain any of the |
---|
66 | following flag characters, in any order: |
---|
67 | .TP 10 |
---|
68 | \fB\-\fR |
---|
69 | Specifies that the converted argument should be left-justified |
---|
70 | in its field (numbers are normally right-justified with leading |
---|
71 | spaces if needed). |
---|
72 | .TP 10 |
---|
73 | \fB+\fR |
---|
74 | Specifies that a number should always be printed with a sign, |
---|
75 | even if positive. |
---|
76 | .TP 10 |
---|
77 | \fIspace\fR |
---|
78 | Specifies that a space should be added to the beginning of the |
---|
79 | number if the first character is not a sign. |
---|
80 | .TP 10 |
---|
81 | \fB0\fR |
---|
82 | Specifies that the number should be padded on the left with |
---|
83 | zeroes instead of spaces. |
---|
84 | .TP 10 |
---|
85 | \fB#\fR |
---|
86 | Requests an alternate output form. For \fBo\fR and \fBO\fR |
---|
87 | conversions it guarantees that the first digit is always \fB0\fR. |
---|
88 | For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively) |
---|
89 | will be added to the beginning of the result unless it is zero. |
---|
90 | For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR, |
---|
91 | \fBg\fR, and \fBG\fR) it guarantees that the result always |
---|
92 | has a decimal point. |
---|
93 | For \fBg\fR and \fBG\fR conversions it specifies that |
---|
94 | trailing zeroes should not be removed. |
---|
95 | .PP |
---|
96 | The third portion of a conversion specifier is a decimal number giving a |
---|
97 | minimum field width for this conversion. |
---|
98 | It is typically used to make columns line up in tabular printouts. |
---|
99 | If the converted argument contains fewer characters than the |
---|
100 | minimum field width then it will be padded so that it is as wide |
---|
101 | as the minimum field width. |
---|
102 | Padding normally occurs by adding extra spaces on the left of the |
---|
103 | converted argument, but the \fB0\fR and \fB\-\fR flags |
---|
104 | may be used to specify padding with zeroes on the left or with |
---|
105 | spaces on the right, respectively. |
---|
106 | If the minimum field width is specified as \fB*\fR rather than |
---|
107 | a number, then the next argument to the \fBformat\fR command |
---|
108 | determines the minimum field width; it must be an integer value. |
---|
109 | .PP |
---|
110 | The fourth portion of a conversion specifier is a precision, |
---|
111 | which consists of a period followed by a number. |
---|
112 | The number is used in different ways for different conversions. |
---|
113 | For \fBe\fR, \fBE\fR, and \fBf\fR conversions it specifies the number |
---|
114 | of digits to appear to the right of the decimal point. |
---|
115 | For \fBg\fR and \fBG\fR conversions it specifies the total number |
---|
116 | of digits to appear, including those on both sides of the decimal |
---|
117 | point (however, trailing zeroes after the decimal point will still |
---|
118 | be omitted unless the \fB#\fR flag has been specified). |
---|
119 | For integer conversions, it specifies a minimum number of digits |
---|
120 | to print (leading zeroes will be added if necessary). |
---|
121 | For \fBs\fR conversions it specifies the maximum number of characters to be |
---|
122 | printed; if the string is longer than this then the trailing characters will be dropped. |
---|
123 | If the precision is specified with \fB*\fR rather than a number |
---|
124 | then the next argument to the \fBformat\fR command determines the precision; |
---|
125 | it must be a numeric string. |
---|
126 | .PP |
---|
127 | The fifth part of a conversion specifier is a size modifier, |
---|
128 | which must be \fBll\fR, \fBh\fR, or \fBl\fR. |
---|
129 | If it is \fBll\fR it specifies that an integer value is taken |
---|
130 | without truncation for conversion to a formatted substring. |
---|
131 | If it is \fBh\fR it specifies that an integer value is |
---|
132 | truncated to a 16-bit range before converting. This option is rarely useful. |
---|
133 | If it is \fBl\fR it specifies that the integer value is |
---|
134 | truncated to the same range as that produced by the \fBwide()\fR |
---|
135 | function of the \fBexpr\fR command (at least a 64-bit range). |
---|
136 | If neither \fBh\fR nor \fBl\fR are present, the integer value is |
---|
137 | truncated to the same range as that produced by the \fBint()\fR |
---|
138 | function of the \fBexpr\fR command (at least a 32-bit range, but |
---|
139 | determined by the value of \fBtcl_platform(wordSize)\fR). |
---|
140 | .PP |
---|
141 | The last thing in a conversion specifier is an alphabetic character |
---|
142 | that determines what kind of conversion to perform. |
---|
143 | The following conversion characters are currently supported: |
---|
144 | .TP 10 |
---|
145 | \fBd\fR |
---|
146 | Convert integer to signed decimal string. |
---|
147 | .TP 10 |
---|
148 | \fBu\fR |
---|
149 | Convert integer to unsigned decimal string. |
---|
150 | .TP 10 |
---|
151 | \fBi\fR |
---|
152 | Convert integer to signed decimal string (equivalent to \fBd\fR). |
---|
153 | .TP 10 |
---|
154 | \fBo\fR |
---|
155 | Convert integer to unsigned octal string. |
---|
156 | .TP 10 |
---|
157 | \fBx\fR or \fBX\fR |
---|
158 | Convert integer to unsigned hexadecimal string, using digits |
---|
159 | .QW 0123456789abcdef |
---|
160 | for \fBx\fR and |
---|
161 | .QW 0123456789ABCDEF |
---|
162 | for \fBX\fR). |
---|
163 | .TP 10 |
---|
164 | \fBc\fR |
---|
165 | Convert integer to the Unicode character it represents. |
---|
166 | .TP 10 |
---|
167 | \fBs\fR |
---|
168 | No conversion; just insert string. |
---|
169 | .TP 10 |
---|
170 | \fBf\fR |
---|
171 | Convert number to signed decimal string of |
---|
172 | the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by |
---|
173 | the precision (default: 6). |
---|
174 | If the precision is 0 then no decimal point is output. |
---|
175 | .TP 10 |
---|
176 | \fBe\fR or \fBE\fR |
---|
177 | Convert number to scientific notation in the |
---|
178 | form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined |
---|
179 | by the precision (default: 6). |
---|
180 | If the precision is 0 then no decimal point is output. |
---|
181 | If the \fBE\fR form is used then \fBE\fR is |
---|
182 | printed instead of \fBe\fR. |
---|
183 | .TP 10 |
---|
184 | \fBg\fR or \fBG\fR |
---|
185 | If the exponent is less than \-4 or greater than or equal to the |
---|
186 | precision, then convert number as for \fB%e\fR or |
---|
187 | \fB%E\fR. |
---|
188 | Otherwise convert as for \fB%f\fR. |
---|
189 | Trailing zeroes and a trailing decimal point are omitted. |
---|
190 | .TP 10 |
---|
191 | \fB%\fR |
---|
192 | No conversion: just insert \fB%\fR. |
---|
193 | .SH "DIFFERENCES FROM ANSI SPRINTF" |
---|
194 | .PP |
---|
195 | The behavior of the format command is the same as the |
---|
196 | ANSI C \fBsprintf\fR procedure except for the following |
---|
197 | differences: |
---|
198 | .IP [1] |
---|
199 | \fB%p\fR and \fB%n\fR specifiers are not supported. |
---|
200 | .IP [2] |
---|
201 | For \fB%c\fR conversions the argument must be an integer value, |
---|
202 | which will then be converted to the corresponding character value. |
---|
203 | .IP [3] |
---|
204 | The size modifiers are ignored when formatting floating-point values. |
---|
205 | The \fBll\fR modifier has no \fBsprintf\fR counterpart. |
---|
206 | .SH EXAMPLES |
---|
207 | Convert the numeric value of a UNICODE character to the character |
---|
208 | itself: |
---|
209 | .CS |
---|
210 | set value 120 |
---|
211 | set char [\fBformat\fR %c $value] |
---|
212 | .CE |
---|
213 | .PP |
---|
214 | Convert the output of \fBtime\fR into seconds to an accuracy of |
---|
215 | hundredths of a second: |
---|
216 | .CS |
---|
217 | set us [lindex [time $someTclCode] 0] |
---|
218 | puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]] |
---|
219 | .CE |
---|
220 | .PP |
---|
221 | Create a packed X11 literal color specification: |
---|
222 | .CS |
---|
223 | # Each color-component should be in range (0..255) |
---|
224 | set color [\fBformat\fR "#%02x%02x%02x" $r $g $b] |
---|
225 | .CE |
---|
226 | .PP |
---|
227 | Use XPG3 format codes to allow reordering of fields (a technique that |
---|
228 | is often used in localized message catalogs; see \fBmsgcat\fR) without |
---|
229 | reordering the data values passed to \fBformat\fR: |
---|
230 | .CS |
---|
231 | set fmt1 "Today, %d shares in %s were bought at $%.2f each" |
---|
232 | puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37] |
---|
233 | |
---|
234 | set fmt2 "Bought %2\e$s equity ($%3$.2f x %1\e$d) today" |
---|
235 | puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37] |
---|
236 | .CE |
---|
237 | .PP |
---|
238 | Print a small table of powers of three: |
---|
239 | .CS |
---|
240 | # Set up the column widths |
---|
241 | set w1 5 |
---|
242 | set w2 10 |
---|
243 | |
---|
244 | # Make a nice header (with separator) for the table first |
---|
245 | set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+ |
---|
246 | puts $sep |
---|
247 | puts [\fBformat\fR "| %-*s | %-*s |" $w1 "Index" $w2 "Power"] |
---|
248 | puts $sep |
---|
249 | |
---|
250 | # Print the contents of the table |
---|
251 | set p 1 |
---|
252 | for {set i 0} {$i<=20} {incr i} { |
---|
253 | puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p] |
---|
254 | set p [expr {wide($p) * 3}] |
---|
255 | } |
---|
256 | |
---|
257 | # Finish off by printing the separator again |
---|
258 | puts $sep |
---|
259 | .CE |
---|
260 | .SH "SEE ALSO" |
---|
261 | scan(n), sprintf(3), string(n) |
---|
262 | .SH KEYWORDS |
---|
263 | conversion specifier, format, sprintf, string, substitution |
---|