util/src/TclTk/tcl8.6.12/doc/format.n

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