鴻蒙OS Formatter

Formatter

java.lang.Object

|---java.util.Formatter

public final class Formatter
extends Object
implements Closeable, Flushable

printf 樣式格式字符串的解釋器。 此類提供對(duì)布局對(duì)齊和對(duì)齊、數(shù)字、字符串和日期/時(shí)間數(shù)據(jù)的通用格式以及特定于語(yǔ)言環(huán)境的輸出的支持。 支持常見的 Java 類型，例如 byte、BigDecimal 和 Calendar。 通過 Formattable 接口為任意用戶類型提供有限的格式定制。

格式化程序?qū)τ诙嗑€程訪問不一定是安全的。 線程安全是可選的，并且是此類中方法的用戶的責(zé)任。

Java 語(yǔ)言的格式化打印很大程度上受到 C 的 printf 的啟發(fā)。 盡管格式字符串與 C 相似，但已進(jìn)行了一些定制以適應(yīng) Java 語(yǔ)言并利用其某些特性。 此外，Java 格式比 C 更嚴(yán)格； 例如，如果轉(zhuǎn)換與標(biāo)志不兼容，則會(huì)引發(fā)異常。 在 C 中，不適用的標(biāo)志會(huì)被默默地忽略。 因此，格式字符串旨在為 C 程序員識(shí)別，但不一定與 C 中的格式字符串完全兼容。

預(yù)期用法示例：

   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)"

如以下調(diào)用所示，存在用于常見格式化請(qǐng)求的便捷方法：

   // 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) 一樣，可以使用靜態(tài)方法 String#format(String,Object...) 格式化字符串：

   // 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$tb %1$te, %1$tY", c);
   // -> s == "Duke's Birthday: May 23, 1995"

組織

本規(guī)范分為兩部分。 第一部分，摘要，涵蓋了基本的格式化概念。 本部分適用于希望快速入門并熟悉其他編程語(yǔ)言的格式化打印的用戶。 第二部分，詳細(xì)信息，涵蓋了具體的實(shí)現(xiàn)細(xì)節(jié)。 它適用于想要更精確地規(guī)范格式化行為的用戶。

概括

本節(jié)旨在提供格式化概念的簡(jiǎn)要概述。

格式化字符串語(yǔ)法

每個(gè)產(chǎn)生格式化輸出的方法都需要一個(gè)格式字符串和一個(gè)參數(shù)列表。 格式字符串是一個(gè)可以包含固定文本和一個(gè)或多個(gè)嵌入格式說明符的字符串。 考慮以下示例：

   Calendar c = ...;
   String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);

此格式字符串是格式方法的第一個(gè)參數(shù)。 它包含三個(gè)格式說明符“%1$tm”、“%1$te”和“%1$tY”，它們指示應(yīng)如何處理參數(shù)以及應(yīng)在文本中插入的位置。 格式字符串的其余部分是固定文本，包括“公爵生日：”和任何其他空格或標(biāo)點(diǎn)符號(hào)。 參數(shù)列表包含在格式字符串之后傳遞給方法的所有參數(shù)。 在上面的示例中，參數(shù)列表的大小為 1，由日歷對(duì)象 c 組成。

• 通用、字符和數(shù)字類型的格式說明符具有以下語(yǔ)法：

     %[argument_index$][flags][width][.precision]conversion 

可選的 argument_index 是一個(gè)十進(jìn)制整數(shù)，指示參數(shù)在參數(shù)列表中的位置。 第一個(gè)參數(shù)由“1$”引用，第二個(gè)由“2$”引用，以此類推。

可選標(biāo)志是一組修改輸出格式的字符。 有效標(biāo)志集取決于轉(zhuǎn)換。

可選寬度是一個(gè)十進(jìn)制正整數(shù)，指示要寫入輸出的最小字符數(shù)。

可選精度是一個(gè)非負(fù)十進(jìn)制整數(shù)，通常用于限制字符數(shù)。 具體行為取決于轉(zhuǎn)換。

所需的轉(zhuǎn)換是一個(gè)字符，指示應(yīng)如何格式化參數(shù)。 給定參數(shù)的有效轉(zhuǎn)換集取決于參數(shù)的數(shù)據(jù)類型。

• 用于表示日期和時(shí)間的類型的格式說明符具有以下語(yǔ)法：

     %[argument_index$][flags][width]conversion 

可選的參數(shù)索引、標(biāo)志和寬度定義如上。

所需的轉(zhuǎn)換是兩個(gè)字符序列。 第一個(gè)字符是“t”或“T”。 第二個(gè)字符表示要使用的格式。 這些字符與 GNU date 和 POSIX strftime(3c) 定義的字符相似但不完全相同。

