hyperuuid 0.0.1-aarch64-linux → 0.1.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c70194e95ed5934800364517f24e261ba9908845ab7aa792323f76e82ade00c
-  data.tar.gz: 2005f034b025bd8f5552ee3973c70175d59dc244b9f59c4e2fbadfbb2fd079b8
+  metadata.gz: 2892b5a876b4e3cad50f46aad3f4a778f89b6d72e4c523b6c711979c6c87ef30
+  data.tar.gz: 61ca11315cb9a92e2221dfa9a752eb83ce9c8c276b4dcf292bf5ce425c66fc55
 SHA512:
-  metadata.gz: 54ae222a52354ce34e13480a081ba166abcdd9c57c4f493242e1a89917b6c969f9411bc5518833ba03e49ba2920d518981963ccdc5710a5d2715604a90b28438
-  data.tar.gz: b14687f14ec691c2a9f7e7abe4547801b9bc9bc9b02cf2b0bf67410f133ba8778455d334d1c6c93ad29b1083313bfa1eb560b7af14567599b86c8088b2f7a1e3
+  metadata.gz: a8e44ec99f418bf148a9611952c64872d933ca2786a760cbb228cfe118c1635a87d7b13d0c2c491b14d0a7f22d68dad482c0f2ef33e73cc952bd2b7ff66e8eda
+  data.tar.gz: 59e0a033d956900a43f010765a00a3edd79def7863c29b01e9cfbbe8c45339e72afe4dec9c544db26057359011a76b5cc22ac2a22bcae7f4f51bf0ca4f201c67

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: aarch64-linux
 authors:
 - Brian Buvinghausen