BytesHexFormat

Версия Kotlin: 2.2

class BytesHexFormat

Представляет параметры шестнадцатеричного формата для форматирования и разбора массивов байтов.

Эти параметры используются функциями ByteArray.toHexString и String.hexToByteArray соответственно для форматирования и разбора. Функции форматирования и разбора также доступны для UByteArray.

При форматировании массива байтов можно считать, что выполняются следующие шаги:

1. Байты разбиваются на строки по bytesPerLine байтов в каждой, за исключением последней строки, в которой байтов может быть меньше.

2. Каждая строка разбивается на группы по bytesPerGroup байтов в каждой, за исключением последней группы в строке, в которой байтов может быть меньше.

3. Все байты преобразуются в двухзначное шестнадцатеричное представление; перед каждым добавляется bytePrefix, а после него — byteSuffix.

4. Соседние отформатированные байты в каждой группе разделяются строкой byteSeparator.

5. Соседние группы в каждой строке разделяются строкой groupSeparator.

6. Соседние строки разделяются символом перевода строки (LF) '\n'.

Например, рассмотрим приведённый ниже фрагмент:

val byteArray = byteArrayOf(0, 1, 2, 3, 4, 5, 6, 7)
val format = HexFormat {
    bytes {
        bytesPerLine = 6
        bytesPerGroup = 4
        groupSeparator = "|" // vertical bar
        byteSeparator = " " // one space
        bytePrefix = "0x"
        byteSuffix = "" // empty string
    }
}

println(byteArray.toHexString(format))

Для byteArray и format форматирование выполняется следующим образом:

1. 8 байтов разбиваются на строки по 6 байтов. Первая строка содержит 0, 1, 2, 3, 4, 5, а вторая (и последняя) строка содержит 6, 7.

2. Затем каждая строка разбивается на группы по 4 байта. В первой строке образуются две группы: 0, 1, 2, 3 и 4, 5; во второй строке образуется одна группа: 6, 7.

3. Каждый байт преобразуется в шестнадцатеричное представление, перед которым добавляется "0x", а после которого — пустая строка.

4. Байты в каждой группе разделяются одним пробелом " ".

5. Группы в каждой строке разделяются символом вертикальной черты "|".

6. Строки разделяются символом LF '\n'.

Вызов byteArray.toHexString(format) вернёт "0x00 0x01 0x02 0x03|0x04 0x05\n0x06 0x07", а его вывод в консоль будет таким:

0x00 0x01 0x02 0x03|0x04 0x05
0x06 0x07

При разборе входная строка должна соответствовать формату, заданному этими параметрами. Однако разбор выполняется с некоторой гибкостью: в качестве разделителя строк допускается любая из последовательностей символов CRLF, LF или CR. Кроме того, разбор groupSeparator, byteSeparator, bytePrefix, byteSuffix и шестнадцатеричных цифр выполняется без учёта регистра.

Этот класс неизменяем и не может быть создан или настроен напрямую. Чтобы создать новый формат, используйте функцию-конструктор HexFormat { } и задайте параметры свойства bytes в фигурных скобках. Например, используйте val format = HexFormat { bytes.bytesPerLine = 16 }, чтобы задать bytesPerLine. Свойство bytes имеет тип BytesHexFormat.Builder; его параметры можно настроить, и они соответствуют параметрам этого класса.