• 與參數(shù)不對(duì)應(yīng)的格式說明符具有以下語(yǔ)法：

     %[flags][width]conversion 

可選標(biāo)志和寬度定義如上。

所需的轉(zhuǎn)換是指示要在輸出中插入的內(nèi)容的字符。

轉(zhuǎn)換

轉(zhuǎn)換分為以下幾類：

1. 一般 - 可應(yīng)用于任何參數(shù)類型

1. 字符 - 可應(yīng)用于表示 Unicode 字符的基本類型：char、Character、byte、Byte、short 和 Short。 當(dāng) Character#isValidCodePoint 返回 true 時(shí)，這種轉(zhuǎn)換也可以應(yīng)用于 int 和 Integer 類型

1. 數(shù)字

• Integral - 可應(yīng)用于 Java 整數(shù)類型：byte、Byte、short、Short、int 和 Integer、long、Long 和 BigInteger（但不是 char 或 Character）

• 浮點(diǎn) - 可應(yīng)用于 Java 浮點(diǎn)類型：float、Float、double、Double 和 BigDecimal

1. 日期/時(shí)間 - 可應(yīng)用于能夠編碼日期或時(shí)間的 Java 類型：long、Long、Calendar、Date 和 TemporalAccessor

1. 百分比 - 產(chǎn)生一個(gè)文字 '%' ('\u0025')

1. Line Separator - 生成特定于平臺(tái)的行分隔符

下表總結(jié)了支持的轉(zhuǎn)換。 由大寫字符表示的轉(zhuǎn)換（即“B”、“H”、“S”、“C”、“X”、“E”、“G”、“A”和“T”）是相同的 與對(duì)應(yīng)的小寫轉(zhuǎn)換字符相同，只是根據(jù)當(dāng)前 Locale 的規(guī)則將結(jié)果轉(zhuǎn)換為大寫。 結(jié)果等效于以下對(duì) String#toUpperCase() 的調(diào)用

    out.toUpperCase() 

任何未明確定義為轉(zhuǎn)換的字符都是非法的，并為將來的擴(kuò)展保留。

日期/時(shí)間轉(zhuǎn)換

為“t”和“T”轉(zhuǎn)換定義了以下日期和時(shí)間轉(zhuǎn)換后綴字符。 這些類型與 GNU date 和 POSIX strftime(3c) 定義的類型相似但不完全相同。 提供了其他轉(zhuǎn)換類型來訪問特定于 Java 的功能（例如，“L”表示秒內(nèi)的毫秒）。

以下轉(zhuǎn)換字符用于格式化時(shí)間：

以下轉(zhuǎn)換字符用于格式化日期：

以下轉(zhuǎn)換字符用于格式化常見的日期/時(shí)間組合。

任何未明確定義為日期/時(shí)間轉(zhuǎn)換后綴的字符都是非法的，并為將來的擴(kuò)展保留。

標(biāo)志

下表總結(jié)了支持的標(biāo)志。 y 表示指示的參數(shù)類型支持該標(biāo)志。

1. 取決于 Formattable 的定義。
2. 僅用于“d”轉(zhuǎn)換。

1. 僅適用于“o”、“x”和“X”轉(zhuǎn)換。

1. 對(duì)于應(yīng)用于 BigInteger 的 'd'、'o'、'x' 和 'X' 轉(zhuǎn)換或應(yīng)用于 byte、Byte、short、Short、int 和 Integer、long 和 Long 的 'd'。

1. 僅適用于“e”、“E”、“f”、“g”和“G”轉(zhuǎn)換。

任何未明確定義為標(biāo)志的字符都是非法的，并為將來的擴(kuò)展保留。

寬度

寬度是要寫入輸出的最小字符數(shù)。 對(duì)于行分隔符轉(zhuǎn)換，寬度不適用； 如果提供，將拋出異常。

精確

對(duì)于一般參數(shù)類型，精度是要寫入輸出的最大字符數(shù)。

對(duì)于浮點(diǎn)轉(zhuǎn)換“a”、“A”、“e”、“E”和“f”，精度是小數(shù)點(diǎn)后的位數(shù)。 如果轉(zhuǎn)換為“g”或“G”，則精度是舍入后結(jié)果幅度中的總位數(shù)。

對(duì)于字符、整數(shù)和日期/時(shí)間參數(shù)類型以及百分比和行分隔符轉(zhuǎn)換，精度不適用； 如果提供了精度，則會(huì)拋出異常。

參數(shù)索引

參數(shù)索引是一個(gè)十進(jìn)制整數(shù)，指示參數(shù)在參數(shù)列表中的位置。 第一個(gè)參數(shù)由“1$”引用，第二個(gè)由“2$”引用，以此類推。

