generateV7NonMonotonicAt

Generates a new random Uuid Version 7 instance for a specified moment in time.

The returned uuid is a time-based sortable UUID that conforms to the IETF variant (variant 2) and version 7, uses UNIX timestamp in milliseconds extracted from timestamp as a prefix and a randomly generated suffix.

Unlike generateV7, this function does not provide any monotonicity guarantees, meaning that there will be no guaranteed order for uuids created by calling this function two or more times with exactly the same timestamp. If multiple uuids corresponding to the same timestamp are needed, consider generating them using this function, then sorting the result before using it to achieve the monotonicity.

This function is aimed for generating v7 uuids corresponding to the past (or the future). Always consider using generateV7 if an uuid corresponding to a current moment in time in needed.

This function does not affect the state and monotonicity guarantees of generateV7 in any way, so even if it is invoked with a timestamp from a distant future, generateV7 will continue returning uuids with a timestamp corresponding to a current moment in time.

The random part of the uuid is produced using a cryptographically secure pseudorandom number generator (CSPRNG) available on the platform. If the underlying system has not collected enough entropy, this function may block until sufficient entropy is collected, and the CSPRNG is fully initialized. It is worth mentioning that the PRNG used in the Kotlin/WasmWasi target is not guaranteed to be cryptographically secure. See the list below for details about the API used for producing the random uuid in each supported target.

Note that the returned uuid is not recommended for use for cryptographic purposes. Because version 7 uuid has a partially predictable bit pattern, and utilizes at most 74 bits of entropy, regardless of platform.

The following APIs are used for producing the random uuid in each of the supported targets:

• Kotlin/JVM - java.security.SecureRandom

• Kotlin/JS - Crypto.getRandomValues()

• Kotlin/WasmJs - Crypto.getRandomValues()

• Kotlin/WasmWasi - random_get

• Kotlin/Native:

• Linux targets - getrandom

• Apple and Android Native targets - arc4random_buf

• Windows targets - BCryptGenRandom

Note that the underlying API used to produce random uuids may change in the future.

Throws

Samples

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

fun main() { 
   //sampleStart 
   val timestamp = Instant.fromEpochMilliseconds(1757440583000L)

val uuid1 = Uuid.generateV7NonMonotonicAt(timestamp)
val uuid2 = Uuid.generateV7NonMonotonicAt(timestamp)

// Uuids have the same timestamp prefix (01992f9f-2558-, which corresponds to 1757440583000 in hex),
// but other bytes are different.
println("uuid1.toHexDashString().startsWith(\"01992f9f-2558-\") is ${uuid1.toHexDashString().startsWith("01992f9f-2558-")}") // true
println(uuid1.toHexDashString())

println("uuid2.toHexDashString().startsWith(\"01992f9f-2558-\") is ${uuid2.toHexDashString().startsWith("01992f9f-2558-")}") // true
println(uuid2.toHexDashString())

assertNotEquals(uuid1, uuid2) 
   //sampleEnd
}

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

fun main() { 
   //sampleStart 
   val timestamp = Instant.fromEpochMilliseconds(1757440583000L)

// Generate 5 uuids for the same timestamp, and them explicitly sort them to ensure monotonicity
val uuids = sequence<Uuid> { Uuid.generateV7NonMonotonicAt(timestamp) }.take(5).sorted().toList()

for (idx in 1..<uuids.size) {
    println("uuids[idx - 1] < uuids[idx] is ${uuids[idx - 1] < uuids[idx]}") // true
} 
   //sampleEnd
}