Uuid

Represents a Universally Unique Identifier (UUID), also known as a Globally Unique Identifier (GUID).

A UUID is a 128-bit value used to uniquely identify items universally. They are particularly useful in environments lacking central registration authority or coordination mechanism for generating identifiers, making UUIDs highly suitable for distributed systems.

The standard textual representation of a UUID, also known as the "hex-and-dash" format, is: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", where 'x' represents a hexadecimal digit, e.g., "550e8400-e29b-41d4-a716-446655440000". This format includes hyphens to separate different parts of the UUID, enhancing human readability.

This class provides utility functions for:

• Generating UUIDs.

• Creating UUIDs from given 128 bits.

• Parsing UUIDs from and formatting them to their string representations.

• Converting UUIDs to and from arrays of bytes.

• Comparing UUIDs to establish ordering or equality.

Note that Uuid has value semantics, and it may become a value class in the future (see (KEEP-0454)[https://github.com/Kotlin/KEEP/blob/main/proposals/KEEP-0454-better-immutability-value-classes-MFVC.md] for more details about multi-field value classes). It is not recommended to rely on Uuid identity (i.e., abstain from comparing two Uuids using === or having an kotlin.concurrent.atomics.AtomicReference to it). Identity-based operations on Uuid may be reported as warnings in future versions of Kotlin.

Samples

import kotlin.test.*
import kotlin.time.Instant
import kotlin.uuid.*

fun main() { 
   //sampleStart 
   // Parsing is case-insensitive
val uuid1 = Uuid.parse("550E8400-e29b-41d4-A716-446655440000") // hex-and-dash
val uuid2 = Uuid.parse("550e8400E29b41D4a716446655440000") // hexadecimal

println("uuid1 == uuid2 is ${uuid1 == uuid2}") // true
println(uuid1) // 550e8400-e29b-41d4-a716-446655440000
println(uuid2) // 550e8400-e29b-41d4-a716-446655440000

// Uuid.parse("I'm not a UUID, sorry") // will fail with IllegalArgumentException 
   //sampleEnd
}

import kotlin.test.*
import kotlin.time.Instant
import kotlin.uuid.*

fun main() { 
   //sampleStart 
   val byteArray = byteArrayOf(
    0x55, 0x0e, 0x84.toByte(), 0x00, 0xe2.toByte(), 0x9b.toByte(), 0x41, 0xd4.toByte(),
    0xa7.toByte(), 0x16, 0x44, 0x66, 0x55, 0x44, 0x00, 0x00
)
val uuid = Uuid.fromByteArray(byteArray)
println(uuid) // 550e8400-e29b-41d4-a716-446655440000 
   //sampleEnd
}

import kotlin.test.*
import kotlin.time.Instant
import kotlin.uuid.*

fun main() { 
   //sampleStart 
   // Generates a random and unique uuid each time
val uuid1 = Uuid.random()
val uuid2 = Uuid.random()
val uuid3 = Uuid.random()

println(uuid1 == uuid2) // false
println(uuid1 == uuid3) // false
println(uuid2 == uuid3) // false 
   //sampleEnd
}