按位置引用參數(shù)的另一種方法是使用 '<' ('\u003c') 標(biāo)志，這會(huì)導(dǎo)致重新使用前一個(gè)格式說明符的參數(shù)。 例如，以下兩個(gè)語(yǔ)句將產(chǎn)生相同的字符串：

   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);

細(xì)節(jié)

本節(jié)旨在提供格式化的行為細(xì)節(jié)，包括條件和異常、支持的數(shù)據(jù)類型、本地化以及標(biāo)志、轉(zhuǎn)換和數(shù)據(jù)類型之間的交互。

任何未明確定義為轉(zhuǎn)換、日期/時(shí)間轉(zhuǎn)換后綴或標(biāo)志的字符都是非法的，并為將來的擴(kuò)展保留。在格式字符串中使用此類字符將導(dǎo)致拋出 UnknownFormatConversionException 或 UnknownFormatFlagsException。

如果格式說明符包含具有無效值或不受支持的寬度或精度，則將分別拋出 IllegalFormatWidthException 或 IllegalFormatPrecisionException。

如果格式說明符包含不適用于相應(yīng)參數(shù)的轉(zhuǎn)換字符，則會(huì)拋出 IllegalFormatConversionException。

Formatter 的任何格式方法以及任何格式便利方法（例如 String#format(String,Object...) 和 PrintStream.printf）都可能引發(fā)所有指定的異常。

由大寫字符表示的轉(zhuǎn)換（即“B”、“H”、“S”、“C”、“X”、“E”、“G”、“A”和“T”）是相同的與對(duì)應(yīng)的小寫轉(zhuǎn)換字符相同，只是根據(jù)當(dāng)前 Locale 的規(guī)則將結(jié)果轉(zhuǎn)換為大寫。結(jié)果等效于以下對(duì) String#toUpperCase() 的調(diào)用

    out.toUpperCase() 

一般的

以下一般轉(zhuǎn)換可應(yīng)用于任何參數(shù)類型：

以下標(biāo)志適用于一般轉(zhuǎn)換：

寬度是要寫入輸出的最小字符數(shù)。如果轉(zhuǎn)換后的值的長(zhǎng)度小于寬度，則輸出將被 ' ' ('\u0020') 填充，直到字符總數(shù)等于寬度。默認(rèn)情況下，填充位于左側(cè)。如果給出“-”標(biāo)志，則填充將在右側(cè)。如果未指定寬度，則沒有最小值。

精度是要寫入輸出的最大字符數(shù)。精度在寬度之前應(yīng)用，因此即使寬度大于精度，輸出也會(huì)被截?cái)酁榫茸址?。如果未指定精度，則對(duì)字符數(shù)沒有明確限制。

字符 這種轉(zhuǎn)換可以應(yīng)用于 char 和 Character。當(dāng) Character#isValidCodePoint 返回 true 時(shí)，它也可以應(yīng)用于 byte、Byte、short 和 Short、int 和 Integer 類型。如果它返回 false，則會(huì)拋出 IllegalFormatCodePointException。

為常規(guī)轉(zhuǎn)換定義的“-”標(biāo)志適用。如果給出了 '#' 標(biāo)志，則將拋出 FormatFlagsConversionMismatchException。

寬度定義為通用轉(zhuǎn)換。

精度不適用。如果指定了精度，則會(huì)拋出 IllegalFormatPrecisionException。

數(shù)字

數(shù)值轉(zhuǎn)換分為以下幾類：

1. Byte, Short, Integer, and Long
2. BigInteger
3. Float and Double
4. BigDecimal

數(shù)字類型將根據(jù)以下算法進(jìn)行格式化：

號(hào)碼定位算法

在為整數(shù)部分、小數(shù)部分和指數(shù)（根據(jù)數(shù)據(jù)類型而定）獲得數(shù)字后，將應(yīng)用以下轉(zhuǎn)換：

1. 字符串中的每個(gè)數(shù)字字符 d 被替換為相對(duì)于當(dāng)前語(yǔ)言環(huán)境的零位 z 計(jì)算的語(yǔ)言環(huán)境特定數(shù)字；即 d - '0' + z。
2. 如果存在小數(shù)分隔符，則替換特定于區(qū)域設(shè)置的小數(shù)分隔符。
3. 如果給出',' ('\u002c') 標(biāo)志，則通過從最低有效位到最高有效位掃描字符串的整數(shù)部分并在由語(yǔ)言環(huán)境的分組大小。
4. 如果給出 '0' 標(biāo)志，則在符號(hào)字符（如果有）之后和第一個(gè)非零數(shù)字之前插入特定于語(yǔ)言環(huán)境的零數(shù)字，直到字符串的長(zhǎng)度等于請(qǐng)求的字段寬度.
5. 如果值為負(fù)并且給出了 '(' 標(biāo)志，則附加一個(gè) '(' ('\u0028') 并附加一個(gè) ')' ('\u0029')。
6. 如果該值為負(fù)數(shù)（或浮點(diǎn)負(fù)零）并且沒有給出'(' 標(biāo)志，則在前面加上'-' ('\u002d')。
7. 如果給出'+' 標(biāo)志并且值為正或零（或浮點(diǎn)正零），則將在前面加上'+' ('\u002b')。

如果值為 NaN 或正無窮大，則將分別輸出文字字符串“NaN”或“Infinity”。 如果該值為負(fù)無窮大，則如果給出了“（”標(biāo)志，則輸出將為“（無窮大）”，否則輸出將為“-Infinity”。這些值未本地化。

Byte, Short, Integer, and Long

以下轉(zhuǎn)換可應(yīng)用于 byte、Byte、short、Short、int 和 Integer、long 和 Long。

如果轉(zhuǎn)換為 'o'、'x' 或 'X' 并且同時(shí)給出了 '#' 和 '0' 標(biāo)志，則結(jié)果將包含基數(shù)指示符（'0' 表示八進(jìn)制和“0x”或“ 0X" 表示十六進(jìn)制）、一些零（基于寬度）和值。

如果未給出“-”標(biāo)志，則空格填充將出現(xiàn)在符號(hào)之前。

以下標(biāo)志適用于數(shù)值整數(shù)轉(zhuǎn)換：

如果沒有給出標(biāo)志，則默認(rèn)格式如下：

• 輸出在寬度內(nèi)右對(duì)齊
• 負(fù)數(shù)以“-”開頭（“\u002d”）
• 正數(shù)和零不包括符號(hào)或額外的前導(dǎo)空格
• 不包括分組分隔符

寬度是要寫入輸出的最小字符數(shù)。 這包括任何符號(hào)、數(shù)字、分組分隔符、基數(shù)指示符和括號(hào)。 如果轉(zhuǎn)換后的值的長(zhǎng)度小于寬度，則輸出將用空格 ('\u0020') 填充，直到字符總數(shù)等于寬度。 默認(rèn)情況下，填充位于左側(cè)。 如果給出“-”標(biāo)志，則填充將在右側(cè)。 如果未指定寬度，則沒有最小值。

精度不適用。 如果指定了精度，則將拋出 IllegalFormatPrecisionException。

BigInteger

以下轉(zhuǎn)換可應(yīng)用于 BigInteger。

如果轉(zhuǎn)換為 'o'、'x' 或 'X' 并且同時(shí)給出了 '#' 和 '0' 標(biāo)志，則結(jié)果將包含基本指示符（'0' 表示八進(jìn)制和“0x”或“ 0X" 表示十六進(jìn)制）、一些零（基于寬度）和值。

如果給出'0'標(biāo)志并且值為負(fù)，則零填充將出現(xiàn)在符號(hào)之后。

如果未給出“-”標(biāo)志，則空格填充將出現(xiàn)在符號(hào)之前。

為 Byte、Short、Integer 和 Long 定義的所有標(biāo)志都適用。 未給出標(biāo)志時(shí)的默認(rèn)行為與 Byte、Short、Integer 和 Long 相同。

寬度的規(guī)格與 Byte、Short、Integer 和 Long 的定義相同。

精度不適用。 如果指定了精度，則將拋出 IllegalFormatPrecisionException。

Float and Double

以下轉(zhuǎn)換可應(yīng)用于 float、Float、double 和 Double。

為 Byte、Short、Integer 和 Long 定義的所有標(biāo)志都適用。

如果給出了“#”標(biāo)志，那么小數(shù)分隔符將始終存在。

如果沒有給出標(biāo)志，則默認(rèn)格式如下：

• 輸出在寬度內(nèi)右對(duì)齊
• 負(fù)數(shù)以“-”開頭
• 正數(shù)和正零不包括符號(hào)或額外的前導(dǎo)空格
• 不包括分組分隔符
• 小數(shù)分隔符僅在后面有數(shù)字時(shí)才會(huì)出現(xiàn)

寬度是要寫入輸出的最小字符數(shù)。這包括任何符號(hào)、數(shù)字、分組分隔符、小數(shù)分隔符、指數(shù)符號(hào)、基數(shù)指示符、括號(hào)以及表示無窮大和 NaN 的字符串（如果適用）。如果轉(zhuǎn)換后的值的長(zhǎng)度小于寬度，則輸出將用空格 ('\u0020') 填充，直到字符總數(shù)等于寬度。默認(rèn)情況下，填充位于左側(cè)。如果給出“-”標(biāo)志，則填充將在右側(cè)。如果未指定寬度，則沒有最小值。

