hyperuuid 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2b7cb6d510ac9faccd193dde27916dc8bd7384b6b9c1d387dfc47682eeb9274
-  data.tar.gz: f4d3082562a32328b0519b6f2c0b461d8fb3303d731fca8b1b96422266f97e4c
+  metadata.gz: d36a27a93cdb9a4a6bffeb6a6b9ddb8da61bbc9d20b8fda29ad7c8b2238465c2
+  data.tar.gz: cbe47ffb022c0ccb23d98ff9543c56d515ecc6928dbf7df11533593c097247ae
 SHA512:
-  metadata.gz: 1d80438fc78ff61048568c3ff70fff7bc6493ba639ac60299c21495b863419fc49f5e61f38bdfaf1b9be9910930da9124deaf98254bc119d9ec0d8f11b6cf1fc
-  data.tar.gz: beed906a491217aef07a6d3ce2ac36f77410710c7379ae1cffa0733cdb3c33c2eb1deeecd24fac7d32f96160068b512b6d5984fbd5aa7508e6fa23590e950169
+  metadata.gz: eb071fda1c20cb7f44d0b64fbcf2833768bac66cfe7d71951d1ba2e4ef0fe3d3d166d6a545b347bba22b52dee932e979f8e7b0059719f92c6308fc70629dbd04
+  data.tar.gz: 8630e51665339db93b4a6c90230b08649f8b9bf2e86520b09a803bff435d0e977df6bdfc88601b412d33f8aa8b19104afd854329d409c0894d9bb3c98258c2ef

data/README.md

@@ -23,6 +23,7 @@ id3 = HyperUuid.new_v6
 id4 = HyperUuid.new_v7
 
 id4.timestamp # recover the embedded UTC Time
+id4.timestamp(raise_on_mismatch: false) # nil instead of raising if id4 isn't v6/v7
 id4.to_sql_order # byte order SQL Server's uniqueidentifier needs to sort by creation order
 
 # One native call, one random-bytes fetch, one counter reservation for the whole batch:
@@ -32,7 +33,9 @@ batch = HyperUuid.new_v7_batch(1000)
 Returns `HyperUuid::Uuid`, a minimal value object (`#bytes`, `#to_s`, `#version`, `#variant`,
 comparable/hashable) — this gem has no runtime dependency on the `uuid` gem.
 `HyperUuid::Namespaces::DNS`/`URL`/`OID`/`X500` are RFC 9562 Section 6.6's well-known
-namespaces. `#timestamp` recovers the embedded UTC `Time` from a version 6 or 7 UUID.
+namespaces. `#timestamp` recovers the embedded UTC `Time` from a version 6 or 7 UUID; pass
+`raise_on_mismatch: false` to get `nil` back for any other version instead of raising.
+`.new_v6`/`.new_v7` also accept a `Time` directly in place of a raw millisecond count.
 `#to_sql_order`/`#from_sql_order` convert a version 6 or 7 UUID to and from the byte order SQL
 Server's `uniqueidentifier` needs on the wire to sort by creation order (`#to_sql_order`
 dispatches on the UUID's own version, matching `#timestamp`'s convention) — computed once in
@@ -90,10 +93,15 @@ The batch multiplier shrank from 11x to ~3.8x for the best reason available: the
 
 ## Install
 
