## Tcl9.0.3/Tk9.0.3 Documentation > Tcl Commands > format

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    format — 文字列をＣ言語のsprintf 様式で書式化する Format a string in the style of sprintf
  構文 SYNOPSIS
  緒論 INTRODUCTION
  書式化の詳細 DETAILS ON FORMATTING
  位置指定子 OPTIONAL POSITIONAL SPECIFIER
  旗標 OPTIONAL FLAGS
    -
    +
    space
    0
    #
  欄幅 OPTIONAL FIELD WIDTH
  制度/束縛 OPTIONAL PRECISION/BOUND
  寸法修飾子 OPTIONAL SIZE MODIFIER
  必須の変換型 MANDATORY CONVERSION TYPE
    d
    u
    i
    o
    x or X
    b
    c
    s
    f
    e or E
    g or G
    a or A
    %
    p
  DIFFERENCES FROM ANSI SPRINTF
  用例 EXAMPLES
  SEE ALSO
  KEYWORDS

### NAME

format — 文字列をＣ言語のsprintf 様式で書式化する Format a string in the style of sprintf

### 構文 SYNOPSIS

format formatString ?arg arg ...?

### 緒論 INTRODUCTION

この命令はANSI C の sprintf 函数と似た方式で書式化された文字列を生成する｡ formatString は､sprintf と同じ % 変換規定子を使って､如何に結果に書式化するかを指し示し､更に､追加的な引数があれば､結果として置換えられる値を提供する｡ format の返り値は､書式化された文字列である｡ 　　 This command generates a formatted string in a fashion similar to the ANSI C sprintf procedure. FormatString indicates how to format the result, using % conversion specifiers as in sprintf, and the additional arguments, if any, provide values to be substituted into the result. The return value from format is the formatted string.

### 書式化の詳細 DETAILS ON FORMATTING

この命令は､ formatString を左から右に走査することによって動作する｡書式文字列の夫々の文字は､百分率記号でない限り､生成文字列に追記される｡文字が % であれば､生成文字列には複写されない｡代りに､% 文字に続く文字列が変換規定子として取扱かわれる｡その変換規定子は､後ろに引続く arg から特定の書式への変換を制御し､その結果が､生成文字列の､変換規定子が指定する位置に追記される｡書式文字列の中に複数の変換規定子があると､それぞれ1つが､引続いている arg １つづつの変換を制御する｡この format 命令は､ formatString 中の全ての変換規定子に組合せられるに足るだけの arg を与える必要がある｡ 　　　 The command operates by scanning formatString 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 % then it is not copied to the result string. Instead, the characters following the % character are treated as a conversion specifier. The conversion specifier controls the conversion of the next successive arg 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 arg. The format command must be given enough args to meet the needs of all of the conversion specifiers in formatString.

各､変換規定子は､最大６つの異なる部分を含む: XPG3 方式の位置指定子､旗標群､欄の最小幅､精度､長さ修飾子､変換文字､である｡変換文字以外はどれも省略可能であるが､現れる場合は､上にあげた順番通りでなくてはならない｡次の節で､それぞれの部品を順番に説明する｡　　　 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.

#### 位置指定子 OPTIONAL POSITIONAL SPECIFIER

もし､ “%2$d” の様に､% の後ろに十進数と $ が着いていると､変換すべき値は､その隣に並んでいる引数ではない｡代りに､% の後ろの数が指している位置の引数が使われる､ここで､1が第一引数に相当する｡規定子に * 記号がある故に､変換規定子が複数の引数を要求する場合､与えられた番号の引数から始まる連続した引数が使われる｡これは､位置の指定として､ XPG3 変換に続いている｡もし､ formatString に何か位置指定子があるときは､全ての規定子は位置を定めなくてはならない｡ 　　　 If the % is followed by a decimal number and a $, as in “%2$d”, 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 arg. If the conversion specifier requires multiple arguments because of * 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 formatString then all of the specifiers must be positional.

#### 旗標 OPTIONAL FLAGS

変換規定子の第２の部分には､以下のどれかの旗標が､任意の順で､含まれることがある: 　　　　 The second portion of a conversion specifier may contain any of the following flag characters, in any order:

-
  変換された引数が､その欄に左詰めにされることを指定する(通常､数は適宜空白を先行させた後に右詰めにされる)｡ 　 Specifies that the converted argument should be left-justified in its field (numbers are normally right-justified with leading spaces if needed).

+
  縦え正値でも､数は､常に､符号を付けて印刷されることを指定する｡ 　　　 Specifies that a number should always be printed with a sign, even if positive.

space
  第１文字が符号でなければ､数の先頭に空白が追加されることを指定する｡ 　　　 Specifies that a space should be added to the beginning of the number if the first character is not a sign.

0
  数の左に空白でなく､0 が詰められることを指定する｡ 　　 Specifies that the number should be padded on the left with zeroes instead of spaces.

