+++ /dev/null
-'\"
-'\" 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:
OSDN Git Service
