From 9fa516f502da5aa62ac984acf21279a8555c96a6 Mon Sep 17 00:00:00 2001 From: Pat Garrity Date: Sat, 22 Mar 2025 11:26:08 -0500 Subject: [PATCH] (minor) Interface improvements, more functions, general version updates. --- .scalafmt.conf | 2 +- README.md | 3 ++ build.sbt | 10 ++++-- project/build.properties | 2 +- project/plugins.sbt | 2 +- src/main/java/gs/uuid/v0/UUIDFormat.java | 30 +++++++++++++++++- src/main/scala/gs/uuid/v0/UUID.scala | 38 +++++++++++++++++------ src/test/scala/gs/uuid/v0/UUIDTests.scala | 30 ++++++++++++++++-- 8 files changed, 100 insertions(+), 17 deletions(-) diff --git a/.scalafmt.conf b/.scalafmt.conf index 17e4b30..13746e4 100644 --- a/.scalafmt.conf +++ b/.scalafmt.conf @@ -1,5 +1,5 @@ // See: https://github.com/scalameta/scalafmt/tags for the latest tags. -version = 3.7.11 +version = 3.9.4 runner.dialect = scala3 maxColumn = 80 diff --git a/README.md b/README.md index 18381c7..3ec0972 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ UUIDs for Scala 3 with generation based on JUG, and serialization based on code from Jackson Databind. The only dependency is JUG, whereas the relevant Jackson code is copied to this implementation (and slightly modified). +This project uses the Apache 2.0 License due to the use of Jackson Databind +code. + - [Usage](#usage) - [Dependency](#dependency) - [Donate](#donate) diff --git a/build.sbt b/build.sbt index f3f293d..859e587 100644 --- a/build.sbt +++ b/build.sbt @@ -1,9 +1,15 @@ -val scala3: String = "3.4.2" +val scala3: String = "3.6.4" ThisBuild / scalaVersion := scala3 ThisBuild / versionScheme := Some("semver-spec") ThisBuild / gsProjectName := "gs-uuid" +ThisBuild / licenses := Seq( + "Apache 2.0" -> url( + "https://git.garrity.co/garrity-software/gs-uuid/src/branch/main/LICENSE" + ) +) + val sharedSettings = Seq( scalaVersion := scala3, version := semVerSelected.value, @@ -14,7 +20,7 @@ val sharedSettings = Seq( lazy val testSettings = Seq( libraryDependencies ++= Seq( - "org.scalameta" %% "munit" % "1.0.0" % Test + "org.scalameta" %% "munit" % "1.1.0" % Test ) ) diff --git a/project/build.properties b/project/build.properties index ee4c672..cc68b53 100644 --- a/project/build.properties +++ b/project/build.properties @@ -1 +1 @@ -sbt.version=1.10.1 +sbt.version=1.10.11 diff --git a/project/plugins.sbt b/project/plugins.sbt index c708d3a..809dbbe 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -29,5 +29,5 @@ externalResolvers := Seq( ) addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.1.0") -addSbtPlugin("gs" % "sbt-garrity-software" % "0.3.0") +addSbtPlugin("gs" % "sbt-garrity-software" % "0.5.0") addSbtPlugin("gs" % "sbt-gs-semver" % "0.3.0") diff --git a/src/main/java/gs/uuid/v0/UUIDFormat.java b/src/main/java/gs/uuid/v0/UUIDFormat.java index e82915d..e3a92b4 100644 --- a/src/main/java/gs/uuid/v0/UUIDFormat.java +++ b/src/main/java/gs/uuid/v0/UUIDFormat.java @@ -33,7 +33,7 @@ public final class UUIDFormat { * @param uuid The UUID to render. * @return Hexadecimal representation of the UUID. */ - public static String toHex(final UUID uuid) { + public static String toHexWithoutDashes(final UUID uuid) { final char[] ch = new char[32]; // Example: @@ -64,6 +64,34 @@ public final class UUIDFormat { return new String(ch, 0, 32); } + /** + *

Render the given UUID as a 36-character string using lowercase + * hexadecimal with dashes.

