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.

Since Kotlin

1.9

Types

Link copied to clipboard
class Builder

Provides an API for building a BytesHexFormat.

Since Kotlin 1.9

Properties

Link copied to clipboard

The string that immediately precedes the two-digit hexadecimal representation of each byte.

Since Kotlin 1.9
Link copied to clipboard

The string used to separate adjacent bytes within a group.

Since Kotlin 1.9
Link copied to clipboard

The maximum number of bytes per group in a line, Int.MAX_VALUE by default.

Since Kotlin 1.9
Link copied to clipboard

The maximum number of bytes per line, Int.MAX_VALUE by default.

Since Kotlin 1.9
Link copied to clipboard

The string that immediately follows the two-digit hexadecimal representation of each byte.

Since Kotlin 1.9
Link copied to clipboard

The string used to separate adjacent groups in a line, two space characters (" ") by default.

Since Kotlin 1.9

Functions

Link copied to clipboard
open override fun toString(): String
Since Kotlin 1.9