#
  別の出力形式を要求している｡o 変換では､結果が 0 でない限り､先頭に 0o が附加されることになる｡x と X 変換では､結果が零でない限り､0x が先頭に附加される｡ b 変換では､零でない限り､結果の先頭に 0b が附加される｡d 変換では､零でない限り､結果の先頭に 0d が附加される｡ 全ての浮動小数変換(e と, E と, f と, g と､ G)では､結果に常に小数点があることを保障する｡ g と G 変換では､末尾の零が削除されないことを指定する｡ 　　　 Requests an alternate output form. For o conversions, 0o will be added to the beginning of the result unless it is zero. For x or X conversions, 0x will be added to the beginning of the result unless it is zero. For b conversions, 0b will be added to the beginning of the result unless it is zero. For d conversions, 0d will be added to the beginning of the result unless it is zero. For all floating-point conversions (e, E, f, g, and G) it guarantees that the result always has a decimal point. For g and G conversions it specifies that trailing zeroes should not be removed.

#### 欄幅 OPTIONAL FIELD WIDTH

変換規定子の３番目の部分は､変換用の枠欄の最小長さを指定する十進数である｡典型的には､表の印刷で､縦に整列させる為に使われる｡もし､引数を変換した文字数が枠欄の最小長さより短いと､枠欄の最小長さになるよう､文字詰めされる｡文字詰めは通常は､変換された引数の左側に余分の空白文字が追加されるが､0 と - の旗標が使われてもよく､それぞれ､左側に零､或は､右か側に空白の文字詰めを指定する｡最小枠欄長さが数字ではなく * で指定されていると､format 命令の次の引数が､最小枠欄長さを定める; それは整数値でなければならない｡ 　　　　 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 0 and - 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 * rather than a number, then the next argument to the format command determines the minimum field width; it must be an integer value.

#### 制度/束縛 OPTIONAL PRECISION/BOUND

変換規定子の４番目の部分は､精度で､小数点に数字を続けて構成する｡その数字は､変換毎に違う方法で使われる｡e, E, f 変換では､小数点の右に並ぶ数字の長さを指定する｡g と G 変換では､小数点の両側を併せた数字の総個数が指定される(しかし､あの # 旗標を指定しない限り､小数点より後ろの末尾の零が省略される)｡整数変換では印刷する数字の最小の長さ指定する(必要に応じて､先頭に0が追加される)｡s 変換では､印刷される最大の文字数を指定する; 文字列がこれより長いと末尾の文字が欠落することになる｡もし精度が数字でなく * で指定されていると､format 命令の次の引数が､最小枠欄長さを定める; それは数の文字列でなければならない｡ 　　 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 e, E, and f conversions it specifies the number of digits to appear to the right of the decimal point. For g and G 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 # flag has been specified). For integer conversions, it specifies a minimum number of digits to print (leading zeroes will be added if necessary). For s 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 * rather than a number then the next argument to the format command determines the precision; it must be a numeric string.

#### 寸法修飾子 OPTIONAL SIZE MODIFIER

変換規定子の５番目の部分は､長さの修飾子で､ ll か h か l か zか tか L でなければならない｡ もし､ ll であると､整数値は切詰めなしに､書式化された部分文字列への変換に扱われることを規定する｡ もし､ h であると､変換の前に､整数は１６ビット幅に切詰められることを指定する｡この指示は､稀に有用である｡ もし､ l (又はjかq)であると､ expr 命令の wide() 函数が生成するのと同じ範囲に整数値が切詰められる(少なくとも６４ビット範囲)事を指定する｡ もし､ z か t であると､整数値はtcl_platform配列のpointerSize要素の値によって定められる範囲に切詰められることを規定する｡ もし L であると､書式化された部分文字列への変換に関して切り詰めなしに､整数か倍数がとられることを指定する｡ これらのどれも指定されないと､整数値は32ビット巾に切詰められる｡ The fifth part of a conversion specifier is a size modifier, which must be ll, h, l, z, t, or L. If it is ll it specifies that an integer value is taken without truncation for conversion to a formatted substring. If it is h it specifies that an integer value is truncated to a 16-bit range before converting. This option is rarely useful. If it is l (or j or q) it specifies that the integer value is truncated to the same range as that produced by the wide() function of the expr command (at least a 64-bit range). If it is z or t it specifies that the integer value is truncated to the range determined by the value of the pointerSize element of the tcl_platform array. If it is L it specifies that an integer or double value is taken without truncation for conversion to a formatted substring. If neither of those are present, the integer value is truncated to a 32-bit range.

#### 必須の変換型 MANDATORY CONVERSION TYPE

変換規定子の最後の部分は､ローマ字文字であって､どの様な種類の変換が行われるかを定める｡現在､以下の変換が運用されている: 　　 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:

d
  整数を符号付き十進文字列に変換する｡ 　 Convert integer to signed decimal string.

u
  整数を符号なし十進文字列に変換する｡ 　　 Convert integer to unsigned decimal string.

i
  整数を符号付き十進文字列に変換する(d と等価)｡ 　　　 Convert integer to signed decimal string (equivalent to d).

o
  整数を符号なし八進文字列に変換する｡ 　　　 Convert integer to unsigned octal string.

x or X
  x では､数字 “0123456789abcdef” を使って､X では､数字 “0123456789ABCDEF” を使って､整数を符号なし十六進文字列に変換する｡ 　　　 Convert integer to unsigned hexadecimal string, using digits “0123456789abcdef” for x and “0123456789ABCDEF” for X).

