Module java.base
Package java.util

Class HexFormat

java.lang.Object
java.util.HexFormat

public final class HexFormat extends Object
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,如 StringBuilderPrintStream。每个字节值被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。每个格式化值后面都跟随一个分隔符,除了最后一个。对于产生大写十六进制字符串的转换,请使用 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 Type
    Method
    Description
    返回格式化十六进制字符串中十六进制值之间的分隔符。
    boolean
    如果另一个对象是具有相同参数的 HexFormat,则返回 true
    formatHex(byte[] bytes)
    返回从字节数组格式化的十六进制字符串。
    formatHex(byte[] bytes, int fromIndex, int toIndex)
    返回从字节数组范围格式化的十六进制字符串。
    <A extends Appendable>
    A
    formatHex(A out, byte[] bytes)
    将从字节数组中格式化的十六进制字符串附加到 Appendable
    <A extends Appendable>
    A
    formatHex(A out, byte[] bytes, int fromIndex, int toIndex)
    将从字节数组范围中格式化的十六进制字符串附加到 Appendable
    static int
    fromHexDigit(int ch)
    返回十六进制字符或代码点的值。
    static int
    返回从最多八个十六进制字符的字符串中解析的 int 值。
    static int
    fromHexDigits(CharSequence string, int fromIndex, int toIndex)
    返回从字符串范围中最多八个十六进制字符解析的 int 值。
    static long
    返回从最多十六个十六进制字符的字符串中解析的 long 值。
    static long
    fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex)
    返回从字符串范围中最多十六个十六进制字符解析的 long 值。
    int
    返回此 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[]
    返回从字符串中解析的十六进制值的字节数组。
    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>
    A
    toHexDigits(A out, byte value)
    将字节值的两个十六进制字符附加到 Appendable
    char
    toHighHexDigit(int value)
    返回值的高 4 位的十六进制字符,将其视为一个字节。
    char
    toLowHexDigit(int value)
    返回值的低 4 位的十六进制字符,将其视为一个字节。
    返回大写、分隔符、前缀和后缀的格式化器参数的描述。
    withDelimiter(String delimiter)
    返回带有分隔符的此 HexFormat 的副本。
    返回使用小写十六进制字符的此 HexFormat 的副本。
    withPrefix(String prefix)
    返回带有前缀的此 HexFormat 的副本。
    withSuffix(String suffix)
    返回带有后缀的此 HexFormat 的副本。
    返回使用大写十六进制字符的此 HexFormat 的副本。

    Methods declared in class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Method Details

    • of

      public static HexFormat of()
      返回没有分隔符和小写字符的十六进制格式化器。分隔符、前缀和后缀为空。方法 withDelimiterwithUpperCasewithLowerCasewithPrefixwithSuffix 返回具有新参数的格式化器副本。
      返回:
      没有分隔符和小写字符的十六进制格式化器
    • ofDelimiter

      public static HexFormat ofDelimiter(String delimiter)
      返回带有分隔符和小写字符的十六进制格式化器。前缀和后缀为空。方法 withDelimiterwithUpperCasewithLowerCasewithPrefixwithSuffix 返回具有新参数的格式化器副本。
      参数:
      delimiter - 一个分隔符,非空,可以为空
      返回:
      带有分隔符和小写字符的 HexFormat
    • withDelimiter

      public HexFormat withDelimiter(String delimiter)
      返回带有分隔符的此 HexFormat 的副本。
      参数:
      delimiter - 分隔符,非空,可以为空
      返回:
      带有分隔符的此 HexFormat 的副本
    • withPrefix

      public HexFormat withPrefix(String prefix)
      返回带有前缀的此HexFormat的副本。
      参数:
      prefix - 前缀,非空,可以为空
      返回:
      带有前缀的此HexFormat的副本
    • withSuffix

      public HexFormat withSuffix(String suffix)
      返回带有后缀的此HexFormat的副本。
      参数:
      suffix - 后缀,非空,可以为空
      返回:
      带有后缀的此HexFormat的副本
    • withUpperCase

      public HexFormat withUpperCase()
      返回使用大写十六进制字符的此HexFormat的副本。大写十六进制字符为"0-9", "A-F"
      返回:
      带有大写十六进制字符的此HexFormat的副本
    • withLowerCase

      public HexFormat withLowerCase()
      返回使用小写十六进制字符的此HexFormat的副本。小写十六进制字符为"0-9", "a-f"
      返回:
      带有小写十六进制字符的此HexFormat的副本
    • delimiter

      public String delimiter()
      返回格式化十六进制字符串中十六进制值之间的分隔符。
      返回:
      分隔符,非空,可以为空""
    • prefix

      public String prefix()
      返回格式化十六进制字符串中每个十六进制值的前缀。
      返回:
      前缀,非空,可以为空""
    • suffix

      public String suffix()
      返回格式化十六进制字符串中每个十六进制值的后缀。
      返回:
      后缀,非空,可以为空""
    • isUpperCase

      public boolean isUpperCase()
      如果十六进制数字为大写,则返回true,否则返回false
      返回:
      如果十六进制数字为大写,则返回true,否则返回false
    • formatHex

      public String formatHex(byte[] bytes)
      从字节数组格式化为十六进制字符串。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。行为等同于formatHex(bytes, 0, bytes.length))
      参数:
      bytes - 一个非空的字节数组
      返回:
      字节数组的十六进制格式化字符串
    • formatHex

      public String formatHex(byte[] bytes, int fromIndex, int toIndex)
      从字节数组范围格式化为十六进制字符串。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。
      参数:
      bytes - 一个非空的字节数组
      fromIndex - 范围的初始索引,包括
      toIndex - 范围的最终索引,不包括
      返回:
      格式化每个字节的字符串十六进制值
      抛出:
      IndexOutOfBoundsException - 如果数组范围超出界限
    • formatHex

      public <A extends Appendable> A formatHex(A out, byte[] bytes)
      将字节数组中的格式化十六进制字符串附加到Appendable。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。格式化的十六进制字符串以零次或多次调用Appendable方法附加。
      类型参数:
      A - Appendable的类型
      参数:
      out - 一个Appendable,非空
      bytes - 一个字节数组
      返回:
      Appendable
      抛出:
      UncheckedIOException - 如果在附加到输出时发生I/O异常
    • formatHex

      public <A extends Appendable> A formatHex(A out, byte[] bytes, int fromIndex, int toIndex)
      将字节数组范围中的格式化十六进制字符串附加到Appendable。每个字节值都被格式化为前缀、两个十六进制字符(从大写或小写数字中选择)和后缀。除最后一个值外,每个格式化值后面都有一个分隔符。格式化的十六进制字符串以零次或多次调用Appendable方法附加。
      类型参数:
      A - Appendable的类型
      参数:
      out - 一个Appendable,非空
      bytes - 一个字节数组,非空
      fromIndex - 范围的初始索引,包括
      toIndex - 范围的最终索引,不包括
      返回:
      Appendable
      抛出:
      IndexOutOfBoundsException - 如果数组范围超出界限
      UncheckedIOException - 如果在附加到输出时发生I/O异常
    • parseHex

      public byte[] parseHex(CharSequence string)
      返回包含从字符串解析的十六进制值的字节数组。每个字节值都从前缀、两个不区分大小写的十六进制字符和后缀中解析。除最后一个值外,每个格式化值后面都有一个分隔符。分隔符、前缀和后缀字符串必须存在;它们可以是空字符串。有效字符串仅包含上述格式。
      参数:
      string - 包含带有前缀、十六进制数字、后缀和分隔符的字节值的字符串
      返回:
      从字符串解析的值的字节数组
      抛出:
      IllegalArgumentException - 如果每个字节值的前缀或后缀不存在,字节值不是十六进制字符,或者在除最后一个字节值之外的所有字节值后分隔符不存在
    • parseHex

      public byte[] parseHex(CharSequence string, int fromIndex, int toIndex)
      返回包含从字符串范围解析的十六进制值的字节数组。每个字节值都从前缀、两个不区分大小写的十六进制字符和后缀中解析。除最后一个值外,每个格式化值后面都有一个分隔符。分隔符、前缀和后缀字符串必须存在;它们可以是空字符串。有效字符串仅包含上述格式。
      参数:
      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)
      返回值被视为字节的低4位的十六进制字符。如果参数isUpperCase()true,则对于值10-15返回的字符为大写"A-F",否则返回的字符为小写"a-f"。范围0-9的值返回为"0-9"
      参数:
      value - 一个值,仅使用值的低4位0-3
      返回:
      值的低4位0-3的十六进制字符
    • toHighHexDigit

      public char toHighHexDigit(int value)
      返回值被视为字节的高4位的十六进制字符。如果参数isUpperCase()true,则对于值10-15返回的字符为大写"A-F",否则返回的字符为小写"a-f"。范围0-9的值返回为"0-9"
      参数:
      value - 一个值,仅使用值的4-7
      返回:
      值的4-7位的十六进制字符
    • toHexDigits

      public <A extends Appendable> A toHexDigits(A out, byte value)
      将两个十六进制字符附加到Appendable的字节值。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。十六进制字符将在一个或多个调用Appendable方法时附加。不使用分隔符、前缀和后缀。
      类型参数:
      A - Appendable的类型
      参数:
      out - 一个非空的Appendable
      value - 一个字节值
      返回:
      Appendable
      抛出:
      UncheckedIOException - 如果在追加到输出时发生I/O异常
    • toHexDigits

      public String toHexDigits(byte value)
      返回byte值的两个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。不使用分隔符、前缀和后缀。
      参数:
      value - 一个字节值
      返回:
      字节值的两个十六进制字符
    • toHexDigits

      public String toHexDigits(char value)
      返回char值的四个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。不使用分隔符、前缀和后缀。
      参数:
      value - 一个char
      返回:
      char值的四个十六进制字符
    • toHexDigits

      public String toHexDigits(short value)
      返回short值的四个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。不使用分隔符、前缀和后缀。
      参数:
      value - 一个short
      返回:
      short值的四个十六进制字符
    • toHexDigits

      public String toHexDigits(int value)
      返回int值的八个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。不使用分隔符、前缀和后缀。
      参数:
      value - 一个int
      返回:
      int值的八个十六进制字符
      参见:
    • toHexDigits

      public String toHexDigits(long value)
      返回long值的十六个十六进制字符。从值的最高有效位到最低有效位,每个半字节(4位)都会被格式化,就好像通过toLowHexDigit(nibble)进行格式化一样。不使用分隔符、前缀和后缀。
      参数:
      value - 一个long
      返回:
      long值的十六个十六进制字符
      参见:
    • toHexDigits

      public String toHexDigits(long value, int digits)
      返回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

      public static int fromHexDigits(CharSequence string)
      从包含最多八个十六进制字符的字符串中解析出int值。使用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
      返回:
      从字符串解析出的值
      抛出:
      IllegalArgumentException - 如果字符串长度大于八(8)或任何字符不是十六进制字符
    • fromHexDigits

      public static int fromHexDigits(CharSequence string, int fromIndex, int toIndex)
      从包含最多八个十六进制字符的字符串范围中解析出int值。从范围fromIndextoIndex(不包括)的字符将从最高有效位到最低有效位使用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

      public static long fromHexDigitsToLong(CharSequence string)
      从包含最多十六个十六进制字符的字符串中解析出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

      public static long fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex)
      从包含最多十六个十六进制字符的字符串范围中解析出long值。从范围fromIndextoIndex(不包括)的字符将从最高有效位到最低有效位使用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

      public boolean equals(Object o)
      如果另一个对象是具有相同参数的HexFormat,则返回true
      覆盖:
      equals 在类 Object
      参数:
      o - 一个对象,可以为null
      返回值:
      如果另一个对象是HexFormat且参数uppercase、delimiter、prefix和suffix相等,则返回true;否则返回false
      参见:
    • hashCode

      public int hashCode()
      返回此HexFormat的哈希码。
      覆盖:
      hashCode 在类 Object
      返回值:
      HexFormat的哈希码
      参见:
    • toString

      public String toString()
      返回大写、分隔符、前缀和后缀的格式化参数的描述。
      覆盖:
      toString 在类 Object
      返回值:
      HexFormat的描述