'\" '\" 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. '\" '\" RCS: @(#) $Id: format.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $ '\" '\" The definitions below are for supplemental macros used in Tcl/Tk '\" manual entries. '\" '\" .AP type name in/out ?indent? '\" Start paragraph describing an argument to a library procedure. '\" type is type of argument (int, etc.), in/out is either "in", "out", '\" or "in/out" to describe whether procedure reads or modifies arg, '\" and indent is equivalent to second arg of .IP (shouldn't ever be '\" needed; use .AS below instead) '\" '\" .AS ?type? ?name? '\" Give maximum sizes of arguments for setting tab stops. Type and '\" name are examples of largest possible arguments that will be passed '\" to .AP later. If args are omitted, default tab stops are used. '\" '\" .BS '\" Start box enclosure. From here until next .BE, everything will be '\" enclosed in one large box. '\" '\" .BE '\" End of box enclosure. '\" '\" .CS '\" Begin code excerpt. '\" '\" .CE '\" End code excerpt. '\" '\" .VS ?version? ?br? '\" Begin vertical sidebar, for use in marking newly-changed parts '\" of man pages. The first argument is ignored and used for recording '\" the version when the .VS was added, so that the sidebars can be '\" found and removed when they reach a certain age. If another argument '\" is present, then a line break is forced before starting the sidebar. '\" '\" .VE '\" End of vertical sidebar. '\" '\" .DS '\" Begin an indented unfilled display. '\" '\" .DE '\" End of indented unfilled display. '\" '\" .SO '\" Start of list of standard options for a Tk widget. The '\" options follow on successive lines, in four columns separated '\" by tabs. '\" '\" .SE '\" End of list of standard options for a Tk widget. '\" '\" .OP cmdName dbName dbClass '\" Start of description of a specific option. cmdName gives the '\" option's name as specified in the class command, dbName gives '\" the option's name in the option database, and dbClass gives '\" the option's class in the option database. '\" '\" .UL arg1 arg2 '\" Print arg1 underlined, then print arg2 normally. '\" '\" RCS: @(#) $Id: format.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $ '\" '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b '\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. '\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out '\" # BS - start boxed text '\" # ^y = starting y location '\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. '\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. '\" # VS - start vertical sidebar '\" # ^Y = starting y location '\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. '\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. '\" # Special macro to handle page bottom: finish off current '\" # box/sidebar if in box/sidebar mode, then invoked standard '\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. '\" # DS - begin display .de DS .RS .nf .sp .. '\" # DE - end display .de DE .fi .RE .sp .. '\" # SO - start of list of standard options .de SO .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. '\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\fBoptions\\fR manual entry for details on the standard options. .. '\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. '\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. '\" # CE - end code excerpt .de CE .fi .RE .. .de UL \\$1\l'|0\(ul'\\$2 .. .TH format 3tcl 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME format \- 按 sprintf 的式樣格式化一個字符串 .SH "總覽 SYNOPSIS" \fBformat \fIformatString \fR?\fIarg arg ...\fR? .BE .SH INTRODUCTION .PP 這個命令按與ANSI C \fBsprintf \fR過程相同的方式生成一個格式化了的字符串(在它的實現中使用了 \fBsprintf\fR)。\fIFormatString\fR 指示如何格式化結果，與 \fBsprintf \fR一樣使用 \fB%\fR 轉換指定符(specifier)，如果有增添的參數，則它們提供要被替換到結果中的值。\fBformat\fR 的返回值是格式化了的字符串。 .SH "格式化細節 DETAILS ON FORMATTING" .PP 命令按從左到右的檢索(scan) \fIformatString\fR 的方式操作。除了百分號之外的在格式字符串中的每個字符都要添加到結果字符串上。如果字符是一個 \fB%\fR則它不被複制到結果字符串中。轉而，在 \fB%\fR 後面的字符被作爲一個轉換指定符對待。轉換指定符控制把下一個連續的(successive) \fIarg\fR 轉換成一個特定的格式，並把結果添加到結果字符串中轉換指定符的位置上。如果在格式字符串中有多個轉換指定符，則每一個控制一個增添的參數 \fIarg\fR。\fBformat\fR 命令必須給出足夠的 \fIarg\fRs 來滿足在 \fIformatString \fR中的所有轉換指定符的需要。 .PP 每個轉換指定符可以由六部分組成: 一個 XPG3 位置指定符，一系列標誌(flag)，一個最小字段寬度，一個精度，一個長度修飾符(modifier)，和一個轉換字符。除了轉換字符之外可以省略這些字段中的任何一個。存在的字段必須按上面給出的次序出現。下面的段落依次討論所有這些字段。 .PP 如果 \fB%\fR 跟隨着一個十進制數值和一個 \fB$\fR, 比如“\fB%2$d\fR”，則要轉換的值不接受下一個順序的參數。轉而，它接受由這個數字指示的參數，這裏 1 對應於第一個 \fIarg\fR。如果因爲在指定符中有 \fB*\fR 字符而轉換指定符要求多個參數，則使用連續的參數，開始的參數由這個數值給出。這依從 XPG3 定位指定符約定。如果在 \fIformatString\fR 中有任何定位的指定符則所有指定符必須定位。 .PP 一個轉換指定符的第二部分可以按任意次序包含任何下列的標誌字符: .TP 10 \fB\-\fR 指定被轉換的參數在它的字段中左對齊(數值一般右對齊，如果需要的話，有前導的空格)。 .TP 10 \fB+\fR 指定輸出的數值必須有符號，即使是正數。 .TP 10 \fIspace\fR 指定如果數值的第一個字符不是一個符號則向數值的開始處添加空格。 .TP 10 \fB0\fR 指定應當在數值的左側填充零而不是空格。 .TP 10 \fB#\fR 要求一中替代的輸出形式。對於 \fBo\fR 和 \fBO\fR 轉換它保證第一個數字總是 \fB0\fR。對於 \fBx\fR 或 \fBX\fR 轉換，除了零之外，在結果的開始處(分別)添加 \fB0x\fR 或 \fB0X\fR。對於所有浮點數轉換(\fBe\fR、\fBE\fR、\fBf\fR、\fBg\fR、和 \fBG\fR) 它保證結果總是一個小數點。對於 \fBg\fR 和 \fBG\fR 轉換它指定刪除尾部的零。 .PP 一個轉換指定符的第三部分是給出這個轉換的最小字段寬度的一個數字。它典型的被用來按列表的(tabular)輸出形式排列(line up)各列(column)。如果被轉換的參數包含的字符比這個最小字段寬度少，則填充它來達到這個最小的字段寬度。填充通常是在被轉換的參數的左側添加額外的空格，但是可以使用 \fB0\fR和 \fB-\fR 標誌來分別指定在左側填充零或在右側填充空格。如果指定最小字段寬度爲 \fB*\fR 而不是一個數值，則用給 \fBformat\fR 命令的下一個參數確定最小字段寬度；它必須是一個數值字符串。 .PP 一個轉換指定符的第四部分是一個精度，它由一個點號和隨後的一個數值組成。在不同的轉換中按不同的方式使用這個數值。對於 \fBe\fR、\fBE\fR、和 \fBf\fR 轉換它指定出現在小數點右側的數字的位數。對於 \fBg\fR 和 \fBG\fR 轉換它指定出現的數字的總數，包括在小數點兩側的數字(但是，除非指定了 \fB#\fR 標誌，省略在小數點後面的尾部的零)。對於正數轉換，它指定輸出的最小的數字位數(如果需要的話添加前導的零)。對於 \fBs\fR 轉換它指定輸出的最大的字符數；如果字符串比它長則刪除尾部的字符。如果用 \fB*\fR 而不是一個數值來指定精度，則用給 \fBformat\fR 命令的下一個參數來確定精度；它必須是一個數值字符串。 .PP 一個轉換指定符的第五部分是一個長度修飾符，它必須是 \fBh\fR 或 \fBl\fR。如果它是 \fBh\fR 則指定數值值在轉換之前必須被截斷(truncate)成16位值。這個選項很少有用。忽略 \fBl\fR 修飾符。 .PP 一個轉換指定符的最後一部分是確定進行那種轉換的一個字母字符。當前支持下列轉換字符: .TP 10 \fBd\fR 把整數轉換成有符號的十進制字符串。 .TP 10 \fBu\fR 把整數轉換成無符號的十進制字符串。 .TP 10 \fBi\fR 把整數轉換成有符號的十進制字符串；整數可以是十進制的，八進制的(有一個前導的 \fB0\fR) 或十六進制的(有一個前導的 \fB0x\fR)。 .TP 10 \fBo\fR 把整數轉換成無符號八進制字符串。 .TP 10 \fBx\fR or \fBX\fR 把整數轉換成無符號十六進制字符串，對 \fBx\fR 使用數字“0123456789abcdef”而對 \fBX\fR 使用數字 “0123456789ABCDEF”。 .VS .TP 10 \fBc\fR 把整數轉換成它代表的 Unicode 字符。 .VE .TP 10 \fBs\fR 不轉換，只是插入字符。 .TP 10 \fBf\fR 浮點數轉換成有符號的 \fIxx.yyy \fR形式的十進制字符串，這裏的 \fIy \fR的位數由精度確定(缺省: 6)。如果精度是 0 則不輸出小數點。 .TP 10 \fBe\fR or \fBe\fR 把浮點數轉換成 \fIx.yyy\fR\fBe±\fR\fIzz \fR形式的科學記數法，這裏的 \fIy \fR的位數由精度確定(缺省: 6)。如果精度是 0 則不輸出小數點。如果使用 \fBE\fR 式樣則輸出 \fBE\fR 而不是 \fBe\fR。 .TP 10 \fBg\fR or \fBG\fR 如果指數小於 -4 或大於等於精度，則把富點數按 \fB%e\fR 或 \fB%E\fR 來轉換。否則按 \fB%f\fR 轉換。省略尾部的零和尾部的小數點。 .TP 10 \fB%\fR 不轉換: 只是插入 \fB%\fR。 .LP 數值轉換，被轉換的參數必須是一個正數或浮點數字符串；format 把參數轉換成二進制接着依照轉換指定符把它再轉換成一個字符串。 .SH "與 ANSI SPRINTF 的區別 DIFFERENCES FROM ANSI SPRINTF" .PP 除了下列區別之外，format 命令的行爲與 ANSI C \fBsprintf\fR 過程相同: .IP [1] 當前不支持 \fB%p\fR 和 \fB%n\fR 指定符。 .IP [2] 對於 \fB%c\fR 轉換，參數必須是一個十進制字符串，它將被轉換成相應的字符值。 .IP [3] 忽略 \fBl\fR 修飾符；轉換整數值總是有如沒有修飾符存在，而轉換實數值總是有如存在 \fBl\fR 修飾符(例如， 使用類型 \fBdouble\fR 作爲內部表示)。如果指定了 \fBh\fR 修飾符則在轉換前截斷整數值。 .SH "參見 SEE ALSO" sprintf(3), string(n) .SH "關鍵字 KEYWORDS" conversion specifier, format, sprintf, string, substitution .SH "[中文版維護人]" .B 寒蟬退士 .SH "[中文版最新更新]" .B 2001/08/29 .SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:" .BI http://cmpp.linuxforum.net .SH "跋" .br 本頁面中文版由中文 man 手冊頁計劃提供。 .br 中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR