產生格式化輸出的每個方法都需要格式字元串 和參數列表。格式字元串是一個 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(int) 返回 true 時,可將此轉換應用於 int 和 Integer 型別
- 數值
- 整數 - 可應用於 Java 的整數型別:byte、Byte、short、Short、int、Integer、long、Long 和BigInteger
- 浮點 - 可用於 Java 的浮點型別:float、Float、double、Double 和 BigDecimal
- 日期/時間 - 可應用於 Java 的、能夠對日期或時間進行編碼的型別:long、Long、Calendar 和 Date。
- 百分比 - 產生文字值 '%' ('\u0025')
- 行分隔符 - 產生特定於平臺的行分隔符
下表總結了受支持的轉換。由大寫字元(如 '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' | 常規 | |
'c','C' | 字元 | 結果是一個 Unicode 字元 |
'd' | 整數 | 結果被格式化為十進制整數 |
'o' | 整數 | 結果被格式化為八進制整數 |
'x','X' | 整數 | 結果被格式化為十六進制整數 |
'e','E' | 浮點 | 結果被格式化為用計算機科學記數法表示的十進制數 |
'f' | 浮點 | 結果被格式化為十進制數 |
'g','G' | 浮點 | 根據精度和捨入運算後的值,使用計算機科學記數形式或十進制格式對結果進行格式化。 |
'a','A' | 浮點 | 結果被格式化為帶有效位數和指數的十六進制浮點數 |
't','T' | 日期/時間 | 日期和時間轉換字元的前綴。請參閱日期/時間轉換。 |
'%' | 百分比 | 結果為文字值 '%' ('\u0025') |
'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' | |
'z' | |
'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' | |
'b' | |
'h' | 與 'b' 相同。 |
'A' | |
'a' | |
'C' | 除以 100 的四位數表示的年份,被格式化為必要時帶前導零的兩位數,即 00 - 99 |
'Y' | 年份,被格式化為必要時帶前導零的四位數(至少),例如,0092 等於格里高里歷的 92 CE。 |
'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' | |
'c' | 日期和時間,被格式化為 "%ta %tb %td %tT %tZ %tY",例如 "Sun Jul 20 16:17:00 EDT 1969"。 |
任何未明確定義為轉換的字元都是非法字元,並且都被保留,以供將來擴展使用。
標誌
下表總結了受支持的標誌。y 表示該標誌受指示參數型別支持。
標誌 | 常規 | 字元 | 整數 | 浮點 | 日期/時間 | 說明 |
'-' | y | y | y | y | y | 結果將是左對齊的。 |
'#' | y1 | - | y3 | y | - | 結果應該使用依賴於轉換型別的替換形式 |
'+' | - | - | y4 | y | - | 結果總是包括一個符號 |
' ' | - | - | y4 | y | - | 對於正值,結果中將包括一個前導空格 |
'0' | - | - | y | y | - | 結果將用零來填充 |
',' | - | - | y2 | y5 | - | 結果將包括特定於語言環境的組分隔符 |
'(' | - | - | y4 | y5 | - | 結果將是用圓括號括起來的負數 |
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$" 參考,依此類別推。
根據位置參考參數的另一種方法是使用 '<' ('\u 003c ') 標誌,這將會重用以前格式說明符的參數。例如,以下兩條語句產生的字元相同:
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' | '\u0062' | |
'B' | '\u0042' | 'b' 的大寫形式。 |
'h' | '\u0068' | 產生一個表示物件的雜湊碼值的字元串。 如果參數 arg 為 null,則結果為 "null"。否則,結果為調用 Integer.toHexString(arg.hashCode()) 得到的結果。 |
'H' | '\u0048' | 'h' 的大寫形式。 |
's' | '\u0073' | 產生一個字元串。 |
'S' | '\u0053' | 's' 的大寫形式。 |
以下 標誌 應用於常規轉換:
'-' | '\u002d' | 將輸出左對齊。根據需要在轉換值結尾處添加空格 ('\u0020'),以滿足欄位的最小寬度要求。如果沒有提供寬度,則將拋出 MissingFormatWidthException。如果沒有給出此標誌,則輸出將是右對齊的。 |
'#' | '\u0023' | 要求輸出使用替換形式。此形式的定義通過轉換指定。 |
寬度 是將向輸出中寫入的最少字元數。如果轉換值的長度小於寬度,則用 ' ' (\u0020') 填充輸出,直到字元總數等於寬度為止。預設情況下,是在左邊進行填充。如果給出 '-' 標誌,則在右邊進行填充。如果沒有指定寬度,則沒有最小寬度。
精度是將向輸出中寫入的最多字元數。精度的應用要先於寬度,因此,即使寬度大於精度,輸出也將被截取為precision 字元。如果沒有指定精度,則對字元數沒有明確限制。
此轉換可應用於 char 和 Character。它還可應用於型別 byte、Byte、short 和 Short、 int 和 Integer。當Character.isValidCodePoint(int) 返回 true 時,此轉換也可應用於 int 和 Integer。如果返回 false,則將拋出IllegalFormatCodePointException。
'c' | '\u0063' | |
'C' | '\u0043' | 'c' 的大寫形式。 |
寬度是為了實作常規轉換而定義的。
精度不適用。如果指定精度,則將拋出 IllegalFormatPrecisionException。
數值轉換分為以下幾類別:
將根據以下演算法對數值型別進行格式化:
在獲得數字的整數部分、小數部分和指數(適用於資料型別)之後,將應用以下轉換:
- 將字元串中的每個數字字元 d 都替換為特定於語言環境的數字,該數字是相對於當前語言環境的零數字 z 來計算的;即 d - '0' + z。
- 如果存在小數點分隔符,則用特定於語言環境的小數點分隔符替換。
- 如果給出 ',' ('\u 002c ') flag 標誌,則插入特定於語言環境的組分隔符,這是通過從最低位到最高位瀏覽字元串的整數部分並不時插入該語言環境組大小定義的分隔符來實作的。
- 如果給出 '0' 標誌,則在符號字元(如果有的話)之後、第一個非零數字前插入特定於語言環境的零數字,直到字元串長度等於所要求的欄位寬度。
- 如果該值為負,並且給出了 '(' 標誌,那麼預先考慮 '(' ('\u0028'),並追加一個 ')' ('\u0029')。
- 如果該值為負(或者為浮點負零),並且沒有給出 '(' 標誌,那麼預先考慮 '-' ('\u002d')。
- 如果給出 '+' 標誌,並且該值為正或零(或者為浮點正零),那麼將預先考慮 '+' ('\u002b')。
如果該值為 NaN 或正無窮大,則分別輸出文本字元串 "NaN" 或 "Infinity"。如果該值為負無窮大,那麼輸出將是 "(Infinity)";否則如果給出 '(' 標誌,那麼輸出將是 "-Infinity"。這些值都沒有被本地化。
Byte、Short、Integer 和 Long
'd' | '\u0054' | 將參數格式化為十進制整數。應用本地化演算法。 如果給出 '0' 標誌,並且值為負,則在符號後填充零。 |
'o' | '\u 006f ' | 將參數格式化為以 8 為基數的整數。不應用本地化。 如果給出 '#' 標誌,則輸出將始終以基數指示符 '0' 開始。 如果給出 '0' 標誌,則使用前導零填充輸出,這些零被填充到以下任意指示符號後面的欄位寬度中。 |
'x' | '\u0078' | 將參數格式化為以 16 為基數的整數。不應用本地化。 如果給出 '#' 標誌,則輸出將始終以基數指示符 '0x' 開始。 如果給出 '0' 標誌,則使用前導零填充輸出,這些零被填充到基數指示符或符號(如果存在)後面的欄位寬度中。 |
'X' | '\u0058' |
如果該轉換是 'o'、'x' 或 'X' 轉換,並且給出了 '#' 和 '0' 標誌,那麼結果將包含基數指示符(對於八進制是 '0',對於十六進制是 '0' 或 "0x")、一定數量的零(基於寬度)和該值。
如果沒有給出 '-' 標誌,則在符號前填充空格。
以下 標誌 應用於數值整數轉換:
'+' | '\u002b' | 要求所有正數的輸出都包含一個正號。如果沒有給出此標誌,則只有負值包含符號。 |
' ' | '\u0020' | 對於非負值的輸出,要求包括單個額外空格 ('\u0020')。 |
'0' | '\u0030' | 要求將前導零填充到輸出中,這些零被填充到以下任意符號或基數指示符之後,以達到最小欄位寬度,轉換 NaN 或無窮大時除外。如果沒有提供寬度,則將拋出 MissingFormatWidthException。 |
',' | '\u 002c ' | |
'(' | '\u0028' | 要求輸出預先考慮 '(' ('\u0028'),並將 ')' ('\u0029') 追加到負值中。 |
如果沒有給出 標誌 ,則預設格式設置如下:
- width 中的輸出是右對齊的
- 負數以 '-' ('\u002d') 開始
- 正數和零不包括符號或額外的前導空格
- 不包括組分隔符
The 寬度 是將向輸出中寫入的最少字元數。這包括所有符號、數字、組分隔符、基數指示符和圓括號。如果轉換值的長度小於寬度,則用空格('\u0020') 填充輸出,直到字元總數等於寬度。預設情況下,在左邊進行填補。如果給出 '-' 標誌,則在右邊進行填補。如果沒有指定寬度,則沒有最小寬度。
精度不適用。如果指定精度,則將拋出 IllegalFormatPrecisionException。
以下轉換可應用於 BigInteger。
'd' | '\u0054' | 要求將輸出格式化為十進制整數。應用本地化演算法。 |
'o' | '\u 006f ' | 要求將輸出格式化為以 8 為基數的整數。不應用本地化。 如果 x 為負,那麼結果將是以 '-' ('\u002d') 開始的有符號值。允許對這種型別使用有符號輸出,因為它不同於基本型別,在沒有假定顯式資料型別大小的情況下,不可能創建無符號的等效值。 如果 x 為正數或零,且給出了 '+' 標誌,那麼結果是以 '+' ('\u002b') 開始的。 如果給出 '#' 標誌,那麼輸出將始終以 '0' 前綴開始。 如果給出 '0' 標誌,那麼將使用前導零填充輸出,這些零被填充到指示符後的欄位寬度中。 |
'x' | '\u0078' | 要求將輸出格式化為以 16 為基數的整數。不應用本地化。 如果 x 為負,那麼結果是以 '-' ('_apos;) 開始的有符號值。此型別允許使用有符號輸出,因為與基本型別不同,如果不假定明確的資料型別大小,則不可能創建無符號的等效數。 如果 x 為正數或零,且給出了 '+' 標誌,那麼結果以 '+' ('\u002b') 開始。 如果給出 '#' 標誌,那麼輸出將始終以基數指示符 '0x' 開始。 如果給出 '0' 標誌,那麼將使用前導零填充輸出,這些零被填充到基數指示符或符號(如果存在)後面的欄位寬度中。 |
'X' | '\u0058' |
如果該轉換是 'o'、'x' 或 'X',並且給出了 '#' 和 '0' 標誌,那麼結果將包含基數指示符(對於八進制是 '0',對於十六進制是 '0' 或 "0x")、一定數量的零(基於寬度)和該值。
如果給出 '0' 標誌,並且值為負,則在符號後填充零。
如果沒有給出 '-' 標誌,則在符號前填充空格。
寬度的規範與為 Byte、Short、Integer 和 Long 定義的規範相同。
精度不適用。如果指定精度,則將拋出 IllegalFormatPrecisionException。
Float 和 Double
'e' | '\u0065' | 數值 m 的格式取決它的值。 如果 m 是 NaN 或無窮大,則分別輸出文本字元串 "NaN" 或 "Infinity"。這些值都沒有被本地化。 如果 m 是正零或負零,則指數將是 "+00"。 讓 n 成為滿足 10n <= m < 10n+1 的唯一整數;讓 a 成為 m 和 10n 的精確算術商數值,且滿足 1 <= a < 10。然後將該數值解釋為 a 的整數部分,因為是一個小數位數,所以後面跟著小數點分隔符,再後面是表示 a 的小數部分的小數位數,後跟指數符號 'e' ('\u0065'),這之後是指數符號,後跟十進制整數形式表示的 n,它由方法Long.toString(long, int) 產生,並用零填充,使其至少包括兩個位數。 在結果中,m 或 a 的小數部分的位數等於精度。如果沒有指定精度,則預設值為 6。如果精度小於將出現在分別由 Float.toString(float) 或 Double.toString(double) 返回的字元串中的小數點之後的位數,則使用四捨五入演算法對該值進行捨入運算。否則,可能通過追加零來達到所需精度。要獲得該值的規範表示形式,請在適當時候使用 Float.toString(float) 或 Double.toString(double)。 |
'E' | '\u0045' | 'e' 的大寫形式。指數符號將是 'E' ('\u0045')。 |
'g' | '\u0067' | 在對精度進行捨入運算後,所得數值 m 的格式取決於它的值。 m 中的總有效位數等於其精度。如果沒有指定精度,則其預設值為 6。如果精度為 0,則該值將為 1。 |
'G' | '\u0047' | 'g' 的大寫形式。 |
'f' | '\u0066' | 如果 m 是 NaN 或無窮大,則將分別輸出文本字元串 "NaN" 或 "Infinity"。這些值都沒有被本地化。 將數值格式化為 m 的整數部分(不帶前導零),後跟小數點分隔符,再後面是表示 m 的小數部分的一個或多個十進制數字。 在結果中,m 或 a 的小數部分的位數等於精度。如果沒有指定精度,則預設值為 6。如果該精度小於將要出現在分別由 Float.toString(float) 或 Double.toString(double) 返回的字元串中的小數點之後的位數,則使用四捨五入演算法對該值進行捨入運算。否則,可能通過追加零來達到所需精度。要獲得該值的規範表示形式,請在適當時候使用 Float.toString(float) 或 Double.toString(double)。 |
'a' | '\u0061' | 要求將輸出格式化為十六進制指數形式。不應用本地化。 結果是表示參數 x 的符號和大小(絕對值)的字元串。 如果 x 為負值或負零值,那麼結果將以 '-' ('\u002d') 開始。 如果 x 為正值或正零值,且給出了 '+' 標誌,那麼結果將以 '+' ('\u002b') 開始。 數值 m 的格式取決它的值。
|
'A' | '\u0041' | 'a' 的大寫形式。表示數字的整個字元串將被轉換為大寫形式,其中包括 'x' ('\u0078') 和 'p' ('\u0070' 以及所有的十六進制數字 'a' - 'f' ('\u0061' - '\u0066')。 |
如果給出 '#' 標誌,則將始終存在小數點分隔符。
如果沒有給出 標誌 則預設格式設置如下:
- width 中的輸出是右對齊的。
- 負數以 '-' 開頭
- 正數和正零不包括符號或額外的前導空格
- 不包括組分隔符
- 小數點分隔符只在後面有數字時才出現
The 寬度 是將向輸出中寫入的最少字元數。這包括可應用的所有符號、數字、組分隔符、小數點分隔符、指數符號、基數指示符、圓括號和表示無窮大和 NaN 的字元串。如果轉換值的長度小於寬度,則用空格('\u0020') 填充輸出,直到字元總數等於寬度。預設情況下,在左邊進行填充。如果給出 '-' 標誌,則在右邊進行填充。如果沒有指定寬度,則沒有最小寬度。
如果轉換是 'g' 或 'G' 轉換,那麼精度就是捨入運算後所得數值的總有效位數。如果沒有指定精度,則預設值為 6。如果精度為 0,則該值將為 1。
BigDecimal
'e' | '\u0065' | 數值 m 的格式取決於它的值。 如果 m 為正零或負零,則指數將為 "+00"。 讓 n 成為滿足 10n <= m < 10n+1 的唯一整數;讓 a 成為 m 和 10n 的精確算術商數值,且滿足 1 <= a < 10。然後將該數值解釋為 a 的整數部分,因為是一個小數位數,所以後面跟著小數點分隔符,再後面是表示 a 的小數部分的小數位數,後跟指數符號 'e' ('\u0065'),這之後是指數符號,後跟十進制整數形式表示的 n,它由方法Long.toString(long, int) 產生,並用零填充,使其至少包括兩個位數。 在結果中,m 或 a 的小數部分的位數等於精度。如果沒有指定精度,則預設值為 6。如果精度小於將出現在分別由 Float.toString(float) 或 Double.toString(double) 返回的字元串中的小數點之後的位數,則使用四捨五入演算法對該值進行捨入運算。否則,可能通過追加零來達到所需精度。要獲得該值的規範表示形式,請使用 BigDecimal.toString()。 |
'E' | '\u0045' | 'e' 的大寫形式。指數符號將是 'E' ('\u0045')。 |
'g' | '\u0067' | 在對精度進行捨入運算後,所得數值 m 的格式取決於它的值。 m 中的總的有效位數等於精度。如果沒有指定精度,則預設值為 6。如果精度為 0,則該值將為 1。 |
'G' | '\u0047' | 'g' 的大寫形式。 |
'f' | '\u0066' | 將該數值格式化為 m 的整數部分(不帶前導零),後跟小數點分隔符,再後面是表示 m 的小數部分的一個或多個十進制數字。 在結果中,m 或 a 的小數部分的位數等於精度。如果沒有指定精度,則預設值為 6。如果精度小於將出現在分別由 Float.toString(float) 或 Double.toString(double) 返回的字元串中的小數點之後的位數,則使用四捨五入演算法對該值進行捨入運算。否則,可能通過追加零來達到所需精度。要獲得該值的規範表示形式,請使用 BigDecimal.toString()。 |
應用為 Byte、Short、Integer 和 Long 定義的所有標誌。
如果給出 '#' 標誌,則將始終存在小數點分隔符。
沒有給出標誌時的預設行為與 Float 和 Double 的行為相同。
't' | '\u0074' | 日期和時間轉換字元的前綴。 |
'T' | '\u0054' | 't' 的大寫形式。 |
以下日期和時間轉換字元後綴是為 't' 和 'T' 轉換定義的。這些型別類似於但不完全等同於 GNU date 和 POSIXstrftime( 3c ) 定義的那些型別。提供其他轉換型別是為了存取特定於 Java 的功能(例如,'L' 用於秒中的毫秒)。
以下轉換字元用來格式化時間:
'H' | '\u0048' | 24 小時制的小時,被格式化為必要時帶前導零的兩位數,即 00 - 23。00 對應午夜。 |
'I' | '\u0049' | 12 小時制的小時,被格式化為必要時帶前導零的兩位數,即 01 - 12。01 對應於 1 點鐘(上午或下午)。 |
'k' | '\u006b' | 24 小時制的小時,即 0 - 23。0 對應於午夜。 |
'l' | '\u 006c ' | 12 小時制的小時,即 1 - 12。1 對應於上午或下午的一點鐘。 |
'M' | '\u004d' | 小時中的分鐘,被格式化為必要時帶前導零的兩位數,即 00 - 59。 |
'S' | '\u0053' | 分鐘中的秒,被格式化為必要時帶前導零的兩位數,即 00 - 60("60" 是支持閏秒所需的一個特殊值)。 |
'L' | '\u 004c ' | 秒中的毫秒,被格式化為必要時帶前導零的三位數,即 000 - 999。 |
'N' | '\u004e' | 秒中的毫微秒,被格式化為必要時帶前導零的九位數,即 000000000 - 999999999。此值的精度受底層作業系統或硬體解析的限制。 |
'p' | '\u0070' | 特定於語言環境的上午或下午標記以小寫形式表示,例如 "am" 或 "pm"。使用轉換前綴 'T' 可以強行將此輸出轉換為大寫形式。(注意,'p' 產生的輸出是小寫的。而 GNU date 和 POSIX strftime( 3c ) 產生的輸出是大寫的。) |
'z' | '\u 007a ' | |
'Z' | '\u 005a ' | 表示時區的縮寫形式的字元串。 |
's' | '\u0073' | 自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的秒數,也就是 Long.MIN_VALUE/1000 與Long.MAX_VALUE/1000 之間的差值。 |
'Q' | '\u 004f ' | 自協調世界時 (UTC) 1970 年 1 月 1 日 00:00:00 至現在所經過的毫秒數,即 Long.MIN_VALUE 與Long.MAX_VALUE 之間的差值。此值的精度受底層作業系統或硬體解析的限制。 |
以下轉換字元用來格式化日期:
'B' | '\u0042' | |
'b' | '\u0062' | |
'h' | '\u0068' | 與 'b' 相同。 |
'A' | '\u0041' | |
'a' | '\u0061' | |
'C' | '\u0043' | 除以 100 的四位數表示的年份,被格式化為必要時帶前導零的兩位數,即 00 - 99 |
'Y' | '\u0059' | 年份,被格式化為必要時帶前導零的四位數(至少),例如 0092 等於格里高里歷的 92 CE。 |
'y' | '\u0079' | 年份的最後兩位數,被格式化為必要時帶前導零的兩位數,即 00 - 99。 |
'j' | '\u 006a ' | 一年中的天數,被格式化為必要時帶前導零的三位數,例如,對於格里高里歷是 001 - 366。001 對應於一年中的第一天。 |
'm' | '\u006d' | 月份,被格式化為必要時帶前導零的兩位數,即 01 - 13,其中 "01" 是一年的第一個月,("13" 是支持陰曆所需的一個特殊值)。 |
'd' | '\u0064' | 一個月中的天數,被格式化為必要時帶前導零的兩位數,即 01 - 31,其中 "01" 是一個月的第一天。 |
'e' | '\u0065' | 一個月中的天數,被格式化為兩位數,即 1 - 31,其中 "1" 是一個月中的第一天。 |
以下轉換字元用於格式化常見的日期/時間組合。
'R' | '\u0052' | 24 小時制的時間,被格式化為 "%tH:%tM" |
'T' | '\u0054' | 24 小時制的時間,被格式化為 "%tH:%tM:%tS"。 |
'r' | '\u0072' | 12 小時制的時間,被格式化為 "%tI:%tM:%tS %Tp"。上午或下午標記 ('%Tp') 的位置可能與地區有關。 |
'D' | '\u0044' | 日期,被格式化為 "%tm/%td/%ty"。 |
'F' | '\u0046' | |
'c' | '\u0063' | 日期和時間,被格式化為 "%ta %tb %td %tT %tZ %tY",例如 "Sun Jul 20 16:17:00 EDT 1969"。 |
寬度 是將向輸出中寫入的最少字元數。如果轉換值的長度小於 width,則用空格('\u0020') 來填充輸出,直到總字元數等於寬度。預設情況下,在左邊進行填充。如果給出 '-' 標誌,則在右邊進行填充。如果沒有指定寬度,則沒有最小寬度。
該轉換不對應於任何參數。
'%' | 結果是一個文字值 '%' ('\u0025') 寬度 是將向輸出中寫入的最少字元數,包括 '%'。如果轉換值的長度小於 width,則用空格 ('\u0020') 來填充輸出,直到總字元數等於寬度。在左邊進行填充。如果沒有指定寬度,則只輸出 '%'。 精度不適用。如果指定精度,則將拋出 IllegalFormatPrecisionException。 |
該轉換不對應於任何參數。
'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"
- 相對索引 是在格式說明符中包含 '<' ('\u 003c ') 標誌時使用,該標誌將導致重用以前格式說明符的參數。如果不存在以前的參數,則拋出 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。
如果參數多於格式說明符,則忽略額外的參數。
全站熱搜
留言列表