NumberHexFormat

Represents hexadecimal format options for formatting and parsing numeric values.

These options are utilized by functions like Int.toHexString for formatting and String.hexToInt for parsing. The formatting and parsing functions are available for all integer numeric types.

When formatting, the result consists of a prefix string, the hexadecimal representation of the numeric value, and a suffix string. The hexadecimal representation of a value is calculated by mapping each four-bit chunk of its binary representation to the corresponding hexadecimal digit, starting with the most significant bits. The upperCase option determines the case (A-F or a-f) of the hexadecimal digits. If removeLeadingZeros is true and the hexadecimal representation is longer than minLength, leading zeros are removed until the length matches minLength. However, if minLength exceeds the length of the hexadecimal representation, removeLeadingZeros is ignored, and zeros are added to the start of the representation to achieve the specified minLength.

For example, the binary representation of the Int value 58 (32-bit long 00000000000000000000000000111010) converts to the hexadecimal representation 0000003a or 0000003A, depending on upperCase. With removeLeadingZeros set to true, it shortens to 3a. However, if minLength is set to 6, the removal of leading zeros stops once the length is reduced to 00003a. Setting minLength to 12 results in 00000000003a, where the removeLeadingZeros option is ignored due to the minimum length requirement.

To format a value into a hexadecimal string of a particular length, start by converting the value to a type with the suitable bit size. For instance, to format an Int value into a 4-digit hexadecimal string, convert the value using toShort() before hexadecimal formatting. To obtain a maximum of 4 digits without leading zeros, additionally set removeLeadingZeros to true.

When parsing, the input string must start with the prefix and end with the suffix. It must contain at least one hexadecimal digit between them. If the number of hexadecimal digits exceeds the capacity of the type being parsed, based on its bit size, the excess leading digits must be zeros. Parsing of the prefix, suffix, and hexadecimal digits is performed in a case-insensitive manner. The removeLeadingZeros and minLength options are ignored during parsing.

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 number property inside the braces. For example, use val format = HexFormat { number.prefix = "0x" } to set the prefix. The number property is of type NumberHexFormat.Builder, whose options are configurable and correspond to the options of this class.

Samples

import kotlin.test.*

fun main() { 
   //sampleStart 
   val numberHexFormat = HexFormat {
    upperCase = true
    number {
        removeLeadingZeros = true
        minLength = 4
        prefix = "0x"
    }
}

println(0x3a.toHexString(numberHexFormat)) // 0x003A
println("0x003A".hexToInt(numberHexFormat)) // 58
// Parsing is case-insensitive
println("0X003a".hexToInt(numberHexFormat)) // 58 
   //sampleEnd
}