HexFormat
将字节、字符和十六进制编码的字符串之间进行转换,这些字符串可能包括附加的格式标记,如前缀、后缀和分隔符。
有两个预设参数的 HexFormat
工厂,分别是 of()
和 ofDelimiter(delimiter)
。对于其他参数组合,withXXX
方法返回修改后的 HexFormat
副本,可以修改 withPrefix(String)
、withSuffix(String)
、withDelimiter(String)
或选择 withUpperCase()
或 withLowerCase()
参数。
对于基本类型到十六进制字符串的转换,toHexDigits
方法包括 toHexDigits(byte)
、toHexDigits(int)
和 toHexDigits(long)
等。默认情况下使用小写字符 "0-9","a-f"
。对于产生大写十六进制的转换,字符为 "0-9","A-F"
。只考虑 HexFormat.isUpperCase()
参数;分隔符、前缀和后缀不会被使用。
对于十六进制字符串到基本类型的转换,fromHexDigits
方法包括 fromHexDigits(string)
、fromHexDigitsToLong(string)
和 fromHexDigit(int)
用于转换单个字符或代码点。对于从十六进制字符转换,数字和大写和小写字符 "0-9", "a-f", 和 "A-F"
被转换为相应的值 0-15
。分隔符、前缀、后缀和大写参数不会被使用。
对于字节数组到格式化十六进制字符串的转换,formatHex
方法包括 formatHex(byte[])
和 formatHex(Appendable, byte[])
。格式化的输出是一个字符串,或者附加到 Appendable
,如 StringBuilder
或 PrintStream
。每个字节值被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。每个格式化值后面都跟随一个分隔符,除了最后一个。对于产生大写十六进制字符串的转换,请使用 withUpperCase()
。
对于格式化的十六进制字符串到字节数组的转换,parseHex
方法包括 parseHex(CharSequence)
和 parseHex(char[], offset, length)
。每个字节值从前缀、两个不区分大小写的十六进制字符和后缀中解析出来。每个格式化值后面都跟随一个分隔符,除了最后一个。
- API 注意:
-
例如,将单个字节转换为十六进制数字字符串使用
toHexDigits(int)
,并将字符串转换为基本值使用fromHexDigits(string)
。HexFormat hex = HexFormat.of(); byte b = 127; String byteStr = hex.toHexDigits(b); byte byteVal = (byte)hex.fromHexDigits(byteStr); assert(byteStr.equals("7f")); assert(b == byteVal); // 十六进制数字为: "7f"
对于以逗号(
", "
)分隔的格式,使用前缀("#"
)和小写十六进制数字的HexFormat
是:HexFormat commaFormat = HexFormat.ofDelimiter(", ").withPrefix("#"); byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127}; String str = commaFormat.formatHex(bytes); byte[] parsed = commaFormat.parseHex(str); assert(Arrays.equals(bytes, parsed)); // 格式化的字符串为: "#00, #01, #02, #03, #7c, #7d, #7e, #7f"
对于使用冒号(
":"
)分隔和大写字符的字节值指纹,HexFormat
是:HexFormat formatFingerprint = HexFormat.ofDelimiter(":").withUpperCase(); byte[] bytes = {0, 1, 2, 3, 124, 125, 126, 127}; String str = formatFingerprint.formatHex(bytes); byte[] parsed = formatFingerprint.parseHex(str); assert(Arrays.equals(bytes, parsed)); // 格式化的字符串为: "00:01:02:03:7C:7D:7E:7F"
这是一个基于值的类;在
HexFormat
实例上使用身份敏感操作(包括引用相等性(==
)、身份哈希码或同步)可能会导致不可预测的结果,应避免使用。应该使用equals
方法进行比较。此类是不可变的且线程安全的。
除非另有说明,否则将 null 参数传递给任何方法将导致抛出
NullPointerException
。 - 自 JDK 版本:
- 17
-
Method Summary
Modifier and TypeMethodDescription返回格式化十六进制字符串中十六进制值之间的分隔符。boolean
如果另一个对象是具有相同参数的HexFormat
,则返回true
。formatHex
(byte[] bytes) 返回从字节数组格式化的十六进制字符串。formatHex
(byte[] bytes, int fromIndex, int toIndex) 返回从字节数组范围格式化的十六进制字符串。<A extends Appendable>
AformatHex
(A out, byte[] bytes) 将从字节数组中格式化的十六进制字符串附加到Appendable
。<A extends Appendable>
AformatHex
(A out, byte[] bytes, int fromIndex, int toIndex) 将从字节数组范围中格式化的十六进制字符串附加到Appendable
。static int
fromHexDigit
(int ch) 返回十六进制字符或代码点的值。static int
fromHexDigits
(CharSequence string) 返回从最多八个十六进制字符的字符串中解析的int
值。static int
fromHexDigits
(CharSequence string, int fromIndex, int toIndex) 返回从字符串范围中最多八个十六进制字符解析的int
值。static long
fromHexDigitsToLong
(CharSequence string) 返回从最多十六个十六进制字符的字符串中解析的long
值。static long
fromHexDigitsToLong
(CharSequence string, int fromIndex, int toIndex) 返回从字符串范围中最多十六个十六进制字符解析的long
值。int
hashCode()
返回此HexFormat
的哈希码。static boolean
isHexDigit
(int ch) 如果字符是有效的十六进制字符或代码点,则返回true
。boolean
如果十六进制数字为大写,则返回true
,否则返回false
。static HexFormat
of()
返回没有分隔符和小写字符的十六进制格式化器。static HexFormat
ofDelimiter
(String delimiter) 返回带有分隔符和小写字符的十六进制格式化器。byte[]
parseHex
(char[] chars, int fromIndex, int toIndex) 返回从字符数组范围中解析的十六进制值的字节数组。byte[]
parseHex
(CharSequence string) 返回从字符串中解析的十六进制值的字节数组。byte[]
parseHex
(CharSequence string, int fromIndex, int toIndex) 返回从字符串范围中解析的十六进制值的字节数组。prefix()
返回格式化十六进制字符串中每个十六进制值使用的前缀。suffix()
返回格式化十六进制字符串中每个十六进制值使用的后缀。toHexDigits
(byte value) 返回byte
值的两个十六进制字符。toHexDigits
(char value) 返回char
值的四个十六进制字符。toHexDigits
(int value) 返回int
值的八个十六进制字符。toHexDigits
(long value) 返回long
值的十六个十六进制字符。toHexDigits
(long value, int digits) 返回long
值的最多十六个十六进制字符。toHexDigits
(short value) 返回short
值的四个十六进制字符。<A extends Appendable>
AtoHexDigits
(A out, byte value) 将字节值的两个十六进制字符附加到Appendable
。char
toHighHexDigit
(int value) 返回值的高 4 位的十六进制字符,将其视为一个字节。char
toLowHexDigit
(int value) 返回值的低 4 位的十六进制字符,将其视为一个字节。toString()
返回大写、分隔符、前缀和后缀的格式化器参数的描述。withDelimiter
(String delimiter) 返回带有分隔符的此HexFormat
的副本。返回使用小写十六进制字符的此HexFormat
的副本。withPrefix
(String prefix) 返回带有前缀的此HexFormat
的副本。withSuffix
(String suffix) 返回带有后缀的此HexFormat
的副本。返回使用大写十六进制字符的此HexFormat
的副本。
-
Method Details
-
of
返回没有分隔符和小写字符的十六进制格式化器。分隔符、前缀和后缀为空。方法withDelimiter
、withUpperCase
、withLowerCase
、withPrefix
和withSuffix
返回具有新参数的格式化器副本。- 返回:
- 没有分隔符和小写字符的十六进制格式化器
-
ofDelimiter
返回带有分隔符和小写字符的十六进制格式化器。前缀和后缀为空。方法withDelimiter
、withUpperCase
、withLowerCase
、withPrefix
和withSuffix
返回具有新参数的格式化器副本。- 参数:
-
delimiter
- 一个分隔符,非空,可以为空 - 返回:
-
带有分隔符和小写字符的
HexFormat
-
withDelimiter
返回带有分隔符的此HexFormat
的副本。- 参数:
-
delimiter
- 分隔符,非空,可以为空 - 返回:
-
带有分隔符的此
HexFormat
的副本
-
withPrefix
返回带有前缀的此HexFormat
的副本。- 参数:
-
prefix
- 前缀,非空,可以为空 - 返回:
-
带有前缀的此
HexFormat
的副本
-
withSuffix
返回带有后缀的此HexFormat
的副本。- 参数:
-
suffix
- 后缀,非空,可以为空 - 返回:
-
带有后缀的此
HexFormat
的副本
-
withUpperCase
返回使用大写十六进制字符的此HexFormat
的副本。大写十六进制字符为"0-9", "A-F"
。- 返回:
-
带有大写十六进制字符的此
HexFormat
的副本
-
withLowerCase
返回使用小写十六进制字符的此HexFormat
的副本。小写十六进制字符为"0-9", "a-f"
。- 返回:
-
带有小写十六进制字符的此
HexFormat
的副本
-
delimiter
返回格式化十六进制字符串中十六进制值之间的分隔符。- 返回:
-
分隔符,非空,可以为空
""
-
prefix
返回格式化十六进制字符串中每个十六进制值的前缀。- 返回:
-
前缀,非空,可以为空
""
-
suffix
返回格式化十六进制字符串中每个十六进制值的后缀。- 返回:
-
后缀,非空,可以为空
""
-
isUpperCase
public boolean isUpperCase()如果十六进制数字为大写,则返回true
,否则返回false
。- 返回:
-
如果十六进制数字为大写,则返回
true
,否则返回false
-
formatHex
从字节数组格式化为十六进制字符串。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。行为等同于formatHex(bytes, 0, bytes.length))
。- 参数:
-
bytes
- 一个非空的字节数组 - 返回:
- 字节数组的十六进制格式化字符串
-
formatHex
从字节数组范围格式化为十六进制字符串。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。- 参数:
-
bytes
- 一个非空的字节数组 -
fromIndex
- 范围的初始索引,包括 -
toIndex
- 范围的最终索引,不包括 - 返回:
- 格式化每个字节的字符串十六进制值
- 抛出:
-
IndexOutOfBoundsException
- 如果数组范围超出界限
-
formatHex
将字节数组中的格式化十六进制字符串附加到Appendable
。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。格式化的十六进制字符串以零次或多次调用Appendable
方法附加。- 类型参数:
-
A
-Appendable
的类型 - 参数:
-
out
- 一个Appendable
,非空 -
bytes
- 一个字节数组 - 返回:
-
Appendable
- 抛出:
-
UncheckedIOException
- 如果在附加到输出时发生I/O异常
-
formatHex
将字节数组范围中的格式化十六进制字符串附加到Appendable
。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。格式化的十六进制字符串以零次或多次调用Appendable
方法附加。- 类型参数:
-
A
-Appendable
的类型 - 参数:
-
out
- 一个Appendable
,非空 -
bytes
- 一个字节数组,非空 -
fromIndex
- 范围的初始索引,包括 -
toIndex
- 范围的最终索引,不包括 - 返回:
-
Appendable
- 抛出:
-
IndexOutOfBoundsException
- 如果数组范围超出界限 -
UncheckedIOException
- 如果在附加到输出时发生I/O异常
-
parseHex
返回包含从字符串解析的十六进制值的字节数组。每个字节值都从前缀、两个不区分大小写的十六进制字符和后缀中解析。除最后一个值外,每个格式化值后面都有一个分隔符。分隔符、前缀和后缀字符串必须存在;它们可以是空字符串。有效字符串仅包含上述格式。- 参数:
-
string
- 包含带有前缀、十六进制数字、后缀和分隔符的字节值的字符串 - 返回:
- 从字符串解析的值的字节数组
- 抛出:
-
IllegalArgumentException
- 如果每个字节值的前缀或后缀不存在,字节值不是十六进制字符,或者在除最后一个字节值之外的所有字节值后分隔符不存在
-
parseHex
返回包含从字符串范围解析的十六进制值的字节数组。每个字节值都从前缀、两个不区分大小写的十六进制字符和后缀中解析。除最后一个值外,每个格式化值后面都有一个分隔符。分隔符、前缀和后缀字符串必须存在;它们可以是空字符串。有效字符串仅包含上述格式。- 参数:
-
string
- 包含十六进制数字、分隔符、前缀和后缀的字符串范围 -
fromIndex
- 范围的初始索引,包括 -
toIndex
- 范围的最终索引,不包括 - 返回:
- 从字符串范围解析的值的字节数组
- 抛出:
-
IllegalArgumentException
- 如果每个字节值的前缀或后缀不存在,字节值不是十六进制字符,或者在除最后一个字节值之外的所有字节值后分隔符不存在 -
IndexOutOfBoundsException
- 如果字符串范围超出界限
-
parseHex
public byte[] parseHex(char[] chars, int fromIndex, int toIndex) 返回包含从字符数组范围解析的十六进制值的字节数组。每个字节值都从前缀、两个不区分大小写的十六进制字符和后缀中解析。除最后一个值外,每个格式化值后面都有一个分隔符。分隔符、前缀和后缀字符串必须存在;它们可以是空字符串。有效字符数组范围仅包含上述格式。- 参数:
-
chars
- 包含偶数个十六进制数字、分隔符、前缀和后缀的字符数组范围 -
fromIndex
- 范围的初始索引,包括 -
toIndex
- 范围的最终索引,不包括 - 返回:
- 从字符数组范围解析的值的字节数组
- 抛出:
-
IllegalArgumentException
- 如果每个字节值的前缀或后缀不存在,字节值不是十六进制字符,或者在除最后一个字节值之外的所有字节值后分隔符不存在 -
IndexOutOfBoundsException
- 如果字符数组范围超出界限
-
toLowHexDigit
public char toLowHexDigit(int value) - 参数:
-
value
- 一个值,仅使用值的低4位0-3
- 返回:
-
值的低4位
0-3
的十六进制字符
-
toHighHexDigit
public char toHighHexDigit(int value) - 参数:
-
value
- 一个值,仅使用值的4-7
位 - 返回:
-
值的
4-7
位的十六进制字符
-
toHexDigits
将两个十六进制字符附加到Appendable
的字节值。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。十六进制字符将在一个或多个调用Appendable
方法时附加。不使用分隔符、前缀和后缀。- 类型参数:
-
A
-Appendable
的类型 - 参数:
-
out
- 一个非空的Appendable
-
value
- 一个字节值 - 返回:
-
Appendable
- 抛出:
-
UncheckedIOException
- 如果在追加到输出时发生I/O异常
-
toHexDigits
返回byte
值的两个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个字节值 - 返回:
- 字节值的两个十六进制字符
-
toHexDigits
返回char
值的四个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个char
值 - 返回:
-
char
值的四个十六进制字符
-
toHexDigits
返回short
值的四个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个short
值 - 返回:
-
short
值的四个十六进制字符
-
toHexDigits
返回int
值的八个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个int
值 - 返回:
-
int
值的八个十六进制字符 - 参见:
-
toHexDigits
返回long
值的十六个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个long
值 - 返回:
-
long
值的十六个十六进制字符 - 参见:
-
toHexDigits
返回long
值的最多十六个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)
进行格式化一样。不使用分隔符、前缀和后缀。- 参数:
-
value
- 一个long
值 -
digits
- 要返回的十六进制数字的位数,从0到16 - 返回:
-
long
值的十六进制字符 - 抛出:
-
IllegalArgumentException
- 如果digits
为负数或大于16
-
isHexDigit
public static boolean isHexDigit(int ch) 如果字符是有效的十六进制字符或代码点,则返回true
。有效的十六进制字符包括:'0' ('\u0030')
到'9' ('\u0039')
,'A' ('\u0041')
到'F' ('\u0046')
,以及'a' ('\u0061')
到'f' ('\u0066')
。
- 参数:
-
ch
- 一个代码点 - 返回:
-
如果字符是有效的十六进制字符,则返回
true
,否则返回false
-
fromHexDigit
public static int fromHexDigit(int ch) 返回十六进制字符或代码点的值。该值为:(ch - '0')
对于'0'
到'9'
,(ch - 'A' + 10)
对于'A'
到'F'
,(ch - 'a' + 10)
对于'a'
到'f'
。
- 参数:
-
ch
- 一个字符或代码点 - 返回:
-
值
0-15
- 抛出:
-
NumberFormatException
- 如果代码点不是十六进制字符
-
fromHexDigits
- API注释:
-
Integer.parseInt(s, 16)
和Integer.parseUnsignedInt(s, 16)
类似,但允许所有由Character.digit(ch, 16)
定义的Unicode十六进制数字。HexFormat
仅使用十六进制字符"0-9"
、"A-F"
和"a-f"
。带符号的十六进制字符串可以使用Integer.parseInt(String, int)
进行解析。 - 参数:
-
string
- 包含最多八个十六进制字符的CharSequence - 返回:
- 从字符串解析出的值
- 抛出:
-
IllegalArgumentException
- 如果字符串长度大于八(8)或任何字符不是十六进制字符
-
fromHexDigits
从包含最多八个十六进制字符的字符串范围中解析出int
值。从范围fromIndex
到toIndex
(不包括)的字符将从最高有效位到最低有效位使用fromHexDigit(int)
解析为无符号值。该值在32位上进行零扩展,并作为int
返回。- API注释:
-
Integer.parseInt(s, 16)
和Integer.parseUnsignedInt(s, 16)
类似,但允许所有由Character.digit(ch, 16)
定义的Unicode十六进制数字。HexFormat
仅使用十六进制字符"0-9"
、"A-F"
和"a-f"
。带符号的十六进制字符串可以使用Integer.parseInt(String, int)
进行解析。 - 参数:
-
string
- 包含字符的CharSequence -
fromIndex
- 范围的初始索引(包括) -
toIndex
- 范围的最终索引(不包括) - 返回:
- 从字符串范围解析出的值
- 抛出:
-
IndexOutOfBoundsException
- 如果范围超出CharSequence
的边界 -
IllegalArgumentException
- 如果范围的长度大于八(8)或任何字符不是十六进制字符
-
fromHexDigitsToLong
从包含最多十六个十六进制字符的字符串中解析出long
值。使用fromHexDigit(int)
从最高有效位到最低有效位解析十六进制字符,形成一个无符号值。该值在64位上进行零扩展,并作为long
返回。- API注释:
-
Long.parseLong(s, 16)
和Long.parseUnsignedLong(s, 16)
类似,但允许所有由Character.digit(ch, 16)
定义的Unicode十六进制数字。HexFormat
仅使用十六进制字符"0-9"
、"A-F"
和"a-f"
。带符号的十六进制字符串可以使用Long.parseLong(String, int)
进行解析。 - 参数:
-
string
- 包含最多十六个十六进制字符的CharSequence - 返回:
- 从字符串解析出的值
- 抛出:
-
IllegalArgumentException
- 如果字符串长度大于十六(16)或任何字符不是十六进制字符
-
fromHexDigitsToLong
从包含最多十六个十六进制字符的字符串范围中解析出long
值。从范围fromIndex
到toIndex
(不包括)的字符将从最高有效位到最低有效位使用fromHexDigit(int)
解析为无符号值。该值在64位上进行零扩展,并作为long
返回。- API注释:
-
Long.parseLong(s, 16)
和Long.parseUnsignedLong(s, 16)
类似,但允许所有由Character.digit(ch, 16)
定义的Unicode十六进制数字。HexFormat
仅使用十六进制字符"0-9"
,"A-F"
和"a-f"
。有符号十六进制字符串可以使用Long.parseLong(String, int)
进行解析。 - 参数:
-
string
- 包含字符的CharSequence -
fromIndex
- 范围的初始索引(包括) -
toIndex
- 范围的最终索引(不包括) - 返回值:
- 从字符串范围解析的值
- 抛出:
-
IndexOutOfBoundsException
- 如果范围超出了CharSequence
的边界 -
IllegalArgumentException
- 如果范围的长度大于十六(16)或任何字符不是十六进制字符
-
equals
如果另一个对象是具有相同参数的HexFormat
,则返回true
。 -
hashCode
public int hashCode()返回此HexFormat
的哈希码。 -
toString
返回大写、分隔符、前缀和后缀的格式化参数的描述。
-