NumberHexFormat

Начиная с Kotlin: 2.2

class NumberHexFormat

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

Эти параметры используются такими функциями, как Int.toHexString для форматирования и String.hexToInt для разбора. Функции форматирования и разбора доступны для всех целочисленных типов.

При форматировании результат состоит из строки prefix, шестнадцатеричного представления числового значения и строки suffix. Шестнадцатеричное представление значения вычисляется путем сопоставления каждой четырехбитной группы его двоичного представления соответствующей шестнадцатеричной цифре, начиная со старших битов. Параметр upperCase определяет регистр (A-F или a-f) шестнадцатеричных цифр. Если removeLeadingZeros равен true и длина шестнадцатеричного представления превышает minLength, начальные нули удаляются, пока длина не станет равна minLength. Однако, если значение minLength превышает длину шестнадцатеричного представления, параметр removeLeadingZeros игнорируется, а в начало представления добавляются нули, чтобы его длина соответствовала заданному значению minLength.

Например, двоичное представление значения Int 58 (длиной 32 бита 00000000000000000000000000111010) преобразуется в шестнадцатеричное представление 0000003a или 0000003A в зависимости от параметра upperCase. Если для removeLeadingZeros задано значение true, представление сокращается до 3a. Однако, если для minLength задано значение 6, удаление начальных нулей прекращается, когда длина сокращается до 00003a. Если задать для minLength значение 12, получится 00000000003a: параметр removeLeadingZeros игнорируется из-за требования к минимальной длине.

Чтобы отформатировать значение в шестнадцатеричную строку заданной длины, сначала преобразуйте значение в тип с подходящим размером в битах. Например, чтобы отформатировать значение типа Int в виде четырехзначной шестнадцатеричной строки, преобразуйте его с помощью toShort() перед шестнадцатеричным форматированием. Чтобы получить не более четырех цифр без начальных нулей, дополнительно задайте для removeLeadingZeros значение true.

При разборе входная строка должна начинаться с prefix и заканчиваться suffix. Между ними должна находиться хотя бы одна шестнадцатеричная цифра. Если количество шестнадцатеричных цифр превышает емкость разбираемого типа с учетом его размера в битах, все лишние цифры в начале должны быть нулями. Разбор prefix, suffix и шестнадцатеричных цифр выполняется без учета регистра. При разборе параметры removeLeadingZeros и minLength игнорируются.

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

Примеры

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
}