BytesHexFormat

Represents hexadecimal format options for formatting and parsing byte arrays.

These options are utilized by ByteArray.toHexString and String.hexToByteArray functions for formatting and parsing, respectively. The formatting and parsing functions are available for UByteArray as well.

When formatting a byte array, one can assume the following steps:

1. The bytes are split into lines with bytesPerLine bytes in each line, except for the last line, which may have fewer bytes.
2. Each line is split into groups with bytesPerGroup bytes in each group, except for the last group in a line, which may have fewer bytes.
3. All bytes are converted to their two-digit hexadecimal representation, each prefixed by bytePrefix and suffixed by byteSuffix.
4. Adjacent formatted bytes within each group are separated by byteSeparator.
5. Adjacent groups within each line are separated by groupSeparator.
6. Adjacent lines are separated by the line feed (LF) character '\n'.

For example, consider the snippet below:

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))

Given the byteArray and format, the formatting proceeds as follows:

1. The 8 bytes are split into lines of 6 bytes each. The first line contains 0, 1, 2, 3, 4, 5, and the second (and last) line contains 6, 7.
2. Each line is then divided into groups of 4 bytes. The first line forms two groups: 0, 1, 2, 3 and 4, 5; the second line forms one group: 6, 7.
3. Each byte is converted to its hexadecimal representation, prefixed by "0x" and suffixed by an empty string.
4. Bytes within each group are separated by a single space " ".
5. Groups within each line are separated by a vertical bar character "|".
6. Lines are separated by the LF character '\n'.

The byteArray.toHexString(format) call will result in "0x00 0x01 0x02 0x03|0x04 0x05\n0x06 0x07", and printing it to the console outputs:

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

When parsing, the input string must conform to the format specified by these options. However, parsing is somewhat lenient, allowing any of the char sequences CRLF, LF, or CR to be used as the line separator. Additionally, parsing of groupSeparator, byteSeparator, bytePrefix, byteSuffix, and the hexadecimal digits is performed in a case-insensitive manner.

This class is immutable and cannot be created or configured directly. To create a new format, use the HexFormat { } builder function and configure the options of the bytes property inside the braces. For example, use val format = HexFormat { bytes.bytesPerLine = 16 } to set the bytesPerLine. The bytes property is of type BytesHexFormat.Builder, whose options are configurable and correspond to the options of this class.