(minor) Interface improvements, more functions, general version updates. (#14)

Reviewed-on: #14

.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
 

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)

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
   )
 )
 

project/build.properties

@@ -1 +1 @@
-sbt.version=1.10.1
+sbt.version=1.10.11

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")

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);
     }
 
+    /**
+     * <p>Render the given UUID as a 36-character string using lowercase
+     * hexadecimal with dashes.</p>
+     *
+     * @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);
+    }
+
     /**
      * <p>Render the given UUID as a 16-byte array.</p>
      *

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
+    /** Serialize this UUID.
-      *   Hexadecimal string representation of this UUID, without dashes.
+      *
+      * @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.
+    /** Type 7 (Unix Epoch Time + Counter + Random) implementation of a UUID
-      * Consider using this rather than Type 1 or Type 6.
+      * 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)

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 v4                                 = UUID.Generator.version4
-  private val v7                                 = UUID.Generator.version7()
+  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)))
   }