diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2016-12-21 22:47:21 (GMT) |
commit | 5514e37335c012cc70f5b9aee3cedfe3d57f583f (patch) | |
tree | 4ba7d8aad13735e52f59bdce7ca5ba3151ebd7e3 /tcl8.6/doc/format.n | |
parent | 768f87f613cc9789fcf8073018fa02178c8c91df (diff) | |
download | blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.zip blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.gz blt-5514e37335c012cc70f5b9aee3cedfe3d57f583f.tar.bz2 |
undo subtree
Diffstat (limited to 'tcl8.6/doc/format.n')
-rw-r--r-- | tcl8.6/doc/format.n | 285 |
1 files changed, 0 insertions, 285 deletions
diff --git a/tcl8.6/doc/format.n b/tcl8.6/doc/format.n deleted file mode 100644 index ba044f2..0000000 --- a/tcl8.6/doc/format.n +++ /dev/null @@ -1,285 +0,0 @@ -'\" -'\" 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: |