以下内容从 oracle JDK8 java.util.Formatter 类上翻译
打印格式字符串的解释器。
该类提供了对布局调整和对齐数字、字符串和日期/时间数据的通用格式以及特定于语言环境的输出的支持。
支持常用 Java 类型 {@code byte}, {@link java.math.BigDecimal BigDecimal} 和 {@link Calendar} 。
可以通过 {@link Formattable} 接口为任意用户类型提供有限的格式定制。
对于多线程访问，格式化程序不一定是安全的。线程安全是可选的，是该类中方法用户的责任。
Java 语言的格式化打印很大程度上受到 C 的 {@code printf} 的启发。
虽然格式字符串类似于C语言，但为了适应Java语言并利用其一些特性，已经进行了一些定制。而且，Java的格式化比C更严格。
例如，如果转换与标志不兼容，则会引发异常。在C语言中，不适用的标志被静默地忽略。因此，格式字符串可以被C程序员识别，但不一定与C中的格式字符串完全兼容。
预期用法示例：
StringBuilder sb = new StringBuilder();
// 将所有输出发送到Appendable对象sb
Formatter formatter = new Formatter(sb, Locale.US);
// 显式参数索引可用于重新排序输出。
formatter.format("%4$2s %3$2s %2$2s %1$2s", "a", "b", "c", "d")
// -> " d c b a"
// 可选的locale作为第一个参数，可用于获取特定于地区的数字格式。可以指定精度和宽度来舍入和对齐值。
formatter.format(Locale.FRANCE, "e = %+10.4f", Math.E);
// -> "e = +2,7183"
// '(' 数字标志可用于用括号而不是减号格式化负数。自动插入组分隔符。
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 语言的 {@code sprintf(3)} 一样，字符串可以使用静态方法 {@link String#format(String,Object...) String.format}:
// 格式化包含日期的字符串。
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"
组织结构
本规范分为两部分。
第一部分 概述 介绍了基本的格式化概念。 本节适用于希望快速入门并熟悉其他编程语言格式化打印的用户。
第二部分 详情 涵盖了具体的实现细节。它适用于希望更精确地规范格式化行为的用户。
概述
本节旨在提供格式化概念的简要概述。有关精确的行为细节，请参阅 详情 部分。
格式化字符串语法
每个产生格式化输出的方法都需要一个 格式字符串 和一个 参数列表 。格式字符串是一个 {@link String} ，它可以包含固定文本和一个或多个嵌入的 格式说明符。
请看下面的例子：
Calendar c = ...;
String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
格式字符串是 {@code format} 方法的第一个参数。它包含三个格式说明符 “{@code %1$tm}”, “{@code %1$te}”, 和 “{@code %1$tY}”，它们表示参数应该如何处理以及应该在文本中的什么位置插入。格式字符串的其余部分是固定文本，包括 {@code "Dukes Birthday: "} 和任何其他空格或标点符号。
参数列表由在格式字符串之后传递给方法的所有参数组成。在上面的例子中，参数列表的大小为1，由 {@link java.util.Calendar Calendar} 对象 {@code c} 组成。
- 通用类型、字符类型和数字类型的格式说明符语法如下：
%[argument_index$][flags][width][.precision]conversion %[参数索引$][标志][宽度][.精度]转换
可选参数 argument_index 是一个十进制整数，表示参数在参数列表中的位置。第一个参数由 "{@code 1$}" 引用，第二个参数由 "{@code 2$}" 引用，以此类推。
可选参数 flags 是一组修改输出格式的字符。有效标志的集合取决于转换。
可选参数 width 是一个十进制正整数，表示要写入输出的最小字符数。
可选参数 precision 是一个非负十进制整数，通常用于限制字符的数量。具体的行为取决于转换。
必需参数 conversion 是一个字符，指示参数应该如何格式化。给定参数的有效转换集取决于参数的数据类型。
- 用于表示日期和时间的类型的格式说明符语法如下：
%[argument_index$][flags][width]conversion %[参数索引$][标志][宽度]转换
可选参数 argument_index, flags 和 width 的定义如上所述。
必需参数 conversion 是一个两个字符的序列。第一个字符是 {@code 't'} 或 {@code 'T'}。第二个字符表示要使用的格式。这些字符类似于 GNU {@code date} 和 POSIX {@code strftime(3c)} 定义的字符，但不完全相同。
- 与参数不对应的格式说明符语法如下：
%[flags][width]conversion %[标志][宽度]转换
可选参数 flags 和 width 的定义如上所述。
必需参数 conversion 是一个字符，表示要在输出中插入的内容。
转换
转换分为以下几类：
- 通用 - 可用于任何参数类型
- 字符 - 可用于表示 Unicode 字符的基本类型： {@code char}, {@link Character}, {@code byte}, {@link Byte}, {@code short}, 和 {@link Short}。当 {@link Character#isValidCodePoint} 返回 {@code true} 时，此转换也可以应用于类型 {@code int} 和 {@link Integer} 。
- 数值
- 整型 - 可用于 Java 整型：{@code byte}, {@link Byte}, {@code short}, {@link Short}, {@code int} 和 {@link Integer}, {@code long}, {@link Long}, 和 {@link java.math.BigInteger BigInteger} (但不包括 {@code char} 或 {@link Character})
- 浮点型 - 可用于 Java 浮点类型：{@code float}, {@link Float}, {@code double}, {@link Double} 和 {@link java.math.BigDecimal BigDecimal}
- 日期/时间 - 可用于能够编码日期或时间的 Java 类型：{@code long}, {@link Long}, {@link Calendar}, {@link Date} 和 {@link TemporalAccessor TemporalAccessor}
- 百分比 - 生成字面量 {@code '%'} ('\u0025')
- 行分隔符 - 生成特定于平台的行分隔符
下表总结了受支持的转换。由大写字符表示的转换 (即 {@code 'B'}, {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'}, {@code 'A'} 和 {@code 'T'}) 与对应的小写转换字符相同，只是根据流行的 {@link java.util.Locale Locale} 的规则将结果转换为大写。结果相当于下面调用 {@link String#toUpperCase()}
out.toUpperCase()
| 转换 | 参数分类 | 描述 |
|---|---|---|
| {@code 'b'}, {@code 'B'} | 通用 | 如果参数 arg 为 {@code null} 则结果是 "{@code false}"。如果 arg 为 {@code boolean} 或 {@link Boolean} 则结果是由 {@link String#valueOf(boolean) String.valueOf(arg)} 返回的字符串。否则，结果为 "true"。 |
| {@code 'h'}, {@code 'H'} | 通用 | 如果参数 arg 为 {@code null} 则结果是 "{@code null}"。否则，通过调用 {@code Integer.toHexString(arg.hashCode())} 获得结果。 |
| {@code 's'}, {@code 'S'} | 通用 | 如果参数 arg 为 {@code null} 则结果是 "{@code null}"。 如果 arg 实现了 {@link Formattable} ，则调用 {@link Formattable#formatTo arg.formatTo} 。否则，通过调用 {@code arg.toString()} 获得结果。 |
| {@code 'c'}, {@code 'C'} | 字符 | 结果是一个 Unicode 字符 |
| {@code 'd'} | 整型 | 结果被格式化为十进制整数 |
| {@code 'o'} | 整型 | 结果被格式化为八进制整数 |
| {@code 'x'}, {@code 'X'} | 整型 | 结果被格式化为十六进制整数 |
| {@code 'e'}, {@code 'E'} | 浮点型 | 结果被格式化为计算机科学记数法中的十进制数字 |
| {@code 'f'} | 浮点型 | 结果被格式化为十进制数 |
| {@code 'g'}, {@code 'G'} | 浮点型 | 根据精度和四舍五入后的值，结果使用计算机科学记数法或十进制格式进行格式化。 |
| {@code 'a'}, {@code 'A'} | 浮点型 | 结果被格式化为一个带有效位和指数的十六进制浮点数。{@code BigDecimal} 类型不支持这种转换，尽管后者属于浮点型。 |
| {@code 't'}, {@code 'T'} | 日期/时间 | 日期和时间转换字符的前缀。请参阅 日期/时间转换。 |
| {@code '%'} | 百分比 | 结果是字面量 {@code '%'} ('\u0025') |
| {@code 'n'} | 行分隔符 | 结果是特定于平台的行分隔符 |
任何没有明确定义为转换的字符都是非法的，保留给将来的扩展使用。
日期/时间转换
下面的日期和时间转换后缀字符被定义为 {@code 't'} 和 {@code 'T'} 转换。这些类型类似于 GNU {@code date} 和 POSIX {@code strftime(3c)} 定义的类型，但不完全相同。还提供了其他的转换类型来访问特定于 java 的功能 (例如 {@code 'L'} 表示毫秒数)。
以下是用于格式化时间的转换字符：
| {@code 'H'} | 24小时制时钟的一天中的小时，格式为两位数字，必要时带前导零，即 {@code 00 - 23}。 |
| {@code 'I'} | 12小时制时钟的小时，格式为两位数字，必要时带前导零，即 {@code 01 - 12}。 |
| {@code 'k'} | 24小时制的一天中的小时，即 {@code 0 - 23}。 |
| {@code 'l'} | 12小时制的小时，即 {@code 1 - 12}。 |
| {@code 'M'} | 小时内的分钟，格式为两位数字，必要时带前导零，即 {@code 00 - 59}。 |
| {@code 'S'} | 分钟内的秒数，格式为两位数字，必要时带前导零，即 {@code 00 - 60} ("{@code 60}" 是支持闰秒所需的特殊值)。 |
| {@code 'L'} | 秒内的毫秒数，格式为三位数字，必要时带前导零，即 {@code 000 - 999}。 |
| {@code 'N'} | 秒内的纳秒，格式为9位数字，必要时带前导零，即 {@code 000000000 - 999999999}。 |
| {@code 'p'} | 特定于语言环境的 {@linkplain java.text.DateFormatSymbols#getAmPmStrings 上午或下午} 标记，小写，例如 "{@code am}" 或 "{@code pm}"。使用转换前缀 {@code 'T'} 强制此输出为大写。 |
| {@code 'z'} | RFC 822 风格数字的 GMT 时区偏移，例如 {@code -0800}。此值将根据夏令时的需要进行调整。对于 {@code long}, {@link Long} 和 {@link Date} ，使用的时区是此Java虚拟机实例的 {@linkplain TimeZone#getDefault() 默认时区} 。 |
| {@code 'Z'} | 表示时区缩写的字符串。此值将根据夏令时的需要进行调整。对于 {@code long}, {@link Long} 和 {@link Date} ，使用的时区是此Java虚拟机实例的 {@linkplain TimeZone#getDefault() 默认时区}。Formatter 的区域设置将取代参数的区域设置(如果有的话)。 |
| {@code 's'} | 自1970年1月1日开始的纪元开始的秒数 {@code 00:00:00} UTC，即 {@code Long.MIN_VALUE/1000} 到 {@code Long.MAX_VALUE/1000}。 |
| {@code 'Q'} | 自1970年1月1日开始的纪元开始的毫秒 {@code 00:00:00} UTC, 即 {@code Long.MIN_VALUE} 到 {@code Long.MAX_VALUE}。 |
以下是用于格式化日期的转换字符：
| {@code 'B'} | 特定于语言环境的 {@linkplain java.text.DateFormatSymbols#getMonths 完整月份名称}，例如 {@code "January"}, {@code "February"}。 |
| {@code 'b'} | 特定于语言环境的 {@linkplain java.text.DateFormatSymbols#getShortMonths 缩写月份名称}，例如 {@code "Jan"}, {@code "Feb"}。 |
| {@code 'h'} | 与 {@code 'b'}相同。 |
| {@code 'A'} | 特定于语言环境的全名 {@linkplain java.text.DateFormatSymbols#getWeekdays 星期几}，例如 {@code "Sunday"}, {@code "Monday"}。 |
| {@code 'a'} | 特定于语言环境的短名 {@linkplain java.text.DateFormatSymbols#getShortWeekdays 星期几}，例如 {@code "Sun"}, {@code "Mon"}。 |
| {@code 'C'} | 四位数年份除以 {@code 100}，格式为两位数字，必要时带前导零，即 {@code 00 - 99}。 |
| {@code 'Y'} | 年份，格式至少为四位数字，必要时带前导零，例如，对于公历 {@code 0092} 等于 {@code 92} CE 。 |
| {@code 'y'} | 年份的最后两位数字，必要时用前导零格式化，即 {@code 00 - 99}。 |
| {@code 'j'} | 年份的第几天，格式为三位数字，必要时带前导零，例如公历的 {@code 001 - 366}。 |
| {@code 'm'} | 月份，格式为两位数字，必要时带前导零，即 {@code 01 - 13}。 |
| {@code 'd'} | 月份的第几天，格式为两位数字，必要时带前导零，即 {@code 01 - 31}。 |
| {@code 'e'} | 月份的第几天，格式为两位数字，即 {@code 1 - 31}。 |
以下是用于格式化日期/时间组合的转换字符：
| {@code 'R'} | 24小时制的时间格式为 {@code "%tH:%tM"} |
| {@code 'T'} | 24小时制的时间格式为 {@code "%tH:%tM:%tS"}. |
| {@code 'r'} | 12小时制的时间格式为 {@code "%tI:%tM:%tS %Tp"}。上午或下午标记 ({@code '%Tp'}) 的位置可能与语言环境有关。 |
| {@code 'D'} | 日期格式为 {@code "%tm/%td/%ty"}. |
| {@code 'F'} | ISO 8601 完整日期格式为 {@code "%tY-%tm-%td"}。 |
| {@code 'c'} | 日期和时间格式为 {@code "%ta %tb %td %tT %tZ %tY"}，例如 {@code "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 | - | 结果将包括特定于语言环境的 {@linkplain java.text.DecimalFormatSymbols#getGroupingSeparator 组分隔符} |
| '(' | - | - | y4 | y5 | - | 结果将把负数括在括号中 |
1 依赖于 {@link Formattable} 的定义。
2 仅用于 {@code 'd'} 转换。
3 仅用于 {@code 'o'}, {@code 'x'} 和 {@code 'X'} 转换。
4 对于 {@code 'd'}, {@code 'o'}, {@code 'x'} 和 {@code 'X'} 转换应用于 {@link java.math.BigInteger BigInteger} 或 {@code 'd'} 应用于 {@code byte}, {@link Byte}, {@code short}, {@link Short}, {@code int} 和 {@link Integer}, {@code long} 和 {@link Long}。
5 仅用于 {@code 'e'}, {@code 'E'}, {@code 'f'}, {@code 'g'} 和 {@code 'G'} 转换。
任何未显式定义为标志的字符都是非法的，并保留给将来的扩展使用。
宽度
宽度是要写入输出的最小字符数。对于行分隔符转换，宽度不适用；如果提供了，则会抛出异常。
精度
对于一般参数类型，精度是要写入输出的最大字符数。
对于浮点转换 {@code 'a'}, {@code 'A'}, {@code 'e'}, {@code 'E'} 和 {@code 'f'} ，精度是基数点后的位数。如果转换为 {@code 'g'} 或 {@code 'G'}，则精度为四舍五入后得到的数量级的总位数。
对于字符、整数和日期/时间参数类型以及百分比和行分隔符转换，精度不适用;如果提供了精度，则会抛出异常。
参数索引
参数索引是一个十进制整数，表示参数在参数列表中的位置。第一个参数由 "{@code 1$}" 引用，第二个参数由 "{@code 2$}" 引用，以此类推。
按位置引用参数的另一种方法是使用 {@code '<'} ('\u003c') 标志，这会导致重用前一个格式说明符的参数。例如，下面两个语句将产生相同的字符串：
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);
详情
本节旨在提供格式化的行为细节，包括条件和异常、支持的数据类型、本地化以及标志、转换和数据类型之间的交互。有关格式化概念的概述，请参阅 概述
任何未显式定义为转换、日期/时间转换后缀或标志的字符都是非法的，并保留给未来的扩展使用。在格式字符串中使用这样的字符将导致抛出 {@link UnknownFormatConversionException} 或 {@link UnknownFormatFlagsException} 。
如果格式说明符包含的宽度或精度值无效或不受支持，则将分别抛出 {@link IllegalFormatWidthException} 或 {@link IllegalFormatPrecisionException} 。
如果格式说明符包含不适用于相应参数的转换字符，则会抛出 {@link IllegalFormatConversionException} 。
所有指定的异常都可以由 {@code Formatter} 的任何 {@code format} 方法抛出，也可以由任何 {@code format} 便利方法抛出，例如 {@link String#format(String,Object...) String.format} 和 {@link java.io.PrintStream#printf(String,Object...) PrintStream.printf}。
由大写字符表示的转换 (即 {@code 'B'}, {@code 'H'}, {@code 'S'}, {@code 'C'}, {@code 'X'}, {@code 'E'}, {@code 'G'}, {@code 'A'} 和 {@code 'T'}) 与对应的小写转换字符相同，只是根据流行的 {@link java.util.Locale Locale} 的规则将结果转换为大写。结果相当于以下对 {@link String#toUpperCase()} 的调用
out.toUpperCase()
通用
以下通用转换可应用于任何实参类型：
| {@code 'b'} | '\u0062' | 生成由 {@link Boolean#toString(boolean)} 返回的 "{@code true}" 或 "{@code false}" 。 如果参数为 {@code null} ，则结果为 "{@code false}"。如果参数是 {@code boolean} 或 {@link Boolean}，则结果是由 {@link String#valueOf(boolean) String.valueOf()} 返回的字符串。否则，结果为 "{@code true}"。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'B'} | '\u0042' | {@code 'b'} 的大写变体。 |
| {@code 'h'} | '\u0068' | 生成表示对象哈希码值的字符串。 如果参数 arg 为 {@code null} ，则结果为 "{@code null}"。否则，通过调用 {@code Integer.toHexString(arg.hashCode())} 获得结果。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'H'} | '\u0048' | {@code 'h'} 的大写变体。 |
| {@code 's'} | '\u0073' | 生成一个字符串。 如果参数为 {@code null} ，则结果为 "{@code null}"。如果参数实现了 {@link Formattable}，则调用它的 {@link Formattable#formatTo formatTo}方法。否则，通过调用参数的 {@code toString()} 方法获得结果。 如果给出了 {@code '#'} 标志，而参数不是 {@link Formattable} ，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'S'} | '\u0053' | {@code 's'} 的大写变体。 |
以下标志 适用于通用转换:
| {@code '-'} | '\u002d' | 左对齐输出。空格 ('\u0020') 将根据需要在转换值的末尾添加，以填充字段的最小宽度。如果没有提供宽度，则会抛出 {@link MissingFormatWidthException} 。如果没有给出这个标志，那么输出将被右对齐。 |
| {@code '#'} | '\u0023' | 需要使用另一种形式的输出。表单的定义由转换指定。 |
宽度 是要写入输出的最小字符数。如果转换值的长度小于宽度，则输出将被 ' ' ('\u0020') 填充，直到字符总数等于宽度。默认情况下，填充在左侧。如果给出 {@code '-'} 标志，则填充将在右侧。如果没有指定宽度，则没有最小值。
精度是要写入输出的最大字符数。精度在宽度之前应用，因此即使宽度大于精度，输出也将被截断为 {@code precision} 字符。如果未指定精度，则对字符数没有显式限制。
字符
这种转换可以应用于 {@code char} 和 {@link Character} 。当 {@link Character#isValidCodePoint} 返回 {@code true} 时，它也可以应用于类型 {@code byte}, {@link Byte}, {@code short} 和 {@link Short}, {@code int} 和 {@link Integer} 。如果它返回 {@code false} ，那么将抛出 {@link IllegalFormatCodePointException} 。| {@code 'c'} | '\u0063' | 如 Unicode 字符表示方式 所述，将参数格式化为 Unicode 字符。如果参数表示一个补充字符，则可能不止一个 16-bit {@code char} 。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'C'} | '\u0043' | {@code 'c'} 的大写变体。 |
应用为 通用转换 定义的 {@code '-'} 标志。如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。
宽度定义为 通用转换.
精度不适用。如果指定了精度，则会抛出 {@link IllegalFormatPrecisionException} 。
数值
数值转换分为以下几类：
数值类型将按照以下算法格式化：
数字定位算法
在获得整数部分、小数部分和指数 (根据数据类型而定) 的数字后，应用以下转换：
- 字符串中的每个数字字符 d 都被替换为一个特定于区域设置的数字，这个数字是相对于当前区域设置计算得到的 {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() 零数字} z; 即 d - {@code '0'} + z 。
- 如果存在十进制分隔符，则使用特定于区域设置的 {@linkplain java.text.DecimalFormatSymbols#getDecimalSeparator 十进制分隔符} 。
- 如果给出了 {@code ','} ('\u002c') 标志 ，则通过扫描字符串的整数部分从最低有效位数到最高有效位数并按区域设置的 {@linkplain java.text.DecimalFormatSymbols#getGroupingSeparator 分组分隔符} 定义的间隔插入分隔符，插入特定于区域设置的 {@code ','} 标记。
- 如果给出了 {@code '0'} 标志，则特定于本地语言环境的 {@linkplain java.text.DecimalFormatSymbols#getZeroDigit() 零数字} 会被插入到符号字符之后(如果有的话)，并且在第一个非零数字之前，直到字符串的长度等于请求的字段宽度。
- 如果值为负数并且给出了 {@code '('} 标志，则会添加 {@code '('} ('\u0028') 前缀并添加 {@code ')'} ('\u0029') 后缀。
- 如果值为负数(或浮点负零)并且没有给出 {@code '('} 标志，则在前面加上 {@code '-'} ('\u002d') 。
- 如果给出了 {@code '+'} 标志并且值为正或零(或浮点正零)，则将在前面加上 {@code '+'} ('\u002b') 。
如果值为NaN或正无穷大，将分别输出字面值字符串 "NaN" 或 "Infinity" 如果值为负无穷大，那么如果给出 {@code '('} 标志，则输出将是 "(Infinity)" ，否则输出将是 "-Infinity" 。这些值没有本地化。
Byte, Short, Integer 和 Long
以下转换可以应用于 {@code byte}, {@link Byte}, {@code short}, {@link Short}, {@code int} 和 {@link Integer}, {@code long} 和 {@link Long} 。
| {@code 'd'} | '\u0064' | 将参数格式化为十进制整数。应用了定位算法。 如果给出了 {@code '0'} 标志并且值为负，则零填充将出现在符号之后。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'o'} | '\u006f' | 将参数格式化为八进制的整数。没有应用本地化。 如果 x 为负值，则结果将是一个无符号值，该值是通过将 2n 加到 {@code n} 的值中生成的，其中 {@code n} 是静态 {@code SIZE} 字段在 {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, {@linkplain Integer#SIZE Integer} 或 {@linkplain Long#SIZE Long} 类中返回的类型的 bit 位数。 如果给出了 {@code '#'} 标志，则输出将始终以基数指示符 {@code '0'} 开始。 如果给出了 {@code '0'} 标志，则输出将在任何符号指示之后用前导零填充字段宽度。 如果给出了 {@code '('}, {@code '+'}, ' ' 或 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'x'} | '\u0078' | 将参数格式化为十六进制的整数。没有应用本地化。 如果 x 为负值，则结果将是一个无符号值，该值是通过将 2n 加到 {@code n} 的值中生成的，其中 {@code n} 是静态 {@code SIZE} 字段在 {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, {@linkplain Integer#SIZE Integer} 或 {@linkplain Long#SIZE Long} 类中返回的类型的 bit 位数。 如果给出了 {@code '#'} 标志，则输出将始终以基数指示符 {@code "0x"} 开始。 如果给出了 {@code '0'} 标志，那么输出将被填充为 基数指示符或符号(如果存在)后带前导零的字段宽度。 如果给出了 {@code '('}, ' ', {@code '+'} 或 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'X'} | '\u0058' | {@code 'x'} 的大写变体。表示数字的整个字符串将被转换为 {@linkplain String#toUpperCase 转换大写} ，包括 {@code 'x'} (如果有的话) 和所有十六进制数字 {@code 'a'} - {@code 'f'} ('\u0061' - '\u0066'). |
如果转换是 {@code 'o'}, {@code 'x'} 或 {@code 'X'} ，并且同时给出了 {@code '#'} 和 {@code '0'} 标志，则结果将包含基数指示符 (八进制为 {@code '0'} ，十六进制为 {@code "0x"} 或 {@code "0X"})、一些零(基于宽度)和值。
如果未给出 {@code '-'} 标志，则空格填充将出现在符号之前。
以下 标志适用于数值整型转换：
| {@code '+'} | '\u002b' | 要求所有正数的输出都包含一个正号。如果没有给出这个标志，那么只有负值才会包含一个符号。 如果同时给出 {@code '+'} 和 ' ' 标志，则会抛出 {@link IllegalFormatFlagsException} 。 |
| ' ' | '\u0020' | 要求输出包含一个额外的空格 ('\u0020') 表示非负数。 如果同时给出 {@code '+'} 和 ' ' 标志，则会抛出 {@link IllegalFormatFlagsException} 。 |
| {@code '0'} | '\u0030' | 要求输出以 {@linkplain java.text.DecimalFormatSymbols#getZeroDigit zeros} 填充到任何符号或基数指示符之后的最小字段宽度，除非转换 NaN 或无穷大。如果没有提供宽度，则会抛出 {@link MissingFormatWidthException} 。 如果同时给出 {@code '-'} 和 {@code '0'} 标志，则会抛出 {@link IllegalFormatFlagsException} 。 |
| {@code ','} | '\u002c' | 要求输出包含特定于语言环境的 {@linkplain java.text.DecimalFormatSymbols#getGroupingSeparator 组分隔符} ，如本地化算法的 "group" 部分 所述。 |
| {@code '('} | '\u0028' | 要求输出在负数前面加上 {@code '('} ('\u0028') 并且在负数后面加上 {@code ')'} ('\u0029') 。 |
如果没有给出标志，默认格式如下：
- 输出在 {@code width} 内右对齐
- 负数以 {@code '-'} ('\u002d') 开头
- 正数和零不包含符号或额外的前导空格
- 不包含分组分隔符
宽度是要写入输出的最小字符数。这包括任何符号、数字、分组分隔符、基数指示符和括号。如果转换值的长度小于宽度，则输出将被空格 ('\u0020') 填充，直到字符总数等于宽度。默认情况下，填充在左侧。如果给出 {@code '-'} 标志，则填充将在右侧。如果没有指定宽度，则没有最小值。
精度不适用。如果指定了精度，则会抛出 {@link IllegalFormatPrecisionException} 。
BigInteger
下面的转换可以应用于 {@link java.math.BigInteger} 。
| {@code 'd'} | '\u0064' | 要求将输出格式设置为十进制整数。采用了定位算法。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'o'} | '\u006f' | 要求将输出格式设置为八进制整数。未应用本地化。 如果 x 是负数，那么结果将是一个以 {@code '-'} ('\u002d') 开头的有符号值。该类型允许有符号输出，因为与基本类型不同，如果不明确指定数据类型的大小，则无法创建等价的无符号输出。 如果 x 是正数或零，并且给出了 {@code '+'} 标志，则结果将以 {@code '+'} ('\u002b') 开头。 如果给出了 {@code '#'} 标志，则输出将始终以 {@code '0'} 前缀开头。 如果给出了 {@code '0'} 标志，则输出将在任何符号之后用前导零填充字段宽度。 如果给出了 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'x'} | '\u0078' | 要求将输出格式设置为十六进制整数。未应用本地化。 如果 x 是负数，那么结果将是一个以 {@code '-'} ('\u002d') 开头的有符号值。该类型允许有符号输出，因为与基本类型不同，如果不明确指定数据类型的大小，则无法创建等价的无符号输出。 如果 x 是正数或零，并且给出了 {@code '+'} 标志，则结果将以 {@code '+'} ('\u002b') 开头。 如果给出了 {@code '#'} 标志，则输出将始终以 {@code '0'} 前缀开头。 如果给出了 {@code '0'} 标志，则输出将在基数指示符或符号 (如果存在) 后以前导零填充到字段宽度。 如果给出了 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'X'} | '\u0058' | {@code 'x'} 的大写变体。表示数字的整个字符串将被转换为 {@linkplain String#toUpperCase 大写} ，包括 {@code 'x'} (如果有的话) 和所有十六进制数字 {@code 'a'} - {@code 'f'} ('\u0061' - '\u0066'). |
如果转换是 {@code 'o'}, {@code 'x'} 或 {@code 'X'} ，并且同时给出了 {@code '#'} 和 {@code '0'} 标志，则结果将包含基本指示符 (八进制为 {@code '0'} ，十六进制为 {@code "0x"} 或 {@code "0X"} ) ，一些零(基于宽度)和值。
如果给出了 {@code '0'} 标志，并且值是负数，那么零填充将出现在符号之后。
如果未给出 {@code '-'} 标志，则空格填充将出现在符号之前。
适用于 Byte, Short, Integer 和 Long 定义的所有标志 。当没有给出标志时，默认行为与 Byte, Short, Integer 和 Long 相同。
宽度的定义与 Byte, Short, Integer 和 Long 的定义相同。
精度不适用。如果指定了精度，则会抛出 {@link IllegalFormatPrecisionException} 。
Float 和 Double
下列转换可以应用于 {@code float}, {@link Float}, {@code double} 和 {@link Double} 。
| {@code 'e'} | '\u0065' | 要求使用计算机科学记数法对输出进行格式化。采用了定位算法。 大小 m 的格式取决于它的值。 如果 m 是 NaN 或无穷大，将分别输出字面值字符串 "NaN" 或 "Infinity" 。这些值没有本地化。 如果 m 是正零或负零，则指数将为 {@code "+00"} 。 否则，结果是一个表示参数的符号和大小(绝对值)的字符串。在定位算法中描述了符号的格式。大小 m 的格式取决于它的值。<= m < 10n+1 的唯一整数；然后设 a 为 m 与 10n 的精确商，使 1 <= a < 10 。然后将大小表示为 a 的整数部分，作为单个十进制数字，后跟十进制分隔符，后跟代表 a 的小数部分的十进制数字，然后是指数符号 {@code 'e'} ('\u0065') ，后跟指数符号，然后是 n 作为十进制整数的表示，由方法 {@link Long#toString(long, int)} 产生，并填充零以包含至少两位数字。 对于 m 或 a 的小数部分，结果中的位数等于精度。如果未指定精度，则默认值为 {@code 6}。如果精度小于 {@link Float#toString(float)} 或 {@link Double#toString(double)} 返回的字符串中小数点后出现的位数，则该值将使用 {@linkplain java.math.BigDecimal#ROUND_HALF_UP 四舍五入算法} 进行舍入。否则，可能会添加零以达到精度。对于值的规范表示，请酌情使用 {@link Float#toString(float)} 或 {@link Double#toString(double)} 。 如果给出了 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'E'} | '\u0045' | {@code 'e'} 的大写形式。指数符号将是 {@code 'E'} ('\u0045') 。 |
| {@code 'g'} | '\u0067' | 要求输出格式为如下所述的一般科学记数法。采用了定位算法。 在舍入精度之后，所得到的大小 m 的格式取决于它的值。 如果 m 大于或等于 10-4 ，但小于 10precision ，则用十进制格式表示。 如果 m 小于 10-4 或大于等于 10precision ，则用计算机科学记数法表示。 m 中有效数字的总数等于精度。如果未指定精度，则默认值为 {@code 6} 。如果精度为 {@code 0} ，则取其为 {@code 1} 。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'G'} | '\u0047' | {@code 'g'} 的大写变体。 |
| {@code 'f'} | '\u0066' | 要求使用十进制格式格式化输出。采用了定位算法 。 结果是一个表示参数的符号和大小(绝对值)的字符串。在定位算法中描述了符号的格式。大小 m 的格式取决于它的值。 如果 m 是 NaN 或无穷大，将分别输出字面值字符串 "NaN" 或 "Infinity" 。这些值没有本地化。 大小被格式化为 m 的整数部分，不带前导零，后跟小数分隔符，然后是表示 m 的小数部分的一个或多个十进制数字。 对于 m 或 a 的小数部分，结果中的位数等于精度。如果未指定精度，则默认值为 {@code 6}。如果精度小于 {@link Float#toString(float)} 或 {@link Double#toString(double)} 返回的字符串中小数点后出现的位数，则该值将使用 {@linkplain java.math.BigDecimal#ROUND_HALF_UP 四舍五入算法} 进行舍入。否则，可能会添加零以达到精度。对于值的规范表示，请酌情使用 {@link Float#toString(float)} 或 {@link Double#toString(double)} 。 |
| {@code 'a'} | '\u0061' | 要求将输出格式设置为十六进制指数形式。未应用本地化。 结果是一个表示参数 x 的符号和大小(绝对值)的字符串。 如果 x 是负值或负零值，则结果将以 {@code '-'} ('\u002d') 开头。 如果 x 是正数或正零值，并且给出了 {@code '+'} 标志，则结果将以 {@code '+'} ('\u002b') 开头。 大小 m 的格式取决于它的值。
|
| {@code 'A'} | '\u0041' | {@code 'a'} 的大写变体。表示数字的整个字符串将被转换为大写，包括 {@code 'x'} ('\u0078') 和 {@code 'p'} ('\u0070' 以及所有十六进制数字 {@code 'a'} - {@code 'f'} ('\u0061' - '\u0066') 。 |
适用于 Byte, Short, Integer 和 Long 定义的所有标志。
如果给出了 {@code '#'} 标志，那么小数分隔符将始终存在。
如果没有给出标志，默认格式如下：
- 输出在 {@code width} 内右对齐
- 负数以 {@code '-'} 开头
- 正数和正零不含符号或额外的前导空格
- 不含分组分隔符
- 小数分隔符只有在后面跟着数字时才会出现
宽度 是要写入输出的最小字符数。这包括任何符号、数字、分组分隔符、小数分隔符、指数符号、基数指示符、括号以及表示无穷大和 NaN 的字符串 (如适用) 。如果转换值的长度小于宽度，则输出将被空格 ('\u0020') 填充，直到字符总数等于宽度。默认情况下，填充在左侧。如果给出 {@code '-'} 标志，则填充将在右侧。如果没有指定宽度，则没有最小值。
如果转换是 {@code 'e'}, {@code 'E'} 或 {@code 'f'} ，那么精度就是小数点分隔符之后的位数。如果没有指定精度，则假定为 {@code 6} 。
如果转换是 {@code 'g'} 或 {@code 'G'} ，则精度是舍入后所得数量级中的有效数字总数。如果未指定精度，则默认值为 {@code 6} 。如果精度为 {@code 0} ，则取其为 {@code 1}.
如果转换是 {@code 'a'} 或 {@code 'A'} ，则精度是基数点后的十六进制位数。如果没有提供精度，则将输出 {@link Double#toHexString(double)} 返回的所有数字。
BigDecimal
以下转换可以应用于 {@link java.math.BigDecimal BigDecimal} 。
| {@code 'e'} | '\u0065' | 要求使用c计算机科学记数法对输出进行格式化。采用了定位算法。 大小 m 的格式取决于它的值。 如果 m 为正零或负零，则指数将为 {@code "+00"} 。 否则，结果是一个表示参数的符号和大小 (绝对值) 的字符串。在定位算法中描述了符号的格式。大小 m 的格式取决于它的值。 设 n 为满足 10n <= m < 10n+1的唯一整数；然后设 a 为 m 与 10n 的精确商，使 1 <= a < 10 。然后将大小表示为 a 的整数部分，作为单个十进制数字，后跟十进制分隔符，后跟代表 a 的小数部分的十进制数字，然后是指数符号 {@code 'e'} ('\u0065') ，后跟指数符号，然后是 n 作为十进制整数的表示，由方法 {@link Long#toString(long, int)} 产生，并填充零以包含至少两位数字。 对于 m 或 a 的小数部分，结果中的位数等于精度。如果未指定精度，则默认值为 {@code 6} 。如果精度小于小数点右边的位数，那么该值将使用 {@linkplain java.math.BigDecimal#ROUND_HALF_UP 四舍五入算法} 进行四舍五入。否则，可能会添加零以达到精度。对于值的规范表示，请使用 {@link BigDecimal#toString()} 。 如果给出了 {@code ','} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'E'} | '\u0045' | {@code 'e'} 的大写形式。指数符号将是 {@code 'E'} ('\u0045') 。 |
| {@code 'g'} | '\u0067' | 要求输出格式为如下所述的一般科学记数法。采用了定位算法。 在舍入精度之后，所得到的大小 m 的格式取决于它的值。 如果 m 大于或等于 10-4 ，但小于 10precision ，则用十进制格式表示。 如果 m 小于 10-4 或大于等于 10precision ，则用计算机科学记数法表示。 m中有效数字的总数等于精度。如果未指定精度，则默认值为 {@code 6} 。如果精度为 {@code 0} ，则取其为 {@code 1} 。 如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 |
| {@code 'G'} | '\u0047' | {@code 'g'} 的大写变体。 |
| {@code 'f'} | '\u0066' | 要求使用十进制格式格式化输出。采用了定位算法。 结果是一个表示参数的符号和大小 (绝对值) 的字符串。在定位算法中描述了符号的格式。大小 m 的格式取决于它的值。 大小被格式化为 m 的整数部分，不带前导零，后跟小数分隔符，然后是表示 m 的小数部分的一个或多个十进制数字。 对于 m 或 a 的小数部分，结果中的位数等于精度。如果未指定精度，则默认值为 {@code 6}。如果精度小于小数点右边的位数，那么该值将使用{@link java.math.BigDecimal#ROUND_HALF_UP 四舍五入算法} 进行四舍五入。否则，可能会添加零以达到精度。对于值的规范表示，请使用 {@link BigDecimal#toString()} 。 |
适用于 Byte, Short, Integer 和 Long 定义的所有标志。
如果给出了 {@code '#'} 标志，则小数分隔符将始终存在。
当没有给出标志时的默认行为与 Float 和 Double 相同。
Date/Time
此转换可以应用于 {@code long}, {@link Long}, {@link Calendar}, {@link Date} 和 {@link TemporalAccessor TemporalAccessor}
| {@code 't'} | '\u0074' | 日期和时间转换字符的前缀。 |
| {@code 'T'} | '\u0054' | {@code 't'} 的大写变体。 |
以下是为 {@code 't'} 和 {@code 'T'} 转换定义的日期和时间转换字符后缀。这些类型类似于 GNU {@code date} 和 POSIX {@code strftime(3c)} 定义的类型，但不完全相同。还提供了其他的转换类型来访问特定于 Java 的功能 (例如 {@code 'L'} 表示毫秒数)。
以下转换字符用于格式化时间：
| {@code 'H'} | '\u0048' | 24小时制时钟的一天中的小时，格式为两位数字，必要时带前导零，即 {@code 00 - 23} 。{@code 00} 表示午夜。 |
| {@code 'I'} | '\u0049' | 12小时制时钟的小时，格式为两位数字，必要时带前导零，即 {@code 01 - 12} 。{@code 01} 表示一点钟 (上午或下午)。 |
| {@code 'k'} | '\u006b' | 24小时制的一天中的小时，即 {@code 0 - 23} 。{@code 0} 表示午夜。 |
| {@code 'l'} | '\u006c' | 12小时制的小时，即 {@code 1 - 12} 。{@code 1} 表示一点钟 (上午或下午)。 |
| {@code 'M'} | '\u004d' | 小时内的分钟，格式为两位数字，必要时带前导零，即 {@code 00 - 59} 。 |
| {@code 'S'} | '\u0053' | 分钟内的秒数，格式为两位数字，必要时带前导零，即 {@code 00 - 60} ("{@code 60}" 是支持闰秒所需的特殊值)。 |
| {@code 'L'} | '\u004c' | 秒内的毫秒数，格式为三位数字，必要时带前导零，即 {@code 000 - 999} 。 |
| {@code 'N'} | '\u004e' | 秒内的纳秒，格式为9位数字，必要时带前导零，即 {@code 000000000 - 999999999} 。此值的精度受底层操作系统或硬件的分辨率限制。 |
| {@code 'p'} | '\u0070' | 特定于地区的 {@link java.text.DateFormatSymbols#getAmPmStrings 上午或下午} 小写标记，例如 "{@code am}" 或 "{@code pm}" 。使用转换前缀 {@code 'T'} 强制此输出为大写。(注意 {@code 'p'} 生成小写输出。这与 GNU {@code date} 和 POSIX {@code strftime(3c)} 产生大写输出不同。) |
| {@code 'z'} | '\u007a' | RFC 822风格数字的 GMT 时区偏移，例如 {@code -0800} 。此值将根据夏令时的需要进行调整。对于 {@code long}, {@link Long} 和 {@link Date} ，使用的时区是此Java虚拟机实例的 {@link TimeZone#getDefault() 默认时区} 。 |
| {@code 'Z'} | '\u005a' | 表示时区缩写的字符串。此值将根据夏令时的需要进行调整。对于 {@code long}, {@link Long} 和 {@link Date} ，使用的时区是此Java虚拟机实例的 {@linkplain TimeZone#getDefault() 默认时区} 。Formatter 的区域设置将取代参数的区域设置(如果有的话)。 |
| {@code 's'} | '\u0073' | 从1970年1月1日 {@code 00:00:00} UTC 开始的秒数，即 {@code Long.MIN_VALUE/1000} 到 {@code Long.MAX_VALUE/1000} 。 |
| {@code 'Q'} | '\u004f' | 从1970年1月1日 {@code 00:00:00} UTC 开始的毫秒数，即 {@code Long.MIN_VALUE} 到 {@code Long.MAX_VALUE} 。此值的精度受底层操作系统或硬件的分辨率限制。 |
以下转换字符用于格式化日期：
| {@code 'B'} | '\u0042' | 特定于地区的 {@linkplain java.text.DateFormatSymbols#getMonths 完整月份名称} ，例如 {@code "January"}, {@code "February"} 。 |
| {@code 'b'} | '\u0062' | 特定于地区的 {@linkplain java.text.DateFormatSymbols#getShortMonths 缩写月份名称} ，例如 {@code "Jan"}, {@code "Feb"} 。 |
| {@code 'h'} | '\u0068' | 与 {@code 'b'} 相同。 |
| {@code 'A'} | '\u0041' | 特定于语言环境的全名称 {@linkplain java.text.DateFormatSymbols#getWeekdays 一周中的哪一天} ，例如 {@code "Sunday"}, {@code "Monday"} 。 |
| {@code 'a'} | '\u0061' | 特定于语言环境的短名称 {@linkplain java.text.DateFormatSymbols#getShortWeekdays 一周中的哪一天} ，例如 {@code "Sun"}, {@code "Mon"} 。 |
| {@code 'C'} | '\u0043' | 四位数年份除以 {@code 100} ，格式为两位数字，必要时带前导零，即 {@code 00 - 99} 。 |
| {@code 'Y'} | '\u0059' | 年份，格式化为至少四位数字，必要时带前导零，例如，对于公历，{@code 0092} 等于 {@code 92} CE 。 |
| {@code 'y'} | '\u0079' | 年份的最后两位数字，必要时用前导零格式化，即 {@code 00 - 99} 。 |
| {@code 'j'} | '\u006a' | 一年中的第几天，格式为三位数字，必要时带前导零，例如公历的 {@code 001 - 366} 。{@code 001} 表示一年的第一天。 |
| {@code 'm'} | '\u006d' | 月份，根据需要格式化为带前导零的两位数字，即 {@code 01 - 13} ，其中 "{@code 01}" 是一年的第一个月，并且 ("{@code 13}" 是支持阴历所需的特殊值) 。 |
| {@code 'd'} | '\u0064' | 月中的一天，格式为两位数字，必要时带前导零，即 {@code 01 - 31} ，其中 "{@code 01}" 表示该月的第一天。 |
| {@code 'e'} | '\u0065' | 月中的一天，格式为两位数字，即 {@code 1 - 31} ，其中 "{@code 1}" 表示该月的第一天。 |
以下转换字符用于格式化常见的日期/时间组合。
| {@code 'R'} | '\u0052' | 24小时制的时间格式为 {@code "%tH:%tM"} |
| {@code 'T'} | '\u0054' | 24小时制的时间格式为 {@code "%tH:%tM:%tS"}. |
| {@code 'r'} | '\u0072' | 12小时制时钟的时间格式为 {@code "%tI:%tM:%tS %Tp"} 。上午或下午标记 ({@code '%Tp'}) 的位置可能与语言环境有关。 |
| {@code 'D'} | '\u0044' | 日期格式为 {@code "%tm/%td/%ty"} 。 |
| {@code 'F'} | '\u0046' | ISO 8601 完整日期格式为 {@code "%tY-%tm-%td"} 。 |
| {@code 'c'} | '\u0063' | 日期和时间格式为 {@code "%ta %tb %td %tT %tZ %tY"} ，例如 {@code "Sun Jul 20 16:17:00 EDT 1969"} 。 |
适用于为通用转换定义的 {@code '-'} 标志。如果给出了 {@code '#'} 标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。
宽度是要写入输出的最小字符数。如果转换值的长度小于 {@code width} ，则输出将被空格 ('\u0020') 填充，直到字符总数等于宽度。默认情况下，填充在左侧。如果给出了 {@code '-'} 标志，则填充将在右侧。如果没有指定宽度，则没有最小值。
精度不适用。如果指定了精度，则会抛出 {@link IllegalFormatPrecisionException} 。
百分比
转换不对应于任何参数。
| {@code '%'} | 结果是字面量 {@code '%'} ('\u0025') 宽度是要写入输出的最小字符数，包括 {@code '%'}。如果转换值的长度小于 {@code width} ，则输出将被空格 ('\u0020') 填充，直到字符总数等于宽度。填充物在左边。如果没有指定宽度，则只输出 {@code '%'} 。 适用于为通用转换定义的 {@code '-'} 标志。如果提供了任何其他标志，则会抛出 {@link FormatFlagsConversionMismatchException} 。 精度不适用。如果指定了精度，则会抛出 {@link IllegalFormatPrecisionException} 。 |
行分隔符
转换不对应任何参数。
| {@code 'n'} | 由 {@link System#getProperty System.getProperty("line.separator")} 返回的平台特有的行分隔符。 |
标志、宽度和精度不适用。如果提供了，则分别会抛出 {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException} 和 {@link IllegalFormatPrecisionException} 。
参数索引
格式说明符可以通过三种方式引用参数：
- 当格式说明符包含参数索引时，使用显式索引。参数索引是一个十进制整数，表示参数在参数列表中的位置。第一个参数由 "{@code 1$}" 引用，第二个参数由 "{@code 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" - 当格式说明符包含{@code '<'} ('\u003c')标志时，会使用相对索引，这会导致重用前一个格式说明符的参数。如果前面没有参数，则抛出 {@link MissingFormatArgumentException} 。
formatter.format("%s %s %<s %<s", "a", "b", "c", "d") // -> "a b b b" // "c" 和 "d" 会被忽略，因为它们没有被引用 - 当格式说明符既不包含参数索引也不包含 {@code '<'} 标志时，使用普通索引。每个使用普通索引的格式说明符都被分配一个顺序隐式索引到参数列表中，该索引独立于显式或相对索引使用的索引。
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" 和 "d" 会被忽略，因为它们没有被引用
参数的最大数量受 Java 数组的最大维数的限制，该数组的最大维数由 Java™ 虚拟机规范定义。 如果参数索引与可用参数不对应，则抛出 {@link MissingFormatArgumentException} 。
如果参数多于格式说明符，则忽略多余的参数。
除非另有说明，否则将 {@code null} 参数传递给该类中的任何方法或构造函数都会引发 {@link NullPointerException} 异常。
3725
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
