diff options
Diffstat (limited to 'tcl8.6/doc/format.n')
-rw-r--r-- | tcl8.6/doc/format.n | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/tcl8.6/doc/format.n b/tcl8.6/doc/format.n new file mode 100644 index 0000000..ba044f2 --- /dev/null +++ b/tcl8.6/doc/format.n @@ -0,0 +1,285 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH format n 8.1 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +format \- Format a string in the style of sprintf +.SH SYNOPSIS +\fBformat \fIformatString \fR?\fIarg arg ...\fR? +.BE + +.SH INTRODUCTION +.PP +This command generates a formatted string in a fashion similar to the +ANSI C \fBsprintf\fR procedure. +\fIFormatString\fR indicates how to format the result, using +\fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional +arguments, if any, provide values to be substituted into the result. +The return value from \fBformat\fR is the formatted string. +.SH "DETAILS ON FORMATTING" +.PP +The command operates by scanning \fIformatString\fR 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 \fB%\fR then it is not copied to the result string. +Instead, the characters following the \fB%\fR character are treated as +a conversion specifier. +The conversion specifier controls the conversion of the next successive +\fIarg\fR 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 \fIarg\fR. +The \fBformat\fR command must be given enough \fIarg\fRs to meet the needs +of all of the conversion specifiers in \fIformatString\fR. +.PP +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 size 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. +.SS "OPTIONAL POSITIONAL SPECIFIER" +.PP +If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in +.QW \fB%2$d\fR , +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 \fIarg\fR. +If the conversion specifier requires multiple arguments because +of \fB*\fR 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 \fIformatString\fR +then all of the specifiers must be positional. +.SS "OPTIONAL FLAGS" +.PP +The second portion of a conversion specifier may contain any of the +following flag characters, in any order: +.TP 10 +\fB\-\fR +Specifies that the converted argument should be left-justified +in its field (numbers are normally right-justified with leading +spaces if needed). +.TP 10 +\fB+\fR +Specifies that a number should always be printed with a sign, +even if positive. +.TP 10 +\fIspace\fR +Specifies that a space should be added to the beginning of the +number if the first character is not a sign. +.TP 10 +\fB0\fR +Specifies that the number should be padded on the left with +zeroes instead of spaces. +.TP 10 +\fB#\fR +Requests an alternate output form. For \fBo\fR and \fBO\fR +conversions it guarantees that the first digit is always \fB0\fR. +For \fBx\fR or \fBX\fR conversions, \fB0x\fR or \fB0X\fR (respectively) +will be added to the beginning of the result unless it is zero. +For \fBb\fR conversions, \fB0b\fR +will be added to the beginning of the result unless it is zero. +For all floating-point conversions (\fBe\fR, \fBE\fR, \fBf\fR, +\fBg\fR, and \fBG\fR) it guarantees that the result always +has a decimal point. +For \fBg\fR and \fBG\fR conversions it specifies that +trailing zeroes should not be removed. +.SS "OPTIONAL FIELD WIDTH" +.PP +The third portion of a conversion specifier is a decimal 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 \fB0\fR and \fB\-\fR 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 \fB*\fR rather than +a number, then the next argument to the \fBformat\fR command +determines the minimum field width; it must be an integer value. +.SS "OPTIONAL PRECISION/BOUND" +.PP +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 \fBe\fR, \fBE\fR, and \fBf\fR conversions it specifies the number +of digits to appear to the right of the decimal point. +For \fBg\fR and \fBG\fR 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 \fB#\fR flag has been specified). +For integer conversions, it specifies a minimum number of digits +to print (leading zeroes will be added if necessary). +For \fBs\fR 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 \fB*\fR rather than a number +then the next argument to the \fBformat\fR command determines the precision; +it must be a numeric string. +.SS "OPTIONAL SIZE MODIFIER" +.PP +The fifth part of a conversion specifier is a size modifier, +which must be \fBll\fR, \fBh\fR, or \fBl\fR. +If it is \fBll\fR it specifies that an integer value is taken +without truncation for conversion to a formatted substring. +If it is \fBh\fR it specifies that an integer value is +truncated to a 16-bit range before converting. This option is rarely useful. +If it is \fBl\fR it specifies that the integer value is +truncated to the same range as that produced by the \fBwide()\fR +function of the \fBexpr\fR command (at least a 64-bit range). +If neither \fBh\fR nor \fBl\fR are present, the integer value is +truncated to the same range as that produced by the \fBint()\fR +function of the \fBexpr\fR command (at least a 32-bit range, but +determined by the value of the \fBwordSize\fR element of the +\fBtcl_platform\fR array). +.SS "MANDATORY CONVERSION TYPE" +.PP +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: +.TP 10 +\fBd\fR +Convert integer to signed decimal string. +.TP 10 +\fBu\fR +Convert integer to unsigned decimal string. +.TP 10 +\fBi\fR +Convert integer to signed decimal string (equivalent to \fBd\fR). +.TP 10 +\fBo\fR +Convert integer to unsigned octal string. +.TP 10 +\fBx\fR or \fBX\fR +Convert integer to unsigned hexadecimal string, using digits +.QW 0123456789abcdef +for \fBx\fR and +.QW 0123456789ABCDEF +for \fBX\fR). +.TP 10 +\fBb\fR +Convert integer to binary string, using digits 0 and 1. +.TP 10 +\fBc\fR +Convert integer to the Unicode character it represents. +.TP 10 +\fBs\fR +No conversion; just insert string. +.TP 10 +\fBf\fR +Convert number to signed decimal string of +the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by +the precision (default: 6). +If the precision is 0 then no decimal point is output. +.TP 10 +\fBe\fR or \fBE\fR +Convert number to scientific notation in the +form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined +by the precision (default: 6). +If the precision is 0 then no decimal point is output. +If the \fBE\fR form is used then \fBE\fR is +printed instead of \fBe\fR. +.TP 10 +\fBg\fR or \fBG\fR +If the exponent is less than \-4 or greater than or equal to the +precision, then convert number as for \fB%e\fR or +\fB%E\fR. +Otherwise convert as for \fB%f\fR. +Trailing zeroes and a trailing decimal point are omitted. +.TP 10 +\fB%\fR +No conversion: just insert \fB%\fR. +.SH "DIFFERENCES FROM ANSI SPRINTF" +.PP +The behavior of the format command is the same as the +ANSI C \fBsprintf\fR procedure except for the following +differences: +.IP [1] +Tcl guarantees that it will be working with UNICODE characters. +.IP [2] +\fB%p\fR and \fB%n\fR specifiers are not supported. +.IP [3] +For \fB%c\fR conversions the argument must be an integer value, +which will then be converted to the corresponding character value. +.IP [4] +The size modifiers are ignored when formatting floating-point values. +The \fBll\fR modifier has no \fBsprintf\fR counterpart. +The \fBb\fR specifier has no \fBsprintf\fR counterpart. +.SH EXAMPLES +.PP +Convert the numeric value of a UNICODE character to the character +itself: +.PP +.CS +set value 120 +set char [\fBformat\fR %c $value] +.CE +.PP +Convert the output of \fBtime\fR into seconds to an accuracy of +hundredths of a second: +.PP +.CS +set us [lindex [time $someTclCode] 0] +puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]] +.CE +.PP +Create a packed X11 literal color specification: +.PP +.CS +# Each color-component should be in range (0..255) +set color [\fBformat\fR "#%02x%02x%02x" $r $g $b] +.CE +.PP +Use XPG3 format codes to allow reordering of fields (a technique that +is often used in localized message catalogs; see \fBmsgcat\fR) without +reordering the data values passed to \fBformat\fR: +.PP +.CS +set fmt1 "Today, %d shares in %s were bought at $%.2f each" +puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37] + +set fmt2 "Bought %2\e$s equity ($%3$.2f x %1\e$d) today" +puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37] +.CE +.PP +Print a small table of powers of three: +.PP +.CS +# Set up the column widths +set w1 5 +set w2 10 + +# Make a nice header (with separator) for the table first +set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+ +puts $sep +puts [\fBformat\fR "| %-*s | %-*s |" $w1 "Index" $w2 "Power"] +puts $sep + +# Print the contents of the table +set p 1 +for {set i 0} {$i<=20} {incr i} { + puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p] + set p [expr {wide($p) * 3}] +} + +# Finish off by printing the separator again +puts $sep +.CE +.SH "SEE ALSO" +scan(n), sprintf(3), string(n) +.SH KEYWORDS +conversion specifier, format, sprintf, string, substitution +'\" Local Variables: +'\" mode: nroff +'\" End: |