详细信息
这一部分将提供格式化行为规范方面的细节,其中包括条件和异常、受支持的数据类型、本地化以及标志、转换和数据类型之间的交互。有关格式化概念的概述,请参阅摘要。
任何未明确定义为转换、日期/时间转换前缀或标志的字符都是非法字符,并且这些字符都被保留,以供未来扩展使用。在格式字符串中使用这样的字符会导致抛出 unknownformatconversionexception
或 unknownformatflagsexception
。
如果格式说明符包含带有无效值或不受支持的其他值的
iis7站长之家或精度,则将分别抛出 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()
常规
以下常规转换可应用于任何参数类型:
以下 标志 应用于常规转换:
宽度 是将向输出中写入的最少字符数。如果转换值的长度小于宽度,则用 ' ' (u0020') 填充输出,直到字符总数等于宽度为止。默认情况下,是在左边进行填充。如果给出 '-' 标志,则在右边进行填充。如果没有指定宽度,则没有最小宽度。
精度是将向输出中写入的最多字符数。精度的应用要先于宽度,因此,即使宽度大于精度,输出也将被截取为 precision 字符。如果没有指定精度,则对字符数没有明确限制。
字符
此转换可应用于
char 和
character
。它还可应用于类型
byte、
byte
、
short 和
short
、
int 和
integer
。当
character.isvalidcodepoint(int)
返回
true 时,此转换也可应用于
int 和
integer
。如果返回
false,则将抛出
illegalformatcodepointexception
。
'-' 标志是为应用常规转换而定义的。如果给出 '#' 标志,则将抛出 formatflagsconversionmismatchexception
。
宽度是为了实现常规转换而定义的。
精度不适用。如果指定精度,则将抛出 illegalformatprecisionexception
。
数值
数值转换分为以下几类:
- byte、short、integer 和 long
- biginteger
- float 和 double
- bigdecimal
将根据以下算法对数值类型进行格式化:
数字本地化算法
在获得数字的整数部分、小数部分和指数(适用于数据类型)之后,将应用以下转换:
- 将字符串中的每个数字字符 d 都替换为特定于语言环境的数字,该数字是相对于当前语言环境的零数字 z 来计算的;即 d - '0' + z。
- 如果存在小数点分隔符,则用特定于语言环境的小数点分隔符替换。
- 如果给出 ',' ('u002c') flag 标志,则插入特定于语言环境的组分隔符,这是通过从最低位到最高位浏览字符串的整数部分并不时插入该语言环境组大小定义的分隔符来实现的。
- 如果给出 '0' 标志,则在符号字符(如果有的话)之后、第一个非零数字前插入特定于语言环境的零数字,直到字符串长度等于所要求的字段宽度。
- 如果该值为负,并且给出了 '(' 标志,那么预先考虑 '(' ('u0028'),并追加一个 ')' ('u0029')。
- 如果该值为负(或者为浮点负零),并且没有给出 '(' 标志,那么预先考虑 '-' ('u002d')。
- 如果给出 '+' 标志,并且该值为正或零(或者为浮点正零),那么将预先考虑 '+' ('u002b')。
如果该值为 nan 或正无穷大,则分别输出文本字符串 "nan" 或 "infinity"。如果该值为负无穷大,那么输出将是 "(infinity)";否则如果给出 '(' 标志,那么输出将是 "-infinity"。这些值都没有被本地化。
byte、short、integer 和 long
以下转换可应用于 byte、byte
、short、short
、int、integer
、long 和 long
。
如果该转换是 'o'、'x' 或 'x' 转换,并且给出了 '#' 和 '0' 标志,那么结果将包含基数指示符(对于八进制是 '0',对于十六进制是 '0' 或 "0x")、一定数量的零(基于宽度)和该值。
如果没有给出 '-' 标志,则在符号前填充空格。
以下 标志 应用于数值整数转换:
如果没有给出 标志 ,则默认格式设置如下:
- width 中的输出是右对齐的
- 负数以 '-' ('u002d') 开始
- 正数和零不包括符号或额外的前导空格
- 不包括组分隔符
the 宽度 是将向输出中写入的最少字符数。这包括所有符号、数字、组分隔符、基数指示符和圆括号。如果转换值的长度小于宽度,则用空格('u0020') 填充输出,直到字符总数等于宽度。默认情况下,在左边进行填补。如果给出 '-' 标志,则在右边进行填补。如果没有指定宽度,则没有最小宽度。
精度不适用。如果指定精度,则将抛出 illegalformatprecisionexception
。
biginteger
以下转换可应用于 biginteger
。
如果该转换是 'o'、'x' 或 'x',并且给出了 '#' 和 '0' 标志,那么结果将包含基数指示符(对于八进制是 '0',对于十六进制是 '0' 或 "0x")、一定数量的零(基于宽度)和该值。
如果给出 '0' 标志,并且值为负,则在符号后填充零。
如果没有给出 '-' 标志,则在符号前填充空格。
应用为 byte、short、integer 和 long 定义的所有标志。没有给出标志时的默认行为与 byte、short、integer 和 long 的行为相同。
宽度的规范与为 byte、short、integer 和 long 定义的规范相同。
精度不适用。如果指定精度,则将抛出 illegalformatprecisionexception
。
float 和 double
以下转换可应用于 float、float
、double 和 double
。
应用为 byte、short、integer 和 long 定义的所有标志。
如果给出 '#' 标志,则将始终存在小数点分隔符。
如果没有给出 标志 则默认格式设置如下:
- width 中的输出是右对齐的。
- 负数以 '-' 开头
- 正数和正零不包括符号或额外的前导空格
- 不包括组分隔符
- 小数点分隔符只在后面有数字时才出现
the 宽度 是将向输出中写入的最少字符数。这包括可应用的所有符号、数字、组分隔符、小数点分隔符、指数符号、基数指示符、圆括号和表示无穷大和 nan 的字符串。如果转换值的长度小于宽度,则用空格('u0020') 填充输出,直到字符总数等于宽度。默认情况下,在左边进行填充。如果给出 '-' 标志,则在右边进行填充。如果没有指定宽度,则没有最小宽度。
如果 转换 是 'e'、'e' 或 'f',则精度是小数点分隔符后的位数。如果没有指定精度,则假定精度为 6。
如果转换是 'g' 或 'g' 转换,那么精度就是舍入运算后所得数值的总有效位数。如果没有指定精度,则默认值为 6。如果精度为 0,则该值将为 1。
如果转换是 'a' 或 'a' 转换,则精度是小数点分隔符后十六进制数字的位数。如果没有提供精度,则将输出 double.tohexstring(double)
返回的所有数字。
bigdecimal
以下转换可应用于 bigdecimal
。
应用为 byte、short、integer 和 long 定义的所有标志。
如果给出 '#' 标志,则将始终存在小数点分隔符。
没有给出标志时的默认行为与 float 和 double 的行为相同。
宽度和精度的规范与为 float 和 double 定义的规范相同。
日期/时间
此转换可应用于 long、long
、calendar
和 date
。
以下日期和时间转换字符后缀是为 't' 和 't' 转换定义的。这些类型类似于但不完全等同于 gnu date 和 posix strftime(3c) 定义的那些类型。提供其他转换类型是为了访问特定于 java 的功能(例如,'l' 用于秒中的毫秒)。
以下转换字符用来格式化时间:
以下转换字符用来格式化日期:
以下转换字符用于格式化常见的日期/时间组合。
应用为常规转换而定义的 '-' 标志。如果给出 '#' 标志,则将抛出 formatflagsconversionmismatchexception
。
宽度 是将向输出中写入的最少字符数。如果转换值的长度小于 width,则用空格('u0020') 来填充输出,直到总字符数等于宽度。默认情况下,在左边进行填充。如果给出 '-' 标志,则在右边进行填充。如果没有指定宽度,则没有最小宽度。
精度不适用。如果指定了精度,则将抛出 illegalformatprecisionexception
。
百分比
该转换不对应于任何参数。
行分隔符
该转换不对应于任何参数。
标志、宽度和精度都不可用。如果提供这三者,则会分别抛出 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"
- 相对索引 是在格式说明符中包含 '<' ('u003c') 标志时使用,该标志将导致重用以前格式说明符的参数。如果不存在以前的参数,则抛出
missingformatargumentexception
。
formatter.format("%s %s % "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 % "b a a b"
// "c" and "d" are ignored because they are not referenced
参数的最大数量受到 java machine specification 定义的 java 数组 的最大维数的限制。如果参数索引与可用参数不对应,则抛出 missingformatargumentexception
。
如果参数多于格式说明符,则忽略额外的参数。
除非另行指定,否则向此类中的任何方法或构造方法传递 null 参数都将抛出 nullpointerexception
。
- 从以下版本开始:
- 1.5