如果轉(zhuǎn)換為“e”、“E”或“f”，則精度為小數(shù)分隔符后的位數(shù)。如果未指定精度，則假定為 6。

如果轉(zhuǎn)換為“g”或“G”，則精度是舍入后所得幅度中有效數(shù)字的總數(shù)。如果未指定精度，則默認(rèn)值為 6。如果精度為 0，則取為 1。

如果轉(zhuǎn)換為“a”或“A”，則精度為小數(shù)點(diǎn)后的十六進(jìn)制位數(shù)。如果未提供精度，則將輸出 Double#toHexString(double) 返回的所有數(shù)字。

BigDecimal

以下轉(zhuǎn)換可能適用于 BigDecimal。

為 Byte、Short、Integer 和 Long 定義的所有標(biāo)志都適用。

如果給出了“#”標(biāo)志，那么小數(shù)分隔符將始終存在。

沒有給出標(biāo)志時(shí)的默認(rèn)行為與 Float 和 Double 相同。

寬度和精度的規(guī)格與 Float 和 Double 的定義相同。

Date/Time

此轉(zhuǎn)換可應(yīng)用于 long、Long、Calendar、Date 和 TemporalAccessor

為“t”和“T”轉(zhuǎn)換定義了以下日期和時(shí)間轉(zhuǎn)換字符后綴。這些類型與 GNU date 和 POSIX strftime(3c) 定義的類型相似但不完全相同。提供了其他轉(zhuǎn)換類型來訪問特定于 Java 的功能（例如，“L”表示秒內(nèi)的毫秒）。

以下轉(zhuǎn)換字符用于格式化時(shí)間：

以下轉(zhuǎn)換字符用于格式化日期：

以下轉(zhuǎn)換字符用于格式化常見的日期/時(shí)間組合。

為常規(guī)轉(zhuǎn)換定義的“-”標(biāo)志適用。如果給出了 '#' 標(biāo)志，則將拋出 FormatFlagsConversionMismatchException。

寬度是要寫入輸出的最小字符數(shù)。如果轉(zhuǎn)換后的值的長(zhǎng)度小于寬度，則輸出將用空格 ('\u0020') 填充，直到字符總數(shù)等于寬度。默認(rèn)情況下，填充位于左側(cè)。如果給出“-”標(biāo)志，則填充將在右側(cè)。如果未指定寬度，則沒有最小值。

精度不適用。如果指定了精度，則會(huì)拋出 IllegalFormatPrecisionException。

Percent

轉(zhuǎn)換不對(duì)應(yīng)于任何參數(shù)。

Line Separator

轉(zhuǎn)換不對(duì)應(yīng)于任何參數(shù)。

標(biāo)志、寬度和精度不適用。 如果提供了任何一個(gè) IllegalFormatFlagsException、IllegalFormatWidthException 和 IllegalFormatPrecisionException，將分別拋出。

Argument Index

格式說明符可以通過三種方式引用參數(shù)：

• 當(dāng)格式說明符包含參數(shù)索引時(shí)，使用顯式索引。 參數(shù)索引是一個(gè)十進(jìn)制整數(shù)，指示參數(shù)在參數(shù)列表中的位置。 第一個(gè)參數(shù)由“1$”引用，第二個(gè)由“2$”引用，依此類推。一個(gè)參數(shù)可能被引用多次。

例如:

     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"

• 當(dāng)格式說明符包含'<' ('\u003c') 標(biāo)志時(shí)使用相對(duì)索引，這會(huì)導(dǎo)致前一個(gè)格式說明符的參數(shù)被重新使用。 如果沒有先前的參數(shù)，則拋出 MissingFormatArgumentException。

      formatter.format("%s %s %<s %<s", "a", "b", "c", "d")
      // -> "a b b b"
      // "c" and "d" are ignored because they are not referenced

• 當(dāng)格式說明符既不包含參數(shù)索引也不包含“<”標(biāo)志時(shí)，使用普通索引。 每個(gè)使用普通索引的格式說明符都被分配到參數(shù)列表中的順序隱式索引，該索引獨(dú)立于顯式或相對(duì)索引使用的索引。

     formatter.format("%s %s %s %s", "a", "b", "c", "d")
     // -> "a b c d"

可以有一個(gè)格式字符串使用所有形式的索引，例如：

   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

參數(shù)的最大數(shù)量受《Java? 虛擬機(jī)規(guī)范》中定義的 Java 數(shù)組的最大維度限制。 如果參數(shù)索引與可用參數(shù)不對(duì)應(yīng)，則拋出 MissingFormatArgumentException。

如果參數(shù)多于格式說明符，則忽略多余的參數(shù)。

