java.util.Formatter (摘自sun主頁)
printf 風格的格式字符串的解釋程序。此類提供了對布局對齊和排列的支持，以及對數值、字符串和日期/時間數據的常規格式和特定於語言環境的輸出的支持。支持諸如 byte、BigDecimal 和 Calendar 等常見 Java 類型。任意用戶類型的受限格式化定制都是通過 Formattable接口提供的。
Formatter 對於多線程訪問而言沒必要是安全的。線程安全是可選的，它對此類中的方法用戶負責。
Java 語言的格式化輸出在很大程度上受到 C 語言 printf的啟發。雖然一些格式字符串與 C 類似，但已進行了某些定制，以適應 Java 語言，並且利用了其中一些特性。此外，Java 的格式比 C 的格式更嚴格；例如，如果轉換與標志不兼容，則會拋出異常。在 C 中，不適用的標志會被忽略。這樣，便於 C 程序員識別這些格式字符串，而又不必與 C 中的那些標志完全兼容。
所期望用法的示例：
StringBuilder sb = new StringBuilder();
// Send all output to the Appendable object sb
Formatter formatter = new Formatter(sb, Locale.US);
// Explicit argument indices may be used to re-order output.
formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
// -> " d c b a"
// Optional locale as the first argument can be used to get
// locale-specific formatting of numbers. The precision and width can be
// given to round and align the value.
formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
// -> "e = +2,7183"
// The '(' numeric flag may be used to format negative numbers with
// parentheses rather than a minus sign. Group separators are
// automatically inserted.
formatter.format("Amount gained or lost since last statement: $ %(,.2f",
balanceDelta);
// -> "Amount gained or lost since last statement: $ (6,217.58)"
常見格式化請求的便捷方法是按照如下調用格式來闡明的：
// Writes a formatted string to System.out.
System.out.format("Local time: %tT", Calendar.getInstance());
// -> "Local time: 13:34:18"
// Writes formatted output to System.err.
System.err.printf("Unable to open file '%1$s': %2$s",
fileName, exception.getMessage());
// -> "Unable to open file 'food': No such file or directory"
與 C 語言的 sprintf(3) 類似，可以使用靜態方法 String#format(String,Object...)String.format來格式化 Strings：
// Format a string containing a date.
import java.util.Calendar;
import java.util.GregorianCalendar;
import static java.util.Calendar.*;
Calendar c = new GregorianCalendar(1995, MAY, 23);
String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
// -> s == "Duke's Birthday: May 23, 1995"
結構
此規范分為兩部分。第一部分是摘要，包括基本的格式概念。這一部分是為那些想要快速入門並熟悉其他編程語言的格式化輸出的用戶准備的。第二部分是詳細信息，包括具體的實現細節。它是為那些需要更精確格式化行為規范的用戶准備的。
摘要
這一部分將提供對格式概念的簡單概述。有關精確的行為細節，請參閱詳細信息部分。
格式字符串語法
產生格式化輸出的每個方法都需要格式字符串 和參數列表。格式字符串是一個 String，它可以包含固定文本以及一個或多個嵌入的格式說明符。請考慮以下示例：
Calendar c = ...;
String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
此格式字符串是 format 方法的第一個參數。它包含三個格式說明符 "%1$tm"、"%1$te" 和 "%1$tY"，它們指出應該如何處理參數以及在文本的什么地方插入它們。格式字符串的其余部分是包括 "Dukes Birthday: " 和其他任何空格或標點符號的固定文本。 參數列表由傳遞給位於格式字符串之后的方法的所有參數組成。在上述示例中，參數列表的大小為 1，由對象 Calendar c組成。
- 常規類型、字符類型和數值類型的格式說明符的語法如下：
%[argument_index$][flags][width][.precision]conversion
可選的 argument_index 是一個十進制整數，用於表明參數在參數列表中的位置。第一個參數由 "1$" 引用，第二個參數由 "2$" 引用，依此類推。
可選 flags是修改輸出格式的字符集。有效標志集取決於轉換類型。
可選 width是一個非負十進制整數，表明要向輸出中寫入的最少字符數。
可選 precision是一個非負十進制整數，通常用來限制字符數。特定行為取決於轉換類型。
所需 conversion是一個表明應該如何格式化參數的字符。給定參數的有效轉換集取決於參數的數據類型。
- 用來表示日期和時間類型的格式說明符的語法如下：
%[argument_index$][flags][width]conversion
可選的 argument_index、flags 和 width的定義同上。
所需的 conversion 是一個由兩字符組成的序列。第一個字符是 't' 或 'T'。第二個字符表明所使用的格式。這些字符類似於但不完全等同於那些由 GNU date 和 POSIX strftime(3c)定義的字符。
- 與參數不對應的格式說明符的語法如下：
%[flags][width]conversion
可選 flags 和 width的定義同上。
所需的 conversion 是一個表明要在輸出中所插內容的字符。
轉換
轉換可分為以下幾類：
- 常規- 可應用於任何參數類型
- 字符 - 可應用於表示 Unicode 字符的基本類型：char、
Character、byte、Byte、short 和Short。當Character#isValidCodePoint返回 true 時，可將此轉換應用於 int 和Integer類型 - 數值
- 整數 - 可應用於 Java 的整數類型：byte、
Byte、short、Short、int、Integer、long、Long和BigInteger - 浮點 - 可用於 Java 的浮點類型：float、
Float、double、Double和BigDecimal
- 整數 - 可應用於 Java 的整數類型：byte、
- 日期/時間 - 可應用於 Java 的、能夠對日期或時間進行編碼的類型：long、
Long、Calendar和Date。 - 百分比 - 產生字面值 '%' ('%')
- 行分隔符 - 產生特定於平台的行分隔符
下表總結了受支持的轉換。由大寫字符（如 'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A' 和 'T'）表示的轉換與由相應的小寫字符的轉換等同，根據流行的 Locale 規則將結果轉換為大寫形式除外。后者等同於 String#toUpperCase()的以下調用
out.toUpperCase()
轉換參數類別說明'b', 'B'常規如果參數 arg 為 null，則結果為 "false"。如果 arg 是一個 boolean 值或 Boolean，則結果為 String.valueOf()返回的字符串。否則結果為 "true"。'h', 'H'常規如果參數 arg 為 null，則結果為 "null"。否則，結果為調用 Integer.toHexString(arg.hashCode())得到的結果。's', 'S'常規如果參數 arg 為 null，則結果為 "null"。如果 arg 實現 Formattable，則調用 arg.formatTo。否則，結果為調用 arg.toString()得到的結果。'c', 'C'字符結果是一個 Unicode 字符'd'整數結果被格式化為十進制整數'o'整數結果被格式化為八進制整數'x', 'X'整數結果被格式化為十六進制整數'e', 'E'浮點結果被格式化為用計算機科學記數法表示的十進制數'f'浮點結果被格式化為十進制數'g', 'G'浮點根據精度和舍入運算后的值，使用計算機科學記數形式或十進制格式對結果進行格式化。'a', 'A'浮點結果被格式化為帶有效位數和指數的十六進制浮點數't', 'T'日期/時間日期和時間轉換字符的前綴。請參閱日期/時間轉換。'%'百分比結果為字面值 '%' ('%')'n'行分隔符結果為特定於平台的行分隔符 |
|---|
任何未明確定義為轉換的字符都是非法字符，並且都被保留，以供將來擴展使用。
日期/時間轉換
以下日期和時間轉換的后綴字符是為 't' 和 'T' 轉換定義的。這些類型相似於但不完全等同於那些由 GNU date 和 POSIX strftime(3c) 定義的類型。提供其他轉換類型是為了訪問特定於 Java 的功能（如將 'L'用作秒中的毫秒）。
以下轉換字符用來格式化時間：
| 'H'24 小時制的小時，被格式化為必要時帶前導零的兩位數，即 00 - 23。'I'12 小時制的小時，被格式化為必要時帶前導零的兩位數，即 01 - 12。'k'24 小時制的小時，即 0 - 23。'l'12 小時制的小時，即 1 - 12。'M'小時中的分鍾，被格式化為必要時帶前導零的兩位數，即 00 - 59。'S'分鍾中的秒，被格式化為必要時帶前導零的兩位數，即 00 - 60 （"60" 是支持閏秒所需的一個特殊值）。'L'秒中的毫秒，被格式化為必要時帶前導零的三位數，即 000 - 999。'N'秒中的毫微秒，被格式化為必要時帶前導零的九位數，即 000000000 - 999999999。'p'特定於語言環境的 上午或下午 標記以小寫形式表示，例如 "am" 或 "pm"。使用轉換前綴 'T'可以強行將此輸出轉換為大寫形式。'z'相對於 GMT 的 RFC 822 格式的數字時區偏移量，例如 -0800。'Z'表示時區縮寫形式的字符串。Formatter 的語言環境將取代參數的語言環境（如果有）。's'自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的秒數，即 Long.MIN_VALUE/1000 與 Long.MAX_VALUE/1000之間的差值。'Q'自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的毫秒數，即 Long.MIN_VALUE 與 Long.MAX_VALUE 之間的差值。 |
以下轉換字符用來格式化日期：
| 'B'特定於語言環境的月份全稱，例如 "January" 和 "February"。'b'特定於語言環境的月份簡稱，例如 "Jan" 和 "Feb"。'h'與 'b'相同。'A'特定於語言環境的星期幾全稱，例如 "Sunday" 和 "Monday"'a'特定於語言環境的星期幾簡稱，例如 "Sun" 和 "Mon"'C'除以 100 的四位數表示的年份，被格式化為必要時帶前導零的兩位數，即 00 - 99'Y'年份，被格式化為必要時帶前導零的四位數（至少），例如，0092 等於格里高利歷的 92CE。'y'年份的最后兩位數，被格式化為必要時帶前導零的兩位數，即 00 - 99。'j'一年中的天數，被格式化為必要時帶前導零的三位數，例如，對於格里高利歷是 001 - 366。'm'月份，被格式化為必要時帶前導零的兩位數，即 01 - 13。'd'一個月中的天數，被格式化為必要時帶前導零兩位數，即 01 - 31'e'一個月中的天數，被格式化為兩位數，即 1 - 31。 |
以下轉換字符用於格式化常見的日期/時間組合。
| 'R'24 小時制的時間，被格式化為 "%tH:%tM"'T'24 小時制的時間，被格式化為 "%tH:%tM:%tS"。'r'12 小時制的時間，被格式化為 "%tI:%tM:%tS %Tp"。上午或下午標記 ('%Tp') 的位置可能與語言環境有關。'D'日期，被格式化為 "%tm/%td/%ty"。'F'ISO 8601 格式的完整日期，被格式化為 "%tY-%tm-%td"。'c'日期和時間，被格式化為 "%ta %tb %td %tT %tZ %tY"，例如 "Sun Jul 20 16:17:00 EDT 1969"。 |
任何未明確定義為轉換的字符都是非法字符，並且都被保留，以供將來擴展使用。
標志
下表總結了受支持的標志。y表示該標志受指示參數類型支持。
| 標志常規字符整數浮點日期/時間說明'-'yyyyy結果將是左對齊的。'#'y1-y3y-結果應該使用依賴於轉換類型的替換形式'+'--y4y-結果總是包括一個符號' '--y4y-對於正值，結果中將包括一個前導空格'0'--yy-結果將用零來填充','--y2y5-結果將包括特定於語言環境的組分隔符'('--y4y5-結果將是用圓括號括起來的負數 |
|---|
1 取決於 Formattable的定義。
2 只適用於 'd'轉換。
3 只適用於 'o'、'x' 和 'X'轉換。
4 對 BigInteger 應用 'd'、'o'、'x' 和 'X' 轉換時，或者對 byte 及 Byte、short 及 Short、int 及 Integer、long 及 Long 分別應用 'd'轉換時適用。
5 只適用於 'e'、'E'、'f'、'g' 和 'G'轉換。
任何未顯式定義為標志的字符都是非法字符，並且都被保留，以供擴展使用。
寬度
寬度是將向輸出中寫入的最少字符數。對於行分隔符轉換，不適用寬度，如果提供寬度，則會拋出異常。
精度
對於常規參數類型，精度是將向輸出中寫入的最多字符數。
對於浮點轉換 'e'、'E' 和 'f'，精度是小數點分隔符后的位數。如果轉換是 'g' 或 'G'，那么精度是舍入計算后所得數值的所有位數。如果轉換是 'a' 或 'A'，則不必指定精度。
對於字符、整數和日期/時間參數類型轉換，以及百分比和行分隔符轉換，精度是不適用的；如果提供精度，則會拋出異常。
參數索引
參數索引是一個十進制整數，用於表明參數在參數列表中的位置。第一個參數由 "1$" 引用，第二個參數由 "2$" 引用，依此類推。
根據位置引用參數的另一種方法是使用 '<' ('<') 標志，這將會重用以前格式說明符的參數。例如，以下兩條語句產生的字符相同：
Calendar c = ...;
String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);
詳細信息
這一部分將提供格式化行為規范方面的細節，其中包括條件和異常、受支持的數據類型、本地化以及標志、轉換和數據類型之間的交互。有關格式化概念的概述，請參閱摘要。
任何未明確定義為轉換、日期/時間轉換前綴或標志的字符都是非法字符，並且這些字符都被保留，以供未來擴展使用。在格式字符串中使用這樣的字符會導致拋出 UnknownFormatConversionException 或 UnknownFormatFlagsException。
如果格式說明符包含帶有無效值或不受支持的其他值的寬度或精度，則將分別拋出 IllegalFormatWidthException 或 IllegalFormatPrecisionException。
如果格式說明符包含不適用於對應參數的轉換字符，則將拋出 IllegalFormatConversionException。
所有指定異常都可能被 Formatter 的任何 format 方法以及任何 format 的便捷方法拋出，比如 String#format(String,Object...)String.format 和 java.io.PrintStream#printf(String,Object...)PrintStream.printf。 String.format} and PrintStream.printf.
由大寫字符（如 'B'、'H'、'S'、'C'、'X'、'E'、'G'、'A' 和 'T'）表示的轉換與那些相應的小寫字符表示的轉換相同，根據流行的 Locale 規則將結果轉換成大寫形式除外。結果等同於 String#toUpperCase()的以下調用
out.toUpperCase()
常規
以下常規轉換可應用於任何參數類型：
'b''b'將生成 "true" 或 "false"，由 Boolean#toString(boolean)返回。 如果參數為 null，則結果為 "false"。如果參數是一個 boolean 值或 如果給出 '#' 標志，則將拋出 如果參數 arg 為 null，則結果為 "null"。否則，結果為調用 Integer.toHexString(arg.hashCode())得到的結果。 如果給出 '#' 標志，則將拋出 如果參數為 null，則結果為 "null"。如果參數實現了 如果給出 '#' 標志，且參數不是 |
'-''-'將輸出左對齊。根據需要在轉換值結尾處添加空格 (' ')，以滿足字段的最小寬度要求。如果沒有提供寬度，則將拋出 MissingFormatWidthException。如果沒有給出此標志，則輸出將是右對齊的。'#''#'要求輸出使用替換形式。此形式的定義通過轉換指定。 |
寬度 是將向輸出中寫入的最少字符數。如果轉換值的長度小於寬度，則用 ' ' (\u0020') 填充輸出，直到字符總數等於寬度為止。默認情況下，是在左邊進行填充。如果給出 '-'標志，則在右邊進行填充。如果沒有指定寬度，則沒有最小寬度。
精度是將向輸出中寫入的最多字符數。精度的應用要先於寬度，因此，即使寬度大於精度，輸出也將被截取為 precision字符。如果沒有指定精度，則對字符數沒有明確限制。
字符
此轉換可應用於 char 和 Character。它還可應用於類型 byte、Byte、short 和 Short、 int 和 Integer。當 Character#isValidCodePoint 返回 true 時，此轉換也可應用於 int 和 Integer。如果返回 false，則將拋出 IllegalFormatCodePointException。
| 'c''c'將參數格式化為 Unicode Character Representation 中描述的 Unicode 字符。在該參數表示增補字符的情況下，它可能是多個 16 位 char。 如果給出 '#' 標志，則將拋出 |
'-' 標志是為應用常規轉換而定義的。如果給出 '#' 標志，則將拋出 FormatFlagsConversionMismatchException。
寬度是為了實現常規轉換而定義的。
精度不適用。如果指定精度，則將拋出 IllegalFormatPrecisionException。
數值
數值轉換分為以下幾類：
將根據以下算法對數值類型進行格式化：
在獲得數字的整數部分、小數部分和指數（適用於數據類型）之后，將應用以下轉換：
- 將字符串中的每個數字字符 d 都替換為特定於語言環境的數字，該數字是相對於當前語言環境的零數字 z 來計算的；即 d - '0' + z。
- 如果存在小數點分隔符，則用特定於語言環境的小數點分隔符替換。
- 如果給出 ',' (',') flag 標志，則插入特定於語言環境的組分隔符，這是通過從最低位到最高位瀏覽字符串的整數部分並不時插入該語言環境組大小定義的分隔符來實現的。
- 如果給出 '0' 標志，則在符號字符（如果有的話）之后、第一個非零數字前插入特定於語言環境的零數字，直到字符串長度等於所要求的字段寬度。
- 如果該值為負，並且給出了 '(' 標志，那么預先考慮 '(' ('(')，並追加一個 ')' (')')。
- 如果該值為負（或者為浮點負零），並且沒有給出 '(' 標志，那么預先考慮 '-' ('-')。
- 如果給出 '+' 標志，並且該值為正或零（或者為浮點正零），那么將預先考慮 '+' ('+')。
如果該值為 NaN 或正無窮大，則分別輸出文本字符串 "NaN" 或 "Infinity"。如果該值為負無窮大，那么輸出將是 "(Infinity)"；否則如果給出 '('標志，那么輸出將是 "-Infinity"。這些值都沒有被本地化。
以下轉換可應用於 byte、Byte、short、Short、int、Integer、long 和 Long。
| 'd''T'將參數格式化為十進制整數。應用本地化算法。 如果給出 '0'標志，並且值為負，則在符號后填充零。 如果給出 '#' 標志，則將拋出 如果 x 為負，那么結果將是通過將 2n 添加到值中產生的一個無符號值，其中 n 是在適當時候由類 Byte、Short、Integer 或 Long 中的靜態 SIZE字段返回的類型中的位數。 如果給出 '#' 標志，則輸出將始終以基數指示符 '0'開始。 如果給出 '0'標志，則使用前導零填充輸出，這些零被填充到以下任意指示符號后面的字段寬度中。 如果給出 '('、'+'、' ' 或 '、' 標志，則將拋出 如果 x 為負，那么結果將為把 2n 添加到值中產生的一個無符號值，其中 n 是在適當時候，由類 Byte、Short、Integer 或 Long 中的靜態 SIZE字段返回的類型中的位數。 如果給出 '#' 標志，則輸出將始終以基數指示符 '0x'開始。 如果給出 '0'標志，則使用前導零填充輸出，這些零被填充到基數指示符或符號（如果存在）后面的字段寬度中。 如果給出 '('、' '、'+' 或 '、' 標志，則將拋出 |
如果該轉換是 'o'、'x' 或 'X' 轉換，並且給出了 '#' 和 '0' 標志，那么結果將包含基數指示符（對於八進制是 '0'，對於十六進制是 '0' 或 "0x"）、一定數量的零（基於寬度）和該值。
如果沒有給出 '-'標志，則在符號前填充空格。
| '+''+'要求所有正數的輸出都包含一個正號。如果沒有給出此標志，則只有負值包含符號。 如果同時給出了 '+' 和 ' ' 標志，則將拋出 如果同時給出了 '+' 和 ' ' 標志，則將拋出 MissingFormatWidthException。 如果同時給出 '-' 和 '0' 標志，則將拋出 |
- width中的輸出是右對齊的
- 負數以 '-' ('-') 開始
- 正數和零不包括符號或額外的前導空格
- 不包括組分隔符
The 寬度 是將向輸出中寫入的最少字符數。這包括所有符號、數字、組分隔符、基數指示符和圓括號。如果轉換值的長度小於寬度，則用空格('\u0020') 填充輸出，直到字符總數等於寬度。默認情況下，在左邊進行填補。如果給出 '-'標志，則在右邊進行填補。如果沒有指定寬度，則沒有最小寬度。
精度不適用。如果指定精度，則將拋出 IllegalFormatPrecisionException。
以下轉換可應用於 java.math.BigInteger。
| 'd''T'要求將輸出格式化為十進制整數。應用本地化算法。 如果給出 '#' 標志，則將拋出 如果 x 為負，那么結果將是以 '-' ('\u002d') 開始的有符號值。允許對這種類型使用有符號輸出，因為它不同於基本類型，在沒有假定顯式數據類型大小的情況下，不可能創建無符號的等效值。 如果 x 為正數或零，且給出了 '+' 標志，那么結果是以 '+' ('+') 開始的。 如果給出 '#' 標志，那么輸出將始終以 '0'前綴開始。 如果給出 '0'標志，那么將使用前導零填充輸出，這些零被填充到指示符后的字段寬度中。 如果給出 ',' 標志，則將拋出 如果 x 為負，那么結果是以 '-' ('_apos;) 開始的有符號值。此類型允許使用有符號輸出，因為與基本類型不同，如果不假定明確的數據類型大小，則不可能創建無符號的等效數。 如果 x 為正數或零，且給出了 '+' 標志，那么結果以 '+' ('+') 開始。 如果給出 '#' 標志，那么輸出將始終以基數指示符 '0x'開始。 如果給出 '0'標志，那么將使用前導零填充輸出，這些零被填充到基數指示符或符號（如果存在）后面的字段寬度中。 如果給出 ',' 標志，則將拋出 |
如果該轉換是 'o'、'x' 或 'X'，並且給出了 '#' 和 '0' 標志，那么結果將包含基數指示符（對於八進制是 '0'，對於十六進制是 '0' 或 "0x"）、一定數量的零（基於寬度）和該值。
如果給出 '0'標志，並且值為負，則在符號后填充零。
如果沒有給出 '-'標志，則在符號前填充空格。
應用為 Byte、Short、Integer 和 Long 定義的所有標志。沒有給出標志時的默認行為與 Byte、Short、Integer 和 Long 的行為相同。
寬度的規范與為 Byte、Short、Integer 和 Long 定義的規范相同。
精度不適用。如果指定精度，則將拋出 IllegalFormatPrecisionException。
以下轉換可應用於 float、Float、double 和 Double。
| 'e''e'要求使用科學記數法來格式化輸出。應用本地化算法。 數值 m的格式取決它的值。 如果 m是 NaN 或無窮大，則分別輸出文本字符串 "NaN" 或 "Infinity"。這些值都沒有被本地化。 如果 m 是正零或負零，則指數將是 "+00"。 否則，結果是表示變量的符號和大小（絕對值）的字符串。符號的格式在本地化算法中已經描述。數值 m的格式取決它的值。 讓 n 成為滿足 10n <= m < 10n+1 的唯一整數；讓 a 成為 m 和 10n 的精確算術商數值，且滿足 1 <= a < 10。然后將該數值解釋為 a 的整數部分，因為是一個小數位數，所以后面跟着小數點分隔符，再后面是表示 a 的小數部分的小數位數，后跟指數符號 'e' ('e')，這之后是指數符號，后跟十進制整數形式表示的 n，它由方法 在結果中，m 或 a 的小數部分的位數等於精度。如果沒有指定精度，則默認值為 6。如果精度小於將出現在分別由 如果給出 ',' 標志，則將拋出 在對精度進行舍入運算后，所得數值 m的格式取決於它的值。 如果 m 大於等於 10-4 但小於 10精度，則以十進制形式表示它。 如果 m 小於 10-4 或者大於等於 10精度，則以計算機科學記數法表示它。 m 中的總有效位數等於其精度。如果沒有指定精度，則其默認值為 6。如果精度為 0，則該值將為 1。 如果給出 '#' 標志，則將拋出 結果是表示參數的符號和大小（絕對值）的字符串。符號的格式在本地化算法中已經描述。數值 m的格式取決它的值。 如果 m是 NaN 或無窮大，則將分別輸出文本字符串 "NaN" 或 "Infinity"。這些值都沒有被本地化。 將數值格式化為 m 的整數部分（不帶前導零），后跟小數點分隔符，再后面是表示 m的小數部分的一個或多個十進制數字。 在結果中，m 或 a 的小數部分的位數等於精度。如果沒有指定精度，則默認值為 6。如果該精度小於將要出現在分別由 結果是表示參數 x的符號和大小（絕對值）的字符串。 如果 x 為負值或負零值，那么結果將以 '-' ('-') 開始。 如果 x 為正值或正零值，且給出了 '+' 標志，那么結果將以 '+' ('+') 開始。 數值 m的格式取決它的值。
如果給出 '(' 或 ',' 標志，則將拋出 |
應用為 Byte、Short、Integer 和 Long 定義的所有標志。
如果給出 '#'標志，則將始終存在小數點分隔符。
- width中的輸出是右對齊的。
- 負數以 '-'開頭
- 正數和正零不包括符號或額外的前導空格
- 不包括組分隔符
- 小數點分隔符只在后面有數字時才出現
The 寬度 是將向輸出中寫入的最少字符數。這包括可應用的所有符號、數字、組分隔符、小數點分隔符、指數符號、基數指示符、圓括號和表示無窮大和 NaN 的字符串。如果轉換值的長度小於寬度，則用空格('\u0020') 填充輸出，直到字符總數等於寬度。默認情況下，在左邊進行填充。如果給出 '-'標志，則在右邊進行填充。如果沒有指定寬度，則沒有最小寬度。
如果 轉換 是 'e'、'E' 或 'f'，則精度是小數點分隔符后的位數。如果沒有指定精度，則假定精度為 6。
如果轉換是 'g' 或 'G' 轉換，那么精度就是舍入運算后所得數值的總有效位數。如果沒有指定精度，則默認值為 6。如果精度為 0，則該值將為 1。
如果轉換是 'a' 或 'A' 轉換，則精度是小數點分隔符后十六進制數字的位數。如果沒有提供精度，則將輸出 Double#toHexString(double)返回的所有數字。
以下轉換可應用於 BigDecimal。
| 'e''e'要求使用計算機科學記數法對輸出進行格式化。應用本地化算法。 數值 m的格式取決於它的值。 如果 m 為正零或負零，則指數將為 "+00"。 否則，結果是表示參數的符號和大小（絕對值）的字符串。符號的格式在本地化算法中已經描述。數值 m的格式取決於它的值。 讓 n 成為滿足 10n <= m < 10n+1 的唯一整數；讓 a 成為 m 和 10n 的精確算術商數值，且滿足 1 <= a < 10。然后將該數值解釋為 a 的整數部分，因為是一個小數位數，所以后面跟着小數點分隔符，再后面是表示 a 的小數部分的小數位數，后跟指數符號 'e' ('e')，這之后是指數符號，后跟十進制整數形式表示的 n，它由方法 在結果中，m 或 a 的小數部分的位數等於精度。如果沒有指定精度，則默認值為 6。如果精度小於將出現在分別由 如果給出 ',' 標志，則將拋出 在對精度進行舍入運算后，所得數值 m的格式取決於它的值。 如果 m 大於等於 10-4 但小於 10精度，則以十進制形式表示它。 如果 m 小於 10-4 或者大於等於 10精度，則以計算機科學記數法表示它。 m 中的總的有效位數等於精度。如果沒有指定精度，則默認值為 6。如果精度為 0，則該值將為 1。 如果給出 '#' 標志，則將拋出 結果是表示參數的符號和大小（絕對值）的字符串。符號的格式在本地化算法中已經描述。數值 m的格式取決於它的值。 將該數值格式化為 m 的整數部分（不帶前導零），后跟小數點分隔符，再后面是表示 m的小數部分的一個或多個十進制數字。 在結果中，m 或 a 的小數部分的位數等於精度。如果沒有指定精度，則默認值為 6。如果精度小於將出現在分別由 |
應用為 Byte、Short、Integer 和 Long 定義的所有標志。
如果給出 '#'標志，則將始終存在小數點分隔符。
沒有給出標志時的默認行為與 Float 和 Double 的行為相同。
寬度和精度的規范與為 Float 和 Double 定義的規范相同。
日期/時間
此轉換可應用於 long、Long、Calendar 和 Date。
| 't''t'日期和時間轉換字符的前綴。'T''T''t' 的大寫形式。 |
以下日期和時間轉換字符后綴是為 't' 和 'T' 轉換定義的。這些類型類似於但不完全等同於 GNU date 和 POSIX strftime(3c) 定義的那些類型。提供其他轉換類型是為了訪問特定於 Java 的功能（例如，'L'用於秒中的毫秒）。
以下轉換字符用來格式化時間：
| 'H''H'24 小時制的小時，被格式化為必要時帶前導零的兩位數，即 00 - 23。00對應午夜。'I''I'12 小時制的小時，被格式化為必要時帶前導零的兩位數，即 01 - 12。01對應於 1 點鍾（上午或下午）。'k''k'24 小時制的小時，即 0 - 23。0對應於午夜。'l''l'12 小時制的小時，即 1 - 12。1對應於上午或下午的一點鍾。'M''M'小時中的分鍾，被格式化為必要時帶前導零的兩位數，即 00 - 59。'S''S'分鍾中的秒，被格式化為必要時帶前導零的兩位數，即 00 - 60（"60" 是支持閏秒所需的一個特殊值）。'L''L'秒中的毫秒，被格式化為必要時帶前導零的三位數，即 000 - 999。'N''N'秒中的毫微秒，被格式化為必要時帶前導零的九位數，即 000000000 - 999999999。此值的精度受底層操作系統或硬件解析的限制。'p''p'特定於語言環境的上午或下午標記以小寫形式表示，例如 "am" 或 "pm"。使用轉換前綴 'T' 可以強行將此輸出轉換為大寫形式。（注意，'p' 產生的輸出是小寫的。而 GNU date 和 POSIX strftime(3c)產生的輸出是大寫的。）'z''z'相對於 GMT 的 RFC 822 格式的數字時區偏移量，例如 -0800。'Z''Z'表示時區的縮寫形式的字符串。's''s'自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的秒數，也就是 Long.MIN_VALUE/1000 與 Long.MAX_VALUE/1000之間的差值。'Q''O'自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的毫秒數，即 Long.MIN_VALUE 與 Long.MAX_VALUE 之間的差值。此值的精度受底層操作系統或硬件解析的限制。 |
以下轉換字符用來格式化日期：
| 'B''B'特定於語言環境的完整月份名稱，例如 "January" 和 "February"。'b''b'特定於語言環境的月份簡稱，例如 "Jan" 和 "Feb"。'h''h'與 'b'相同。'A''A'特定於語言環境的星期幾的全稱，例如 "Sunday" 和 "Monday"'a''a'特定於語言環境的星期幾的簡稱，例如 "Sun" 和 "Mon"'C''C'除以 100 的四位數表示的年份，被格式化為必要時帶前導零的兩位數，即 00 - 99'Y''Y'年份，被格式化為必要時帶前導零的四位數（至少），例如 0092 等於格里高利歷的 92CE。'y''y'年份的最后兩位數，被格式化為必要時帶前導零的兩位數，即 00 - 99。'j''j'一年中的天數，被格式化為必要時帶前導零的三位數，例如，對於格里高利歷是 001 - 366。001對應於一年中的第一天。'm''m'月份，被格式化為必要時帶前導零的兩位數，即 01 - 13，其中 "01" 是一年的第一個月，("13" 是支持陰歷所需的一個特殊值）。'd''d'一個月中的天數，被格式化為必要時帶前導零的兩位數，即 01 - 31，其中 "01" 是一個月的第一天。'e''e'一個月中的天數，被格式化為兩位數，即 1 - 31，其中 "1" 是一個月中的第一天。 |
以下轉換字符用於格式化常見的日期/時間組合。
| 'R''R'24 小時制的時間，被格式化為 "%tH:%tM"'T''T'24 小時制的時間，被格式化為 "%tH:%tM:%tS"。'r''r'12 小時制的時間，被格式化為 "%tI:%tM:%tS %Tp"。上午或下午標記 ('%Tp') 的位置可能與地區有關。'D''D'日期，被格式化為 "%tm/%td/%ty"。'F''F'ISO 8601 格式的完整日期，被格式化為 "%tY-%tm-%td"。'c''c'日期和時間，被格式化為 "%ta %tb %td %tT %tZ %tY"，例如 "Sun Jul 20 16:17:00 EDT 1969"。 |
應用為常規轉換而定義的 '-' 標志。如果給出 '#' 標志，則將拋出 FormatFlagsConversionMismatchException。
寬度 是將向輸出中寫入的最少字符數。如果轉換值的長度小於 width，則用空格(' ') 來填充輸出，直到總字符數等於寬度。默認情況下，在左邊進行填充。如果給出 '-'標志，則在右邊進行填充。如果沒有指定寬度，則沒有最小寬度。
精度不適用。如果指定了精度，則將拋出 IllegalFormatPrecisionException。
百分比
該轉換不對應於任何參數。
| '%'結果是一個字面值 '%' ('%') 寬度 是將向輸出中寫入的最少字符數，包括 '%'。如果轉換值的長度小於 width，則用空格 (' ') 來填充輸出，直到總字符數等於寬度。在左邊進行填充。如果沒有指定寬度，則只輸出 '%'。 應用為常規轉換而定義的 '-' 標志。如果提供其他任何標志，則將拋出 精度不適用。如果指定精度，則將拋出 |
行分隔符
該轉換不對應於任何參數。
'n'由 System.getProperty("line.separator") 返回的特定於平台的行分隔符。 |
標志、寬度和精度都不可用。如果提供這三者，則會分別拋出 IllegalFormatFlagsException、IllegalFormatWidthException 和 IllegalFormatPrecisionException。
參數索引
格式說明符可以通過三種方式引用參數：
- 顯式索引 是在格式說明符中包含參數索引時使用。參數索引是一個十進制整數，用於指示參數在參數列表中的位置。第一個參數由 "1$" 引用，第二個參數由 "2$" 引用，依此類推。可以多次引用任何一個參數。
例如：
formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s", "a", "b", "c", "d") // -> "d c b a d c b a" - 相對索引 是在格式說明符中包含 '<' ('<') 標志時使用，該標志將導致重用以前格式說明符的參數。如果不存在以前的參數，則拋出
MissingFormatArgumentException。formatter.format("%s %s %<s %<s", "a", "b", "c", "d") // -> "b a a b" // "c" and "d" are ignored because they are not referenced - 普通索引 在格式說明符中既不包含參數索引也不包含 '<'標志時使用。每個使用普通索引的格式說明符都分配了一個連續隱式索引，分配在獨立於顯式索引或相對索引使用的參數列表中。
formatter.format("%s %s %s %s", "a", "b", "c", "d") // -> "a b c d"
可能有一個使用所有索引形式的格式字符串，例如：
formatter.format("%2$s %s %<s %s", "a", "b", "c", "d")
// -> "b a a b"
// "c" and "d" are ignored because they are not referenced
參數的最大數量受到 Java Machine Specification 定義的 Java 數組 的最大維數的限制。如果參數索引與可用參數不對應，則拋出 MissingFormatArgumentException。
如果參數多於格式說明符，則忽略額外的參數。
除非另行指定，否則向此類中的任何方法或構造方法傳遞 null 參數都將拋出 NullPointerException。
| version | 1.26, 06/28/06 |
| since | 1.5 |
| Constructors | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public | Formatter() 構造一個新 formatter。 格式化輸出的目標文件是
|
||||||||||||
| public | Formatter(Appendable a) 構造一個帶指定目標文件的新 formatter。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(Locale l) 構造一個帶指定語言環境的新 formatter。 格式化輸出的目標文件是
|
||||||||||||
| public | Formatter(Appendable a, Locale l) 構造一個帶指定目標文件和語言環境的新 formatter。
|
||||||||||||
| public | Formatter(String fileName) throws FileNotFoundException 構造一個帶指定文件名的新 formatter。 對於 Java 虛擬機的此實例，所使用的字符集是默認字符集。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException 構造一個帶指定文件名和字符集的新 formatter。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException 構造一個帶指定文件名、字符集和語言環境的新 formatter。
|
||||||||||||
| public | Formatter(File file) throws FileNotFoundException 構造一個帶指定文件的新 formatter。 對於 Java 虛擬機的此實例，所使用的字符集是默認字符集。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException 構造一個帶指定文件和字符集的新 formatter。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException 構造一個帶指定文件、字符集和語言環境的新 formatter。
|
||||||||||||
| public | Formatter(PrintStream ps) 構造一個帶指定輸出流的新 formatter。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。 將字符寫入給定的
|
||||||||||||
| public | Formatter(OutputStream os) 構造一個帶指定輸出流的新 formatter。 對於 Java 虛擬機的此實例，所使用的字符集是默認字符集。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(OutputStream os, String csn) throws UnsupportedEncodingException 構造一個帶指定輸出流和字符集的新 formatter。 對於 Java 虛擬機的此實例，所使用的語言環境是默認語言環境。
|
||||||||||||
| public | Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException 構造一個帶指定輸出流、字符集和語言環境的新 formatter。
|
||||||||||||
| Methods | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public void | close() 關閉此 formatter。如果目標文件實現 java.io.Closeable 接口，則調用其 close方法。 關閉 formatter 允許釋放它可能保持（比如打開文件）的資源。如果已經關閉 formatter，則調用此方法無效。 如果試圖在此 formatter 已經關閉之后調用其中除
|
||||||||||||
| public void | flush() 刷新此 formatter。如果目標文件實現 java.io.Flushable 接口，則調用其 flush方法。 刷新 formatter 會使目標文件中的所有緩沖輸出都寫入底層流中。
|
||||||||||||
| public Formatter | format(String format, Object[] args) 使用指定格式字符串和參數將一個格式化字符串寫入此對象的目標文件中。使用的語言環境是構造此 formatter 期間定義的語言環境。
|
||||||||||||
| public Formatter | format(Locale l, String format, Object[] args) 使用指定的語言環境、格式字符串和參數，將一個格式化字符串寫入此對象的目標文件中。
|
||||||||||||
| public IOException | ioException() 返回由此 formatter 的 Appendable 方法上次拋出的 IOException異常。 如果目標文件的 append() 方法從未拋出 IOException，則此方法將始終返回 null。
|
||||||||||||
| public Locale | locale() 返回構造此 formatter 時設置的語言環境。 此對象的帶語言環境參數的
|
||||||||||||
| public Appendable | out() 返回輸出的目標文件。
|
||||||||||||
| public String | toString() 返回對輸出的目標文件調用 toString() 的結果。例如，以下代碼將文本格式化到 StringBuilder中，然后獲取得到的字符串：
調用此方法的方式與調用 out().toString() 的方式完全相同。
out().toString() 根據針對
|
||||||||||||