Use kotlin.time.Instant api (#438)

detekt-baseline.xml

@@ -3,6 +3,7 @@
   <ManuallySuppressedIssues/>
   <CurrentIssues>
     <ID>FunctionNaming:Dsl.kt$public fun Uuidv7(timeStamp: Instant = Clock.System.now(), random: Random): Uuid</ID>
+    <ID>FunctionNaming:Uuidv7.kt$@ExperimentalTime public fun Uuidv7(timeStamp: Instant = Clock.System.now(), random: Random): Uuid</ID>
     <ID>FunctionNaming:Uuidv7.kt$public fun Uuidv7(timeStamp: Long, random: Random): Uuid</ID>
     <ID>MagicNumber:NameBasedGenerator.kt$0x3f</ID>
     <ID>MagicNumber:NameBasedGenerator.kt$4</ID>

kotlinx-uuid-core/README.md

@@ -33,6 +33,18 @@ val uuid = UUIDv7(unixTimestamp)
 uuid.unixTimeStamp // 42
 ```
 
+UUIDv7 with the current timestamp using `Clock.System` can be created using:
+
+```kotlin
+val uuid = UUIDv7(random = Random)
+```
+
+When processing existing UUIDv7s, the timestamp bits can be interpreted as an Instant with millisecond precision using:
+
+```kotlin
+UUIDv7().instant
+```
+
 ## Serializing (kotlinx.serialization)
 
 There is also a binary serializers for `Uuid`.

kotlinx-uuid-core/api/kotlinx-uuid-core.api

@@ -38,6 +38,9 @@ public final class app/softwork/uuid/UuidKt {
 
 public final class app/softwork/uuid/Uuidv7Kt {
 	public static final fun Uuidv7 (JLkotlin/random/Random;)Lkotlin/uuid/Uuid;
+	public static final fun Uuidv7 (Lkotlin/time/Instant;Lkotlin/random/Random;)Lkotlin/uuid/Uuid;
+	public static synthetic fun Uuidv7$default (Lkotlin/time/Instant;Lkotlin/random/Random;ILjava/lang/Object;)Lkotlin/uuid/Uuid;
+	public static final fun getInstant (Lkotlin/uuid/Uuid;)Lkotlin/time/Instant;
 	public static final fun getUnixTimeStamp (Lkotlin/uuid/Uuid;)J
 }
 

kotlinx-uuid-core/api/kotlinx-uuid-core.klib.api

@@ -22,6 +22,8 @@ final val app.softwork.uuid/MAX // app.softwork.uuid/MAX|@kotlin.uuid.Uuid.Compa
     final fun (kotlin.uuid/Uuid.Companion).<get-MAX>(): kotlin.uuid/Uuid // app.softwork.uuid/MAX.<get-MAX>|<get-MAX>@kotlin.uuid.Uuid.Companion(){}[0]
 final val app.softwork.uuid/clockSequence // app.softwork.uuid/clockSequence|@kotlin.uuid.Uuid{}clockSequence[0]
     final fun (kotlin.uuid/Uuid).<get-clockSequence>(): kotlin/Int // app.softwork.uuid/clockSequence.<get-clockSequence>|<get-clockSequence>@kotlin.uuid.Uuid(){}[0]
+final val app.softwork.uuid/instant // app.softwork.uuid/instant|@kotlin.uuid.Uuid{}instant[0]
+    final fun (kotlin.uuid/Uuid).<get-instant>(): kotlin.time/Instant // app.softwork.uuid/instant.<get-instant>|<get-instant>@kotlin.uuid.Uuid(){}[0]
 final val app.softwork.uuid/isRfcVariant // app.softwork.uuid/isRfcVariant|@kotlin.uuid.Uuid{}isRfcVariant[0]
     final fun (kotlin.uuid/Uuid).<get-isRfcVariant>(): kotlin/Boolean // app.softwork.uuid/isRfcVariant.<get-isRfcVariant>|<get-isRfcVariant>@kotlin.uuid.Uuid(){}[0]
 final val app.softwork.uuid/node // app.softwork.uuid/node|@kotlin.uuid.Uuid{}node[0]
@@ -45,6 +47,7 @@ final fun (kotlin.uuid/Uuid.Companion).app.softwork.uuid/isValidUuidString(kotli
 final fun (kotlin.uuid/Uuid.Companion).app.softwork.uuid/random(kotlin.random/Random): kotlin.uuid/Uuid // app.softwork.uuid/random|[email protected](kotlin.random.Random){}[0]
 final fun (kotlin/String).app.softwork.uuid/toUuid(): kotlin.uuid/Uuid // app.softwork.uuid/toUuid|[email protected](){}[0]
 final fun (kotlin/String).app.softwork.uuid/toUuidOrNull(): kotlin.uuid/Uuid? // app.softwork.uuid/toUuidOrNull|[email protected](){}[0]
+final fun app.softwork.uuid/Uuidv7(kotlin.time/Instant = ..., kotlin.random/Random): kotlin.uuid/Uuid // app.softwork.uuid/Uuidv7|Uuidv7(kotlin.time.Instant;kotlin.random.Random){}[0]
 final fun app.softwork.uuid/Uuidv7(kotlin/Long, kotlin.random/Random): kotlin.uuid/Uuid // app.softwork.uuid/Uuidv7|Uuidv7(kotlin.Long;kotlin.random.Random){}[0]
 
 // Targets: [apple]

kotlinx-uuid-core/build.gradle.kts

@@ -1,5 +1,3 @@
-import org.jetbrains.kotlin.gradle.plugin.*
-
 /*
  * Copyright 2020-2021 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  * Copyright 2021 hfhbd and contributors. Use of this source code is governed by the Apache 2.0 license.

kotlinx-uuid-core/src/commonMain/kotlin/app/softwork/uuid/Uuidv7.kt

@@ -1,6 +1,9 @@
 package app.softwork.uuid
 
 import kotlin.random.Random
+import kotlin.time.Clock
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 import kotlin.uuid.Uuid
 
 private const val UNIX_48_TIMESTAMP = 0x1FFF_FFFF_FFFF_FL
@@ -34,3 +37,17 @@ public fun Uuidv7(timeStamp: Long, random: Random): Uuid {
  * The Uuidv7 48 bit big-endian unsigned number of Unix epoch timestamp in milliseconds
  */
 public val Uuid.unixTimeStamp: Long get() = toLongs { mostSignificantBits, _ -> mostSignificantBits ushr 16 }
+
+/**
+ * An Uuidv7 implementation according to the
+ * [draft](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#section-5.7).
+ */
+@ExperimentalTime
+public fun Uuidv7(timeStamp: Instant = Clock.System.now(), random: Random): Uuid =
+    Uuidv7(timeStamp = timeStamp.toEpochMilliseconds(), random = random)
+
+/**
+ * The Uuidv7 48 bit big-endian unsigned number of Unix epoch timestamp in milliseconds
+ */
+@ExperimentalTime
+public val Uuid.instant: Instant get() = Instant.fromEpochMilliseconds(unixTimeStamp)

kotlinx-uuid-core/src/commonTest/kotlin/app/softwork/uuid/Uuidv7Test.kt

@@ -3,6 +3,8 @@ package app.softwork.uuid
 import kotlin.random.Random
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 
 class Uuidv7Test {
     @Test
@@ -14,4 +16,14 @@ class Uuidv7Test {
         assertEquals(7, uuid.version)
         assertEquals(5, uuid.variant)
     }
+
+    @Test
+    @ExperimentalTime
+    fun testConversionInstant() {
+        val timestamp = Instant.parse("2020-02-20T10:21:42Z")
+        val uuid = Uuidv7(timeStamp = timestamp, random = Random(4242))
+        assertEquals(timestamp, uuid.instant)
+        assertEquals("0170621e-0ef0-7a1e-ad73-08cd2f61d78a", uuid.toString())
+        assertEquals(7, uuid.version)
+    }
 }