除非另有說明，否則將 null 參數(shù)傳遞給此類中的任何方法或構(gòu)造函數(shù)將導(dǎo)致拋出 NullPointerException。

嵌套類摘要

修飾符和類型	類	描述
static class	Formatter.BigDecimalLayoutForm	BigDecimal 格式的枚舉。

構(gòu)造函數(shù)摘要

構(gòu)造函數(shù)	描述
Formatter()	構(gòu)造一個(gè)新的格式化程序。
Formatter(File file)	用指定的文件構(gòu)造一個(gè)新的格式化程序。
Formatter(File file, String csn)	使用指定的文件和字符集構(gòu)造一個(gè)新的格式化程序。
Formatter(File file, String csn, Locale l)	使用指定的文件、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。
Formatter(OutputStream os)	使用指定的輸出流構(gòu)造一個(gè)新的格式化程序。
Formatter(OutputStream os, String csn)	使用指定的輸出流和字符集構(gòu)造一個(gè)新的格式化程序。
Formatter(OutputStream os, String csn, Locale l)	使用指定的輸出流、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。
Formatter(PrintStream ps)	使用指定的打印流構(gòu)造一個(gè)新的格式化程序。
Formatter(Appendable a)	構(gòu)造具有指定目標(biāo)的新格式化程序。
Formatter(Appendable a, Locale l)	構(gòu)造具有指定目標(biāo)和語(yǔ)言環(huán)境的新格式化程序。
Formatter(String fileName)	構(gòu)造具有指定文件名的新格式化程序。
Formatter(String fileName, String csn)	使用指定的文件名和字符集構(gòu)造一個(gè)新的格式化程序。
Formatter(String fileName, String csn, Locale l)	使用指定的文件名、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。
Formatter(Locale l)	構(gòu)造具有指定語(yǔ)言環(huán)境的新格式化程序。

方法總結(jié)

修飾符和類型	方法	描述
void	close()	關(guān)閉此格式化程序。
void	flush()	刷新此格式化程序。
Formatter	format(String format, Object... args)	使用指定的格式字符串和參數(shù)將格式化字符串寫入此對(duì)象的目標(biāo)。
Formatter	format(Locale l, String format, Object... args)	使用指定的語(yǔ)言環(huán)境、格式字符串和參數(shù)將格式化字符串寫入此對(duì)象的目標(biāo)。
IOException	ioException()	返回此格式化程序的 Appendable 上次拋出的 IOException。
Locale	locale()	返回由構(gòu)造此格式化程序設(shè)置的語(yǔ)言環(huán)境。
Appendable	out()	返回輸出的目的地。
String	toString()	返回在輸出目標(biāo)上調(diào)用 toString() 的結(jié)果。

從類 java.lang.Object 繼承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

構(gòu)造函數(shù)詳細(xì)信息

Formatter

public Formatter()

構(gòu)造一個(gè)新的格式化程序。

格式化輸出的目的地是一個(gè) StringBuilder，可以通過調(diào)用 out() 來檢索它，并且可以通過調(diào)用 toString() 將其當(dāng)前內(nèi)容轉(zhuǎn)換為字符串。 對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

Formatter

public Formatter(Appendable a)

構(gòu)造具有指定目標(biāo)的新格式化程序。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
a	格式化輸出的目的地。 如果 a 為 null，則將創(chuàng)建一個(gè) StringBuilder。

Formatter

public Formatter(Locale l)

構(gòu)造具有指定語(yǔ)言環(huán)境的新格式化程序。

格式化輸出的目的地是一個(gè) StringBuilder，可以通過調(diào)用 out() 來檢索它，并且可以通過調(diào)用 toString() 將其當(dāng)前內(nèi)容轉(zhuǎn)換為字符串。

參數(shù)：

參數(shù)名稱	參數(shù)描述
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。

Formatter

public Formatter(Appendable a, Locale l)

構(gòu)造具有指定目標(biāo)和語(yǔ)言環(huán)境的新格式化程序。

參數(shù)：

參數(shù)名稱	參數(shù)描述
a	格式化輸出的目的地。 如果 a 為 null，則將創(chuàng)建一個(gè) StringBuilder。
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。

Formatter

public Formatter(String fileName) throws FileNotFoundException

構(gòu)造具有指定文件名的新格式化程序。

使用的字符集是此 Java 虛擬機(jī)實(shí)例的默認(rèn)字符集。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
fileName	用作此格式化程序目標(biāo)的文件的名稱。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。

Throws:

Throw名稱	Throw描述
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
FileNotFoundException	如果給定的文件名不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)出現(xiàn)其他錯(cuò)誤

Formatter

public Formatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException

