HexFormat

Represents hexadecimal format options for formatting and parsing byte arrays and integer numeric values, both signed and unsigned.

An instance of this class is passed to formatting and parsing functions and specifies how formatting and parsing should be conducted. The options of the bytes property apply only when formatting and parsing byte arrays, while the number property applies when formatting and parsing numeric values. The upperCase option affects both.

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 inside the braces. For example, use val format = HexFormat { upperCase = true } to enable upper-case formatting.

Two predefined instances are provided by this class's companion object: Default and UpperCase. The Default instance has the upperCase option set to false, and the options of bytes and number properties set to their default values as specified in BytesHexFormat and NumberHexFormat, respectively. The UpperCase instance has the upperCase option set to true, and the options of bytes and number properties set to their default values.

Since Kotlin

1.9

Samples

import kotlin.test.*

fun main() { 
   //sampleStart 
   // Specifying format options for numeric values.
println(58.toHexString(HexFormat { number.removeLeadingZeros = true })) // 3a
println("0x3a".hexToInt(HexFormat { number.prefix = "0x" })) // 58

// Specifying format options for byte arrays.
val macAddressFormat = HexFormat {
    upperCase = true
    bytes {
        bytesPerGroup = 2
        groupSeparator = "."
    }
}
val macAddressBytes = byteArrayOf(0x00, 0x1b, 0x63, 0x84.toByte(), 0x45, 0xe6.toByte())
println(macAddressBytes.toHexString(macAddressFormat)) // 001B.6384.45E6
println("\"001B.6384.45E6\".hexToByteArray(macAddressFormat).contentEquals(macAddressBytes) is ${"001B.6384.45E6".hexToByteArray(macAddressFormat).contentEquals(macAddressBytes)}") // true

// Creating a format that defines options for both byte arrays and numeric values.
val customHexFormat = HexFormat {
    upperCase = true
    number {
        removeLeadingZeros = true
        prefix = "0x"
    }
    bytes {
        bytesPerGroup = 2
        groupSeparator = "."
    }
}
// Formatting numeric values utilizes the `upperCase` and `number` options.
println(58.toHexString(customHexFormat)) // 0x3A
// Formatting byte arrays utilizes the `upperCase` and `bytes` options.
println(macAddressBytes.toHexString(customHexFormat)) // 001B.6384.45E6 
   //sampleEnd
}
xxxxxxxxxx
 
// Specifying format options for numeric values.
println(58.toHexString(HexFormat { number.removeLeadingZeros = true })) // 3a
println("0x3a".hexToInt(HexFormat { number.prefix = "0x" })) // 58
// Specifying format options for byte arrays.
val macAddressFormat = HexFormat {
    upperCase = true
    bytes {
        bytesPerGroup = 2
        groupSeparator = "."
    }
}
val macAddressBytes = byteArrayOf(0x00, 0x1b, 0x63, 0x84.toByte(), 0x45, 0xe6.toByte())
println(macAddressBytes.toHexString(macAddressFormat)) // 001B.6384.45E6
println("\"001B.6384.45E6\".hexToByteArray(macAddressFormat).contentEquals(macAddressBytes) is ${"001B.6384.45E6".hexToByteArray(macAddressFormat).contentEquals(macAddressBytes)}") // true
// Creating a format that defines options for both byte arrays and numeric values.
val customHexFormat = HexFormat {
    upperCase = true
    number {
        removeLeadingZeros = true
        prefix = "0x"
    }
    bytes {
        bytesPerGroup = 2
        groupSeparator = "."
    }
}
// Formatting numeric values utilizes the `upperCase` and `number` options.
println(58.toHexString(customHexFormat)) // 0x3A
// Formatting byte arrays utilizes the `upperCase` and `bytes` options.
println(macAddressBytes.toHexString(customHexFormat)) // 001B.6384.45E6 
Open in Playground →
Target: JVMRunning on v.2.1.20