UUID

Генерация UUID

Чтобы сгенерировать случайный UUID версии 4 для обычных идентификаторов, например идентификаторов пользователей или баз данных, используйте функцию Uuid.random():

import kotlin.uuid.Uuid

fun main() {
//sampleStart    
    val id = Uuid.random()
    println(id)
//sampleEnd    
}

Вы также можете генерировать UUID определённых версий с помощью следующих функций со статусом «Экспериментальная»:

• Функция Uuid.generateV4() генерирует UUID того же типа, что и функция Uuid.random(), но явно указывает, что это UUID версии 4.

• Функция Uuid.generateV7() генерирует UUID версии 7 с временной меткой, которую можно использовать для сортировки UUID.

• Функция Uuid.generateV7NonMonotonicAt() генерирует UUID версии 7 для указанного момента времени.

Эти функции генерации UUID имеют статус «Экспериментальные». Чтобы начать их использовать, примените аннотацию @OptIn(ExperimentalUuidApi::class) или добавьте следующий параметр компилятора в файл сборки:

kotlin {
    compilerOptions {
        freeCompilerArgs.add("-opt-in=kotlin.uuid.ExperimentalUuidApi")
    }
}

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <configuration>
                <args>
                    <arg>-opt-in=kotlin.uuid.ExperimentalUuidApi</arg>
                </args>
            </configuration>
        </plugin>
    </plugins>
</build>

Вот пример генерации UUID разных версий:

import kotlin.time.Instant
import kotlin.time.ExperimentalTime
import kotlin.uuid.Uuid

@OptIn(kotlin.uuid.ExperimentalUuidApi::class, ExperimentalTime::class)
fun main() {
    // Generates a version 4 UUID
    val idVersion4 = Uuid.generateV4()
    println(idVersion4)

    // Generates a version 7 UUID
    val idVersion7 = Uuid.generateV7()
    println(idVersion7)

    // Generates a version 7 UUID for the specified timestamp
    val timestamp = Instant.fromEpochMilliseconds(1757440583000L)
    val idVersion7SpecificTime = Uuid.generateV7NonMonotonicAt(timestamp)
    println(idVersion7SpecificTime)
}

Разбор UUID

Значения UUID часто представлены в виде строк, например в параметрах URL или записях базы данных.

Чтобы преобразовать значение String в значение Uuid, используйте функцию Uuid.parse():

import kotlin.uuid.Uuid

fun main() {
//sampleStart
    val id = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a")
    println(id)
//sampleEnd    
}

Функция Uuid.parse() принимает как стандартный формат с шестнадцатеричными символами и дефисами, так и шестнадцатеричный формат без дефисов.

Если входные данные недопустимы, функция Uuid.parse() выбрасывает исключение IllegalArgumentException:

import kotlin.uuid.Uuid

fun main() { 
//sampleStart    
    val id = Uuid.parse("10")
    println(id)
//sampleEnd    
}

Если приложение принимает только одно представление, используйте функции для конкретного формата:

• Uuid.parseHexDash() — для строкового представления с шестнадцатеричными символами и дефисами.

• Uuid.parseHex() — для шестнадцатеричного строкового представления без дефисов.

Например:

import kotlin.uuid.Uuid

fun main() {
//sampleStart  
    val standard = Uuid.parseHexDash("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a")
    val compact = Uuid.parseHex("de2bc56cea734f3c8a375a46fdb2d79a")
    
    println(standard)
    println(compact)
//sampleEnd    
}

Если вы получаете UUID из внешних источников и должны безопасно обрабатывать недопустимые входные данные, используйте Uuid.parseOrNull(), Uuid.parseHexDashOrNull() или Uuid.parseHexOrNull(). Если входные данные недопустимы, эти функции возвращают null:

fun parseId(input: String): Uuid? { 
    return Uuid.parseOrNull(input) 
}

Преобразование UUID в строки

Преобразовать значение Uuid в значение String можно с помощью следующих функций:

• toString() — для стандартного строкового представления

• toHexDashString() — для формата с шестнадцатеричными символами и дефисами

• toHexString() — для шестнадцатеричного формата без дефисов

Например:

import kotlin.uuid.Uuid

fun main() {
//sampleStart    
    val id = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a")
    
    println(id.toString())
    // de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a
    println(id.toHexDashString())
    // de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a
    println(id.toHexString())
    // de2bc56cea734f3c8a375a46fdb2d79a 
//sampleEnd    
}

Сравнение UUID

Проверить равенство значений Uuid можно с помощью оператора ==.

Kotlin сравнивает значения UUID, а не их текстовое представление. Например, два значения в разных форматах равны, если они соответствуют одному и тому же 128-битному значению:

import kotlin.uuid.Uuid