+ * + * @param uuid The UUID to render. + * @return Hexadecimal representation of the UUID. + */ + public static String toHexWithDashes(final UUID uuid) { + final char[] ch = new char[36]; + + final long msb = uuid.getMostSignificantBits(); + _appendInt((int) (msb >> 32), ch, 0); + ch[8] = '-'; + int i = (int) msb; + _appendShort(i >>> 16, ch, 9); + ch[13] = '-'; + _appendShort(i, ch, 14); + ch[18] = '-'; + + final long lsb = uuid.getLeastSignificantBits(); + _appendShort((int) (lsb >>> 48), ch, 19); + ch[23] = '-'; + _appendShort((int) (lsb >>> 32), ch, 24); + _appendInt((int) lsb, ch, 28); + + return new String(ch, 0, 36); + } + /** *

Render the given UUID as a 16-byte array.

* diff --git a/src/main/scala/gs/uuid/v0/UUID.scala b/src/main/scala/gs/uuid/v0/UUID.scala index f4e2954..548fea4 100644 --- a/src/main/scala/gs/uuid/v0/UUID.scala +++ b/src/main/scala/gs/uuid/v0/UUID.scala @@ -2,7 +2,8 @@ package gs.uuid.v0 import com.fasterxml.uuid.Generators -/** Alias for the `java.util.UUID` type, which represents a 128-bit value. +/** Alias for the `java.util.UUID` type, which represents a 128-bit (16-byte) + * value. * * ## ID Generation * @@ -65,6 +66,16 @@ object UUID: G: Generator ): UUID = G.next() + /** @return + * New v4 UUID (Random). + */ + def v4(): UUID = Generator.version4.next() + + /** @return + * New v7 UUID (Epoch + Counter + Random). + */ + def v7(): UUID = Generator.version7.next() + /** Parse the given string as a UUID. * * @param str @@ -100,15 +111,24 @@ object UUID: */ def toBytes(): Array[Byte] = UUIDFormat.toBytes(uid) - /** @return - * Hexadecimal string representation of this UUID, without dashes. + /** Serialize this UUID. + * + * @param dashes + * Whether to use dashes in the output (default = false). + * @return + * Hexadecimal string representation of this UUID. */ - def str(): String = withoutDashes() + def str(dashes: Boolean = false): String = withoutDashes() /** @return * Hexadecimal string representation of this UUID, without dashes. */ - def withoutDashes(): String = UUIDFormat.toHex(uid) + def withoutDashes(): String = UUIDFormat.toHexWithoutDashes(uid) + + /** @return + * Hexadecimal string representation of this UUID, with dashes. + */ + def withDashes(): String = UUIDFormat.toHexWithDashes(uid) /** @return * The least significant bits of this UUID. @@ -135,11 +155,11 @@ object UUID: object Generator: /** Instantiate a new Type 4 generator. */ - def version4(): Generator = new Version4 + lazy val version4: Generator = new Version4 /** Instantiate a new Type 7 generator. */ - def version7(): Generator = new Version7 + lazy val version7: Generator = new Version7 /** Type 4 (Random) implementation of a UUID generator. */ @@ -147,8 +167,8 @@ object UUID: private val gen = Generators.randomBasedGenerator() override def next(): UUID = gen.generate() - /** Type 7 (Unix Epoch Time + Random) implementation of a UUID generator. - * Consider using this rather than Type 1 or Type 6. + /** Type 7 (Unix Epoch Time + Counter + Random) implementation of a UUID + * generator. Consider using this rather than Type 1 or Type 6. * * This type is defined in [IETF New UUID Formats * Draft](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-7) diff --git a/src/test/scala/gs/uuid/v0/UUIDTests.scala b/src/test/scala/gs/uuid/v0/UUIDTests.scala index 3c962ce..3b80518 100644 --- a/src/test/scala/gs/uuid/v0/UUIDTests.scala +++ b/src/test/scala/gs/uuid/v0/UUIDTests.scala @@ -1,8 +1,8 @@ package gs.uuid.v0 class UUIDTests extends munit.FunSuite: - private val v4 = UUID.Generator.version4() - private val v7 = UUID.Generator.version7() + private val v4 = UUID.Generator.version4 + private val v7 = UUID.Generator.version7 given CanEqual[java.util.UUID, java.util.UUID] = CanEqual.derived test( @@ -14,6 +14,15 @@ class UUIDTests extends munit.FunSuite: assertEquals(parsed, Some(base)) } + test( + "should instantiate a type 4 UUID, serialize it, and parse the result (helper function)" + ) { + val base = UUID.v4() + val str = base.str() + val parsed = UUID.parse(str) + assertEquals(parsed, Some(base)) + } + test( "should instantiate a type 7 UUID, serialize it, and parse the result" ) { @@ -23,6 +32,15 @@ class UUIDTests extends munit.FunSuite: assertEquals(parsed, Some(base)) } + test( + "should instantiate a type 7 UUID, serialize it, and parse the result (helper function)" + ) { + val base = UUID.v7() + val str = base.str() + val parsed = UUID.parse(str) + assertEquals(parsed, Some(base)) + } + test("should instantiate from any java.util.UUID") { val raw = java.util.UUID.randomUUID() val base = UUID(raw) @@ -33,6 +51,14 @@ class UUIDTests extends munit.FunSuite: } test("should successfully parse a UUID with dashes") { + val raw = java.util.UUID.randomUUID() + val base = UUID(raw) + assertEquals(UUID.parse(base.withDashes()), Some(base)) + } + + test( + "should successfully parse a UUID with dashes, generated with this library" + ) { val base = java.util.UUID.randomUUID() assertEquals(UUID.parse(base.toString()), Some(UUID(base))) }