Класс 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", and "A-F" преобразуются в соответствующие значения 0-15. Разделитель, префикс, суффикс и параметр верхнего регистра не используются.
Для преобразования массивов байтов в форматированные шестнадцатеричные строки методы formatHex включают formatHex(byte[]) и formatHex(Appendable, byte[]). Отформатированный вывод — это строка или она добавляется к Appendable, например, StringBuilder или PrintStream. Каждое значение байта форматируется как префикс, две шестнадцатеричные цифры из цифр верхнего или нижнего регистра и суффикс. Разделитель следует за каждым отформатированным значением, кроме последнего. Для преобразований, производящих шестнадцатеричные строки в верхнем регистре, используйте withUpperCase().
Для преобразования форматированных шестнадцатеричных строк в массивы байтов методы parseHex включают parseHex(CharSequence) и parseHex(char[], offset, length). Каждое значение байта анализируется по префиксу, двум нечувствительным к регистру шестнадцатеричным символам и суффиксу. Разделитель следует за каждым отформатированным значением, кроме последнего.
- API Note:
- Например, отдельный байт преобразуется в строку шестнадцатеричных цифр с помощью
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); // The hexadecimal digits are: "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)); // The formatted string is: "#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)); // The formatted string is: "00:01:02:03:7C:7D:7E:7F"Это класс значений; использование операций, чувствительных к идентификатору (включая равенство ссылок (
==), хэш-код по идентификатору или синхронизацию) на экземплярахHexFormatможет привести к непредсказуемым результатам и следует избегать. Для сравнений следует использовать методequals.Этот класс неизменяемый и потокобезопасный.
Если не указано иное, передача null-аргумента в любой метод вызовет исключение
NullPointerException. - Since:
- 17
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
String |
delimiter() |
Возвращает разделитель между шестнадцатеричными значениями в отформатированных шестнадцатеричных строках. |
boolean |
equals |
Возвращает true, если другой объект является HexFormat с теми же параметрами. |
String |
formatHex |
Возвращает отформатированную шестнадцатеричную строку из массива байтов. |
String |
formatHex |
Возвращает отформатированную шестнадцатеричную строку из диапазона массива байтов. |
<A extends Appendable> |
formatHex |
Добавляет отформатированные шестнадцатеричные строки из массива байтов в Appendable. |
<A extends Appendable> |
formatHex |
Добавляет отформатированные шестнадцатеричные строки из диапазона массива байтов в Appendable. |
static int |
fromHexDigit |
Возвращает значение шестнадцатеричного символа или кода. |
static int |
fromHexDigits |
Возвращает значение int , разобранное из строки до восьми шестнадцатеричных символов. |
static int |
fromHexDigits |
Возвращает значение int , разобранное из диапазона строки до восьми шестнадцатеричных символов. |
static long |
fromHexDigitsToLong |
Возвращает значение типа long, разобранное из строки до шестнадцати шестнадцатеричных символов. |
static long |
fromHexDigitsToLong |
Возвращает значение типа long, разобранное из диапазона строки до шестнадцати шестнадцатеричных символов. |
int |
hashCode() |
Возвращает хэш-код для этого HexFormat. |
static boolean |
isHexDigit |
Возвращает true, если символ является допустимым шестнадцатеричным символом или кодом. |
boolean |
isUpperCase() |
Возвращает true, если шестнадцатеричные цифры заглавные, в противном случае false. |
static HexFormat |
of() |
Возвращает шестнадцатеричный форматер без разделителя и строчных символов. |
static HexFormat |
ofDelimiter |
Возвращает шестнадцатеричный форматер с разделителем и строчными символами. |
byte[] |
parseHex |
Возвращает массив байтов, содержащий шестнадцатеричные значения, разобранные из диапазона массива символов. |
byte[] |
parseHex |
Возвращает массив байтов, содержащий шестнадцатеричные значения, разобранные из строки. |
byte[] |
parseHex |
Возвращает массив байтов, содержащий шестнадцатеричные значения, разобранные из диапазона строки. |
String |
prefix() |
Возвращает префикс, используемый для каждого шестнадцатеричного значения в отформатированных шестнадцатеричных строках. |
String |
suffix() |
Возвращает суффикс, используемый для каждого шестнадцатеричного значения в отформатированных шестнадцатеричных строках. |
String |
toHexDigits |
Возвращает две шестнадцатеричные цифры для значения byte. |
String |
toHexDigits |
Возвращает четыре шестнадцатеричные цифры для значения char. |
String |
toHexDigits |
Возвращает восемь шестнадцатеричных цифр для значения int. |
String |
toHexDigits |
Возвращает шестнадцать шестнадцатеричных цифр для значения long. |
String |
toHexDigits |
Возвращает до шестнадцати шестнадцатеричных цифр для значения long. |
String |
toHexDigits |
Возвращает четыре шестнадцатеричные цифры для значения short. |
<A extends Appendable> |
toHexDigits |
Добавляет две шестнадцатеричные цифры для значения байта в Appendable. |
char |
toHighHexDigit |
Возвращает шестнадцатеричный символ для старших 4 бит значения, рассматривая его как байт. |
char |
toLowHexDigit |
Возвращает шестнадцатеричный символ для младших 4 бит значения, рассматривая его как байт. |
String |
toString() |
Возвращает описание параметров форматера для заглавных букв, разделителя, префикса и суффикса. |
HexFormat |
withDelimiter |
Возвращает копию этого HexFormat с разделителем. |
HexFormat |
withLowerCase() |
Возвращает копию этого HexFormat для использования строчных шестнадцатеричных символов. |
HexFormat |
withPrefix |
Возвращает копию этого HexFormat с префиксом. |
HexFormat |
withSuffix |
Возвращает копию этого HexFormat с суффиксом. |
HexFormat |
withUpperCase() |
Возвращает копию этого HexFormat для использования заглавных шестнадцатеричных символов. |
Подробности методов
of
public static HexFormat of()
withDelimiter, withUpperCase, withLowerCase, withPrefix и withSuffix возвращают копии форматтеров с новыми параметрами.- Возвращает:
- шестнадцатеричный форматтер без разделителя и с маленькими буквами
ofDelimiter
public static HexFormat ofDelimiter(String delimiter)
withDelimiter, withUpperCase, withLowerCase, withPrefix и withSuffix возвращают копии форматтеров с новыми параметрами.- Параметры:
-
delimiter- разделитель, не null, может быть пустым - Возвращает:
- шестнадцатеричный форматтер с разделителем и маленькими буквами
withDelimiter
public HexFormat withDelimiter(String delimiter)
HexFormat с разделителем.- Параметры:
-
delimiter- разделитель, не null, может быть пустым - Возвращает:
- копию этого
HexFormatс разделителем
withPrefix
public HexFormat withPrefix(String prefix)
HexFormat с префиксом.- Параметры:
-
prefix- префикс, не null, может быть пустым - Возвращает:
- копию этого
HexFormatс префиксом
withSuffix
public HexFormat withSuffix(String suffix)
HexFormat с суффиксом.- Параметры:
-
suffix- суффикс, не null, может быть пустым - Возвращает:
- копию этого
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()
- Возвращает:
- разделитель, не null, может быть пустым
""
prefix
public String prefix()
- Возвращает:
- префикс, не null, может быть пустым
""
suffix
public String suffix()
- Возвращает:
- суффикс, не null, может быть пустым
""
isUpperCase
public boolean isUpperCase()
true , если шестнадцатеричные цифры заглавные, иначе false.- Возвращает:
-
trueесли шестнадцатеричные цифры заглавные, иначеfalse
formatHex
public String formatHex(byte[] bytes)
formatHex(bytes, 0, bytes.length)).- Параметры:
-
bytes- массив байтов, не null - Возвращает:
- шестнадцатеричная строка, форматирующая массив байтов
formatHex
public String formatHex(byte[] bytes, int fromIndex, int toIndex)
- Параметры:
-
bytes- массив байтов, не null -
fromIndex- начальный индекс диапазона, включительно -
toIndex- конечный индекс диапазона, исключая - Возвращает:
- строка, форматирующая каждый байт диапазона массива
- Исключения:
-
IndexOutOfBoundsException- если диапазон массива выходит за пределы
formatHex
public <A extends Appendable> A formatHex(A out, byte[] bytes)
Appendable. Каждое значение байта форматируется как префикс, две шестнадцатеричные цифры выбранные из заглавных или строчных цифр и суффикс. Разделитель следует за каждым отформатированным значением, кроме последнего. Отформатированные шестнадцатеричные строки добавляются в нуле или более вызовах методов Appendable.- Параметры типа:
-
A- ТипAppendable - Параметры:
-
out- объектAppendable, не null -
bytes- массив байтов - Возвращает:
- объект
Appendable - Исключения:
-
UncheckedIOException- если произошла ошибка ввода-вывода при добавлении в выходные данные
formatHex
public <A extends Appendable> A formatHex(A out, byte[] bytes, int fromIndex, int toIndex)
Appendable. Каждое значение байта форматируется как префикс, две шестнадцатеричные цифры выбранные из заглавных или строчных цифр и суффикс. Разделитель следует за каждым отформатированным значением, кроме последнего. Отформатированные шестнадцатеричные строки добавляются в нуле или более вызовах методов Appendable.- Параметры типа:
-
A- ТипAppendable - Параметры:
-
out- объектAppendable, не null -
bytes- массив байтов, не null -
fromIndex- начальный индекс диапазона, включительно -
toIndex- конечный индекс диапазона, исключая. - Возвращает:
- объект
Appendable - Исключения:
-
IndexOutOfBoundsException- если диапазон массива выходит за пределы -
UncheckedIOException- если произошла ошибка ввода-вывода при добавлении в выходные данные
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)
- Parameters:
-
chars- диапазон символьного массива, содержащий чётное число шестнадцатеричных цифр, разделителей, префикса и суффикса. -
fromIndex- начальный индекс диапазона, включительно -
toIndex- конечный индекс диапазона, исключая - Returns:
- массив байтов со значениями, извлечёнными из диапазона символьного массива
- Throws:
-
IllegalArgumentException- если префикс или суффикс отсутствуют для каждого значения байта, значения байтов не являются шестнадцатеричными символами, или если разделитель отсутствует после всех, кроме последнего значения байта -
IndexOutOfBoundsException- если диапазон символьного массива выходит за пределы
toLowHexDigit
public char toLowHexDigit(int value)
isUpperCase() равен true, возвращаемый символ для значений 10-15 будет заглавным "A-F", в противном случае возвращаемый символ будет строчным "a-f". Значения в диапазоне 0-9 возвращаются как "0-9".- Parameters:
-
value- значение; используются только младшие 4 бита0-3значения - Returns:
- шестнадцатеричный символ для младших 4 битов
0-3значения
toHighHexDigit
public char toHighHexDigit(int value)
isUpperCase() равен true, возвращаемый символ для значений 10-15 будет заглавным "A-F", в противном случае возвращаемый символ будет строчным "a-f". Значения в диапазоне 0-9 возвращаются как "0-9".- Parameters:
-
value- значение; используются только биты4-7значения - Returns:
- шестнадцатеричный символ для битов
4-7значения
toHexDigits
public <A extends Appendable> A toHexDigits(A out, byte value)
Appendable. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Шестнадцатеричные символы добавляются в одном или нескольких вызовах методов Appendable. Разделитель, префикс и суффикс не используются.- Type Parameters:
-
A- ТипAppendable - Parameters:
-
out-Appendable, не null -
value- значение байта - Returns:
Appendable- Throws:
-
UncheckedIOException- если при добавлении в вывод возникает исключение I/O
toHexDigits
public String toHexDigits(byte value)
byte значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значение байта - Returns:
- два шестнадцатеричных символа для значения байта
toHexDigits
public String toHexDigits(char value)
char значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значениеchar - Returns:
- четыре шестнадцатеричных символа для
charзначения
toHexDigits
public String toHexDigits(short value)
short значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значениеshort - Returns:
- четыре шестнадцатеричных символа для
shortзначения
toHexDigits
public String toHexDigits(int value)
int значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значениеint - Returns:
- восемь шестнадцатеричных символов для
intзначения - See Also:
toHexDigits
public String toHexDigits(long value)
long значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значениеlong - Returns:
- шестнадцать шестнадцатеричных символов для
longзначения - See Also:
toHexDigits
public String toHexDigits(long value, int digits)
long значения. Каждый бит (4 бита) от старшего к младшему из значения форматируется так же, как и в toLowHexDigit(nibble). Разделитель, префикс и суффикс не используются.- Parameters:
-
value- значениеlong -
digits- количество шестнадцатеричных цифр для возврата, от 0 до 16 - Returns:
- шестнадцатеричные символы для
longзначения - Throws:
-
IllegalArgumentException- еслиdigitsотрицательное или больше 16
isHexDigit
public static boolean isHexDigit(int ch)
true, если символ является допустимым шестнадцатеричным символом или кодовым значением. Допустимые шестнадцатеричные символы: -
'0' ('\u0030')по'9' ('\u0039')включительно, -
'A' ('\u0041')по'F' ('\u0046')включительно, и -
'a' ('\u0061')по'f' ('\u0066')включительно.
- Parameters:
-
ch- кодовое значение - Returns:
-
trueесли символ является допустимым шестнадцатеричным символом, в противном случаеfalse
fromHexDigit
public static int fromHexDigit(int ch)
-
(ch - '0')для'0'по'9'включительно, -
(ch - 'A' + 10)для'A'по'F'включительно, и -
(ch - 'a' + 10)для'a'по'f'включительно.
- Parameters:
-
ch- символ или кодовое значение - Returns:
- значение
0-15 - Throws:
-
NumberFormatException- если кодовое значение не является шестнадцатеричным символом
fromHexDigits
public static int fromHexDigits(CharSequence string)
int значение, извлечённое из строки до восьми шестнадцатеричных символов. Шестнадцатеричные символы извлекаются от старшего к младшему с помощью fromHexDigit(int) для формирования беззнакового значения. Значение расширяется до 32 бит и возвращается как int.- API Note:
-
Integer.parseInt(s, 16)иInteger.parseUnsignedInt(s, 16)аналогичны, но допускают все шестнадцатеричные цифры Unicode, определённыеCharacter.digit(ch, 16).HexFormatиспользует только шестнадцатеричные символы"0-9","A-F"и"a-f". Знаковые шестнадцатеричные строки можно анализировать с помощьюInteger.parseInt(String, int). - Parameters:
-
string- CharSequence, содержащая до восьми шестнадцатеричных символов - Returns:
- значение, извлечённое из строки
- Throws:
-
IllegalArgumentException- если длина строки больше восьми (8) или любой из символов не является шестнадцатеричным символом
fromHexDigits
public static int fromHexDigits(CharSequence string, int fromIndex, int toIndex)
int из диапазона строк до восьми шестнадцатеричных символов. Символы в диапазоне fromIndex до toIndex, исключая границы, преобразуются от старшего к младшему с использованием fromHexDigit(int) для формирования беззнакового значения. Значение расширяется до 32 бит с нулями и возвращается как int.- API Note:
-
Integer.parseInt(s, 16)иInteger.parseUnsignedInt(s, 16)аналогичны, но позволяют использовать все Unicode шестнадцатеричные цифры, определённые вCharacter.digit(ch, 16).HexFormatиспользует только шестнадцатеричные символы"0-9","A-F"и"a-f". Для парсинга знаковых шестнадцатеричных строк можно использоватьInteger.parseInt(String, int). - Parameters:
-
string- a CharSequence, содержащий символы -
fromIndex- начальный индекс диапазона (включительно) -
toIndex- конечный индекс диапазона (исключительно). - Returns:
- значение, преобразованное из диапазона строки
- Throws:
-
IndexOutOfBoundsException- если диапазон выходит за пределы допустимого дляCharSequence -
IllegalArgumentException- если длина диапазона больше восьми (8) или любой из символов не является шестнадцатеричным символом
fromHexDigitsToLong
public static long fromHexDigitsToLong(CharSequence string)
fromHexDigit(int) для формирования беззнакового значения. Значение расширяется до 64 бит с нулями и возвращается как long.- API Note:
-
Long.parseLong(s, 16)иLong.parseUnsignedLong(s, 16)аналогичны, но позволяют использовать все Unicode шестнадцатеричные цифры, определённые вCharacter.digit(ch, 16).HexFormatиспользует только шестнадцатеричные символы"0-9","A-F"и"a-f". Для парсинга знаковых шестнадцатеричных строк можно использоватьLong.parseLong(String, int). - Parameters:
-
string- a CharSequence, содержащая до шестнадцати шестнадцатеричных символов - Returns:
- значение, преобразованное из строки
- Throws:
-
IllegalArgumentException- если длина строки больше шестнадцати (16) или любой из символов не является шестнадцатеричным символом
fromHexDigitsToLong
public static long fromHexDigitsToLong(CharSequence string, int fromIndex, int toIndex)
fromIndex до toIndex, исключая границы, преобразуются от старшего к младшему с использованием fromHexDigit(int) для формирования беззнакового значения. Значение расширяется до 64 бит с нулями и возвращается как long.- API Note:
-
Long.parseLong(s, 16)иLong.parseUnsignedLong(s, 16)аналогичны, но позволяют использовать все Unicode шестнадцатеричные цифры, определённые вCharacter.digit(ch, 16).HexFormatиспользует только шестнадцатеричные символы"0-9","A-F"и"a-f". Для парсинга знаковых шестнадцатеричных строк можно использоватьLong.parseLong(String, int). - Parameters:
-
string- a CharSequence, содержащий символы -
fromIndex- начальный индекс диапазона (включительно) -
toIndex- конечный индекс диапазона (исключительно). - Returns:
- значение, преобразованное из диапазона строки
- Throws:
-
IndexOutOfBoundsException- если диапазон выходит за пределы допустимого дляCharSequence -
IllegalArgumentException- если длина диапазона больше шестнадцати (16) или любой из символов не является шестнадцатеричным символом
equals
public boolean equals(Object o)
true , если другой объект является HexFormat с теми же параметрами.- Overrides:
-
equalsв классеObject - Parameters:
-
o- объект, может быть null - Returns:
-
trueесли другой объект являетсяHexFormatи параметры uppercase, delimiter, prefix, и suffix равны; иначеfalse - See Also:
hashCode
public int hashCode()
HexFormat.- Overrides:
-
hashCodeв классеObject - Returns:
- хэш-код для данного
HexFormat - See Also:
toString
public String toString()
- Overrides:
-
toStringв классеObject - Returns:
- описание этого
HexFormat
© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/HexFormat.html