fun main() {
//sampleStart    
    val first = Uuid.parse("de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a")
    val second = Uuid.parse("de2bc56cea734f3c8a375a46fdb2d79a")

    println(first == second) 
    // true 
//sampleEnd    
}

Поэтому сравнение Uuid надёжнее сравнения строк, при котором одно и то же значение в разных форматах считается разным. Сравнение Uuid проверяет фактическое значение идентификатора.

Uuid реализует интерфейс Comparable<Uuid>, поэтому значения UUID можно сортировать с помощью стандартных функций коллекций, таких как sorted(). В этом случае Kotlin сравнивает значения лексикографически (от наиболее значащего бита к наименее значащему):

import kotlin.uuid.Uuid

fun main() {
//sampleStart    
    val first = Uuid.generateV7()
    val second = Uuid.generateV7()

    val sorted = listOf(first, second).sorted()
    println(sorted) 
//sampleEnd    
}

Работа с двоичными представлениями

Некоторые API, форматы хранения и двоичные протоколы представляют UUID не в виде строк. Вместо этого они хранят 128-битное значение UUID в одном из следующих видов:

• Массив из 16 байт

• Два 64-битных значения

Используйте эти представления, если нужно обмениваться UUID с системами, которые ожидают двоичные данные UUID.

Чтобы преобразовать UUID в 16-байтовое представление и обратно, используйте функции .toByteArray() и Uuid.fromByteArray():

import kotlin.uuid.Uuid

fun main() {
//sampleStart 
    val id = Uuid.random()

    val bytes = id.toByteArray()
    val original = Uuid.fromByteArray(bytes)
  
    println(id)
    
    println(bytes)
    println(original)

    println(id == original) 
    // true
//sampleEnd  
}

То же 128-битное значение UUID можно также представить в виде двух значений Long. Это полезно, поскольку в Kotlin нет встроенного 128-битного целочисленного типа. Два значения Long хранят UUID в двух частях:

• Параметр mostSignificantBits — для первых 64 бит UUID.

• Параметр leastSignificantBits — для последних 64 бит UUID.

Чтобы создать значение Uuid из двух значений Long, используйте функцию Uuid.fromLongs():

import kotlin.uuid.Uuid

fun main() {
//sampleStart 
    val id = Uuid.fromLongs(
        mostSignificantBits = -4653685776373167443,
        leastSignificantBits = -6288180676521310383.toLong()
    )
    println(id) 
    // bf6ac971-52fd-4aad-a8bb-e4fdac78c751
//sampleEnd  
}

Чтобы извлечь обе части из существующего значения Uuid, используйте функцию Uuid.toLongs():

import kotlin.uuid.Uuid

fun main() {
//sampleStart 
    val id = Uuid.random()
    
    id.toLongs { mostSignificantBits, leastSignificantBits ->
        println(mostSignificantBits)
        println(leastSignificantBits)
    }
//sampleEnd  
}

Сериализация UUID

Kotlin поддерживает сериализацию значений Uuid. Используйте её, чтобы хранить или передавать значение UUID за пределами кода Kotlin, например в API JSON или файлах конфигурации.

Для сериализации значения Uuid представьте его в виде строки, если приложению не требуется другой формат. Библиотека kotlinx.serialization использует формат с шестнадцатеричными символами и дефисами:

//sampleStart 
import kotlin.uuid.Uuid
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class User(
    val id: Uuid,
    val name: String
)

fun main() {
    val user = User(
        id = Uuid.parse("de2bc56cea734f3c8a375a46fdb2d79a"),
        name = "Kotlin"
    )

    println(Json.encodeToString(user))
    // {"id":"de2bc56c-ea73-4f3c-8a37-5a46fdb2d79a","name":"Kotlin"}
}
//sampleEnd

Использование UUID с API Java

Для представления UUID в Java используется класс java.util.UUID. На JVM API Java могут принимать или возвращать значения этого типа. Хотя java.util.UUID и kotlin.uuid.Uuid представляют UUID, это два разных типа.

Чтобы передавать UUID между Kotlin и Java, явно преобразуйте значения:

• Преобразуйте UUID из Java в Kotlin с помощью функции-расширения .toKotlinUuid():

  import kotlin.uuid.toKotlinUuid
  
  val kotlinId: Uuid = javaId.toKotlinUuid()
  

• Преобразуйте UUID из Kotlin в Java с помощью функции-расширения .toJavaUuid():

  import kotlin.uuid.toJavaUuid
  
  val javaId: java.util.UUID = kotlinId.toJavaUuid()
  

Эти функции позволяют представлять значения UUID с помощью Uuid на границах взаимодействия с JVM.

Kotlin также поддерживает работу с буферами Java. Используйте функции, специфичные для JVM, чтобы работать с UUID в ByteBuffer:

• Используйте функцию .getUuid(), чтобы прочитать UUID из буфера.

• Используйте функцию .putUuid(), чтобы записать UUID в буфер.