Module: HyperUuid

Defined in:
lib/hyperuuid.rb,
lib/hyperuuid/uuid.rb,
lib/hyperuuid/runtime.rb,
lib/hyperuuid/namespaces.rb,
lib/hyperuuid/native_platform.rb

Overview

RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, calling directly into the native libhyperuuid shared library via Fiddle — no runtime bridge, no extra gem dependency. Bundles a native build for every supported platform (see HyperUuid::NativePlatform) and picks the right one at runtime, the same trick the Go/ Java bindings use since RubyGems has no per-platform native selection wired up here.

Defined Under Namespace

Modules: Namespaces, NativePlatform, Runtime Classes: Uuid

Constant Summary collapse

VERSION =

This gem's own version — distinct from the RFC 9562 UUID versions (v4/v5/v6/v7) the rest of this module generates.

"0.1.0"
BACKEND =

--- backend selection: the Magnus extension, when present, replaces the Runtime methods above in place (no delegation layer) — Fiddle's measured per-call marshalling floor drops to an ordinary extension call, while everything above Runtime (Uuid, the module doors, batch slicing) stays shared byte-for-byte between backends. The pure-Fiddle definitions remain the universal zero-compile fallback; precompiled platform gems are how the extension ships without ever making a consumer compile anything. Set HYPERUUID_PURE=1 to force Fiddle.

if ENV["HYPERUUID_PURE"]
  :fiddle
else
  begin
    require "hyperuuid_native"
    :native
  rescue LoadError
    :fiddle
  end
end

Class Method Summary collapse

Class Method Details

.new_v4 ⇒ Object

Creates a random UUID version 4 (RFC 9562 §5.4).



19
20
21
 
# File 'lib/hyperuuid.rb', line 19

def self.new_v4
  Uuid.new(Runtime.new_v4)
end

.new_v5(namespace, name) ⇒ Object

Creates a deterministic UUID version 5 (RFC 9562 §5.5) from a namespace and a name. The same (namespace, name) pair always produces the same UUID. name may be a text String (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is.



26
27
28
29
30
31
32
33
34
 
# File 'lib/hyperuuid.rb', line 26

def self.new_v5(namespace, name)
  name_bytes =
    if name.encoding == Encoding::ASCII_8BIT
      name
    else
      name.encode(Encoding::UTF_8).dup.force_encoding(Encoding::BINARY)
    end
  Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes))
end

.new_v6(unix_millis = nil) ⇒ Object

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



54
55
56
 
# File 'lib/hyperuuid.rb', line 54

def self.new_v6(unix_millis = nil)
  Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis)))
end

.new_v6_batch(count, unix_millis = nil) ⇒ Object

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; pass an explicit Time or Unix-epoch millisecond integer to embed a specific time instead.



61
62
63
64
 
# File 'lib/hyperuuid.rb', line 61

def self.new_v6_batch(count, unix_millis = nil)
  bytes = Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
  Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
end

.new_v7(unix_millis = nil) ⇒ Object

Creates a time-sortable UUID version 7 (RFC 9562 §6.2). Defaults to the current time; pass an explicit Time or Unix-epoch millisecond integer (non-negative, fitting in 48 bits) to embed a specific time instead.



69
70
71
 
# File 'lib/hyperuuid.rb', line 69

def self.new_v7(unix_millis = nil)
  Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis)))
end

.new_v7_batch(count, unix_millis = nil) ⇒ Object

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; pass an explicit Time or Unix-epoch millisecond integer to embed a specific time instead.



77
78
79
80
 
# File 'lib/hyperuuid.rb', line 77

def self.new_v7_batch(count, unix_millis = nil)
  bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
  Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
end