b
  数字の 0 と 1 を使って､整数を符号なし２進数文字列に変換する｡ 　　 Convert integer to unsigned binary string, using digits 0 and 1.

c
  整数を､それが表現するユニコード文字に変換する｡　　 Convert integer to the Unicode character it represents.

s
  無変換;そのまま文字列に挿入｡ 　　　 No conversion; just insert string.

f
  数を xx.yyy の形式の符号付十進文字列に変換する､ここで､y の個数は精度によって定められる(無為設定: 6)｡もし､精度が0であれば､小数点は出力されない｡ 　　 Convert number to signed decimal string of the form xx.yyy, where the number of y's is determined by the precision (default: 6). If the precision is 0 then no decimal point is output.

e or E
  数を､x.yyye±zz の指数表記形式に変換する､ここで､y の個数は精度によって定められる(無為設定: 6)｡もし､精度が0であれば､小数点は出力されない｡もし､ E の形式が指定されると､ e の代りに E が印刷される｡ 　　　 Convert number to scientific notation in the form x.yyy e±zz, where the number of y's is determined by the precision (default: 6). If the precision is 0 then no decimal point is output. If the E form is used then E is printed instead of e.

g or G
  もし､冪数が-4より小さいか､精度と同じか､より大きいと､数を %e か %E の様に変換する｡それ以外では %f の様に変換する｡末尾の零と小数点は省略される｡ If the exponent is less than -4 or greater than or equal to the precision, then convert number as for %e or %E. Otherwise convert as for %f. Trailing zeroes and a trailing decimal point are omitted.

a or A
  倍精度から 0x1.yyyp±zz の書式の十六進数に変換する､ここで､y の数は精度によって決められる(無為設定は： 13)｡もし､A 書式が使用されると十六進数は大文字で印刷される｡ Convert double to hexadecimal notation in the form 0x1.yyy p±zz, where the number of y's is determined by the precision (default: 13). If the A form is used then the hex characters are printed in uppercase.

%
  無変換: % を挿入するのみ｡ No conversion: just insert %.

p
  0x%zx の簡略形式､従って整数を前置辞 0x を附した十六進書式を出力する｡ Shorthand form for 0x%zx, so it outputs the integer in hexadecimal form with 0x prefix.

### DIFFERENCES FROM ANSI SPRINTF

書式変換の振舞いは､以下の違いを除いて､ ANSI C sprintf 函数と同じである｡ 　　 The behavior of the format command is the same as the ANSI C sprintf procedure except for the following differences:

1. Tcl はユニコード文字によって動作することが保障される｡ Tcl guarantees that it will be working with UNICODE characters.

2. %n 規定子は運用していない｡ %n specifier is not supported.

3. %c 変換では､引数は整数でなければならない｡それが､相当する文字値に変換される｡ 　　 For %c conversions the argument must be an integer value, which will then be converted to the corresponding character value.

4. 浮動小数値の書式化では寸法修飾子は無視される｡ b 指定子は sprintf に対応するものがない｡　　　 The size modifiers are ignored when formatting floating-point values. The b specifier has no sprintf counterpart.

### 用例 EXAMPLES

ユニコード文字の数値を文字そのものに変換する: 　　　 Convert the numeric value of a UNICODE character to the character itself:

    set value 120
    set char [format %c $value]

time の出力を秒から百分の一秒の精度に変換する: 　　 Convert the output of time into seconds to an accuracy of hundredths of a second:

    set us [lindex [time $someTclCode] 0]
    puts [format "%.2f seconds to execute" [expr {$us / 1e6}]]

短縮X11用色彩記号規定子の作成: 　　 Create a packed X11 literal color specification:

    # 各色要素は0～255の範囲の筈　# Each color-component should be in range (0..255)
    set color [format "#%02x%02x%02x" $r $g $b]

format に渡したデータの値の再整列なしに欄枠の再整列を許容する為にXPG3 書式番号(しばしば方言化された伝言文に使われる技術; msgcat 参照)を使う: 　　　 Use XPG3 format codes to allow reordering of fields (a technique that is often used in localized message catalogs; see msgcat) without reordering the data values passed to format:

    set fmt1 "Today, %d shares in %s were bought at $%.2f each"
    puts [format $fmt1 123 "Global BigCorp" 19.37]

    set fmt2 "Bought %2\$s equity ($%3$.2f x %1\$d) today"
    puts [format $fmt2 123 "Global BigCorp" 19.37]

３の冪乗の小さな表を印刷する: 　　 Print a small table of powers of three:

    # 欄の幅を準備する	# 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 [format "| %-*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 [format "| %*d | %*ld |" $w1 $i $w2 $p]
        set p [expr {wide($p) * 3}]
    }

    # 再度区切り記号を印刷して仕上げる
    # Finish off by printing the separator again
    puts $sep

### SEE ALSO

scan, sprintf, string

### KEYWORDS

conversion specifier, format, sprintf, string, substitution
Copyright © 1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.