-Not yet published to RubyGems.org under a registered `SkunkWerkx`/`buvinghausen` presence —
-for now this is proven by CI building and testing the native core plus this gem on real
-hardware for every platform leg. Consume via a direct
-`gem "hyperuuid", git: "https://github.com/SkunkWerkx/HyperUuid", glob: "ruby/*.gemspec"` in
-the meantime.
+```sh
+gem install hyperuuid
+```
+
+Published to [RubyGems.org](https://rubygems.org/gems/hyperuuid) as real precompiled
+"platform gems" — `bundle`/`gem install` auto-selects the matching one for
+linux-x64/arm64 or osx-x64/arm64 (the compiled Magnus native extension, `backend: :native`),
+falling back automatically to the universal `ruby`-platform gem (pure Fiddle, zero compile,
+bundles all 6 platforms' native libs) everywhere else — Windows included, since Magnus
+doesn't target it. No extra configuration needed either way.
 
 See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.

data/lib/hyperuuid/uuid.rb

@@ -52,12 +52,18 @@ module HyperUuid
     # when `version` is 6 or 7 — the RFC 9562 bit layout doesn't distinguish "not a time-based
     # UUID" from "time-based UUID with a very early timestamp", so the caller is responsible
     # for checking `version` first if that matters.
-    def timestamp
+    #
+    # Raises by default for any other version; pass `raise_on_mismatch: false` to get `nil`
+    # back instead — for a caller that doesn't already know (or want to separately check)
+    # whether this UUID is time-based.
+    def timestamp(raise_on_mismatch: true)
       millis =
         case version
         when 6 then Runtime.v6_unix_millis(bytes)
         when 7 then Runtime.v7_unix_millis(bytes)
-        else raise ArgumentError, "timestamp is only defined for version 6 or 7 UUIDs, got version #{version}"
+        else
+          raise ArgumentError, "timestamp is only defined for version 6 or 7 UUIDs, got version #{version}" if raise_on_mismatch
+          return nil
         end
       Time.at(millis / 1000, millis % 1000, :millisecond).utc
     end

data/lib/hyperuuid.rb

@@ -33,38 +33,49 @@ module HyperUuid
     Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes))
   end
 
+  # Converts +value+ to a Unix-epoch millisecond integer: +nil+ becomes the current time, a
+  # +Time+ is converted exactly (via its own Rational seconds, avoiding float rounding), and
+  # anything else (an Integer millisecond count) passes through unchanged. Shared by every
+  # `new_v6`/`new_v7`/batch door below so a caller can pass either a `Time` or a raw
+  # millisecond count interchangeably.
+  private_class_method def self.unix_millis_from(value)
+    case value
+    when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    when Time then (value.to_r * 1000).to_i
+    else value
+    end
+  end
+
   # Creates a time-sortable UUID version 6 (RFC 9562 §5.6), a field-compatible reordering of
   # version 1 for better sort/index locality. Defaults to the current time; pass an explicit
-  # Unix-epoch millisecond timestamp to embed a specific time instead. `clock_seq` and `node`
-  # are randomly generated on every call — unlike version 7, there is no monotonic counter, so
-  # calls within the same millisecond are not guaranteed to sort in creation order.
+  # `Time` or Unix-epoch millisecond integer to embed a specific time instead. `clock_seq` and
+  # `node` are randomly generated on every call — unlike version 7, there is no monotonic
+  # counter, so calls within the same millisecond are not guaranteed to sort in creation order.
   def self.new_v6(unix_millis = nil)
-    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    Uuid.new(Runtime.new_v6(unix_millis))
+    Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis)))
   end
 
   # Creates `count` time-sortable version 6 UUIDs sharing one timestamp capture — one FFI call
-  # and one random-bytes fetch instead of `count` of each. Defaults to the current time.
+  # and one random-bytes fetch instead of `count` of each. Defaults to the current time; pass
+  # an explicit `Time` or Unix-epoch millisecond integer to embed a specific time instead.
   def self.new_v6_batch(count, unix_millis = nil)
-    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    bytes = Runtime.new_v6_batch(count, unix_millis)
+    bytes = Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
     Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
   end
 
   # Creates a time-sortable UUID version 7 (RFC 9562 §6.2). Defaults to the current time; pass
-  # an explicit Unix-epoch millisecond timestamp (non-negative, fitting in 48 bits) to embed a
-  # specific time instead.
+  # an explicit `Time` or Unix-epoch millisecond integer (non-negative, fitting in 48 bits) to
+  # embed a specific time instead.
   def self.new_v7(unix_millis = nil)
-    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    Uuid.new(Runtime.new_v7(unix_millis))
+    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis)))
   end
 
   # Creates `count` time-sortable version 7 UUIDs sharing one timestamp capture and one
   # contiguous block of the monotonic counter — one FFI call and one random-bytes fetch
-  # instead of `count` of each. Defaults to the current time.
+  # instead of `count` of each. Defaults to the current time; pass an explicit `Time` or
+  # Unix-epoch millisecond integer to embed a specific time instead.
   def self.new_v7_batch(count, unix_millis = nil)
-    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    bytes = Runtime.new_v7_batch(count, unix_millis)
+    bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
     Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Brian Buvinghausen