使用指定的文件名和字符集構(gòu)造一個(gè)新的格式化程序。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
fileName	用作此格式化程序目標(biāo)的文件的名稱。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。
csn	支持的字符集的名稱

Throws:

Throw名稱	Throw描述
FileNotFoundException	如果給定的文件名不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)出現(xiàn)其他錯(cuò)誤
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
UnsupportedEncodingException	如果不支持命名字符集

Formatter

public Formatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException

使用指定的文件名、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。

參數(shù)：

參數(shù)名稱	參數(shù)描述
fileName	用作此格式化程序目標(biāo)的文件的名稱。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。
csn	支持的字符集的名稱
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。

Throws:

Throw名稱	Throw描述
FileNotFoundException	如果給定的文件名不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)出現(xiàn)其他錯(cuò)誤
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
UnsupportedEncodingException	如果不支持命名字符集

Formatter

public Formatter(File file) throws FileNotFoundException

用指定的文件構(gòu)造一個(gè)新的格式化程序。

使用的字符集是此 Java 虛擬機(jī)實(shí)例的默認(rèn)字符集。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
file	用作此格式化程序目標(biāo)的文件。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。

Throws:

Throw名稱	Throw描述
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
FileNotFoundException	如果給定的文件對(duì)象不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)發(fā)生其他錯(cuò)誤

Formatter

public Formatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException

使用指定的文件和字符集構(gòu)造一個(gè)新的格式化程序。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
file	用作此格式化程序目標(biāo)的文件。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。
csn	支持的字符集的名稱

Throws:

Throw名稱	Throw描述
FileNotFoundException	如果給定的文件對(duì)象不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)發(fā)生其他錯(cuò)誤
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
UnsupportedEncodingException	如果不支持命名字符集

Formatter

public Formatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException

使用指定的文件、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。

參數(shù)：

參數(shù)名稱	參數(shù)描述
file	用作此格式化程序目標(biāo)的文件。 如果文件存在，那么它將被截?cái)酁榱愦笮。?nbsp;否則，將創(chuàng)建一個(gè)新文件。 輸出將被寫入文件并被緩沖。
csn	支持的字符集的名稱
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。

Throws:

Throw名稱	Throw描述
FileNotFoundException	如果給定的文件對(duì)象不表示現(xiàn)有的可寫常規(guī)文件并且無法創(chuàng)建該名稱的新常規(guī)文件，或者在打開或創(chuàng)建文件時(shí)發(fā)生其他錯(cuò)誤
SecurityException	如果存在安全管理器并且 SecurityManager#checkWrite 拒絕對(duì)文件的寫訪問權(quán)限
UnsupportedEncodingException	如果不支持命名字符集

Formatter

public Formatter(PrintStream ps)

使用指定的打印流構(gòu)造一個(gè)新的格式化程序。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

字符被寫入給定的 PrintStream 對(duì)象，因此使用該對(duì)象的字符集進(jìn)行編碼。

參數(shù)：

參數(shù)名稱	參數(shù)描述
ps	用作此格式化程序目標(biāo)的流。

Formatter

public Formatter(OutputStream os)

使用指定的輸出流構(gòu)造一個(gè)新的格式化程序。

使用的字符集是此 Java 虛擬機(jī)實(shí)例的默認(rèn)字符集。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
os	用作此格式化程序目標(biāo)的輸出流。 輸出將被緩沖。

Formatter

public Formatter(OutputStream os, String csn) throws UnsupportedEncodingException

使用指定的輸出流和字符集構(gòu)造一個(gè)新的格式化程序。

對(duì)于此 Java 虛擬機(jī)實(shí)例，使用的語(yǔ)言環(huán)境是 Locale.Category#FORMAT 的 Locale#getDefault(Locale.Category)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
os	用作此格式化程序目標(biāo)的輸出流。 輸出將被緩沖。
csn	支持的字符集的名稱

Throws:

Throw名稱	Throw描述
UnsupportedEncodingException	如果不支持命名字符集

Formatter

public Formatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException

使用指定的輸出流、字符集和語(yǔ)言環(huán)境構(gòu)造一個(gè)新的格式化程序。

參數(shù)：

參數(shù)名稱	參數(shù)描述
os	用作此格式化程序目標(biāo)的輸出流。 輸出將被緩沖。
csn	支持的字符集的名稱
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。

Throws:

Throw名稱	Throw描述
UnsupportedEncodingException	如果不支持命名字符集

方法詳情

locale

public Locale locale()

返回由構(gòu)造此格式化程序設(shè)置的語(yǔ)言環(huán)境。

此對(duì)象的具有語(yǔ)言環(huán)境參數(shù)的格式方法不會(huì)更改此值。

返回:

如果未應(yīng)用本地化，則為 null，否則為語(yǔ)言環(huán)境

Throws:

Throw名稱	Throw描述
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉

out

public Appendable out()

返回輸出的目的地。

返回:

輸出的目的地

Throws:

Throw名稱	Throw描述
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉

toString

public String toString()

返回在輸出目標(biāo)上調(diào)用 toString() 的結(jié)果。 例如，以下代碼將文本格式化為 StringBuilder，然后檢索結(jié)果字符串：

   Formatter f = new Formatter();
   f.format("Last reboot at %tc", lastRebootDate);
   String s = f.toString();
   // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"

此方法的調(diào)用與調(diào)用的行為方式完全相同

     out().toString() 

根據(jù) Appendable 的 toString 規(guī)范，返回的字符串可能包含也可能不包含寫入目標(biāo)的字符。 例如，緩沖區(qū)通常在 toString() 中返回其內(nèi)容，但流不能，因?yàn)閿?shù)據(jù)被丟棄。

覆蓋：

類 Object 中的 toString

返回:

在輸出目標(biāo)上調(diào)用 toString() 的結(jié)果

Throws:

Throw名稱	Throw描述
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉

flush

public void flush()

刷新此格式化程序。 如果目標(biāo)實(shí)現(xiàn)了 Flushable 接口，則會(huì)調(diào)用其 flush 方法。

刷新格式化程序會(huì)將目標(biāo)中的任何緩沖輸出寫入底層流。

指定者：

在接口 Flushable 中刷新

Throws:

Throw名稱	Throw描述
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉

close

public void close()

關(guān)閉此格式化程序。 如果目標(biāo)實(shí)現(xiàn)了 Closeable 接口，則將調(diào)用其 close 方法。

關(guān)閉格式化程序允許它釋放它可能持有的資源（例如打開的文件）。 如果格式化程序已經(jīng)關(guān)閉，則調(diào)用此方法無效。

在此格式化程序關(guān)閉后嘗試調(diào)用除 ioException() 之外的任何方法將導(dǎo)致 FormatterClosedException。

指定者：

在接口 AutoCloseable 中關(guān)閉

指定者：

在接口Closeable中關(guān)閉

ioException

public IOException ioException()

返回此格式化程序的 Appendable 上次拋出的 IOException。

如果目標(biāo)的 append() 方法從不拋出 IOException，則此方法將始終返回 null。

返回:

Appendable 拋出的最后一個(gè)異常，如果不存在此類異常，則返回 null。

format

public Formatter format(String format, Object... args)

使用指定的格式字符串和參數(shù)將格式化字符串寫入此對(duì)象的目標(biāo)。 使用的語(yǔ)言環(huán)境是在構(gòu)造此格式化程序期間定義的語(yǔ)言環(huán)境。

參數(shù)：

參數(shù)名稱	參數(shù)描述
format	格式字符串語(yǔ)法中描述的格式字符串。
args	格式字符串中的格式說明符引用的參數(shù)。 如果參數(shù)多于格式說明符，則忽略多余的參數(shù)。 參數(shù)的最大數(shù)量受《Java? 虛擬機(jī)規(guī)范》中定義的 Java 數(shù)組的最大維度限制。

返回:

這個(gè)格式化程序

Throws:

Throw名稱	Throw描述
IllegalFormatException	如果格式字符串包含非法語(yǔ)法、與給定參數(shù)不兼容的格式說明符、給定格式字符串的參數(shù)不足或其他非法條件。
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉

format

public Formatter format(Locale l, String format, Object... args)

使用指定的語(yǔ)言環(huán)境、格式字符串和參數(shù)將格式化字符串寫入此對(duì)象的目標(biāo)。

參數(shù)：

參數(shù)名稱	參數(shù)描述
l	在格式化期間應(yīng)用的語(yǔ)言環(huán)境。 如果 l 為空，則不應(yīng)用本地化。 這不會(huì)更改在構(gòu)造期間設(shè)置的此對(duì)象的語(yǔ)言環(huán)境。
format	格式字符串語(yǔ)法中描述的格式字符串
args	格式字符串中的格式說明符引用的參數(shù)。 如果參數(shù)多于格式說明符，則忽略多余的參數(shù)。 參數(shù)的最大數(shù)量受《Java? 虛擬機(jī)規(guī)范》中定義的 Java 數(shù)組的最大維度限制。

返回:

這個(gè)格式化程序

Throws:

Throw名稱	Throw描述
IllegalFormatException	如果格式字符串包含非法語(yǔ)法、與給定參數(shù)不兼容的格式說明符、給定格式字符串的參數(shù)不足或其他非法條件。
FormatterClosedException	如果此格式化程序已通過調(diào)用其 close() 方法關(guān)閉