class Torid::UUID

Represents a UUID generated by Torid

Torid::UUID wraps 2 64bit Integer values and can convert them back and forth between raw bytes and the canonical UUID form of 32 lowercase hexadecimal lowercase hexadecimal digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens)

Since internally, Torid::UUID's represent a 64bit microsecond timestamp and a 'node_id', those data fields are also able to be returned as a Time instance or an Integer respectively.

Examples

uuid = Torid.uuid
uuid.to_s  # => "0004fda3-8c73-5e0f-bae4-e9c86e3684a5"
uuid.bytes # => "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5"

uuid.timestamp # => Time
uuid.node_id   # => Integer

Constants

REGEX

Regular expression that matches the 36 byte 8-4-4-4-12 format

Public Instance Methods

eql?(other)
Alias for: ==

Public

↑ top

Attributes

node_id[R]

The 64bit node id

timestamp[R]

The 64bit microsecond UNIX timestamp

Public Class Methods

from( str ) click to toggle source

Create a Torid::UUID from an existing String. The String can either be a 16 byte binary string, or a 36byte hexadecimal UUID in the 8-4-4-4-12 format.

str

The String from which to create the UUID.

Examples

Torid::UUID.from( "0004fda3-8c73-5e0f-bae4-e9c86e3684a5" )                 # => Torid::UUID
Torid::UUID.from( "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5" ) # => Torid::UUID

Returns

Returns a Torid::UUID

Raises ArgumentError if the String is not convertable to a UUID.

# File lib/torid/uuid.rb, line 53
def self.from( str )
  return from_bytes( str )  if str.bytesize == 16
  return from_string( str ) if UUID.match( str )
  raise ArgumentError, "UUID can only be loaded from a 16 byte binary string or a 36 byte formatted UUID string."
end
match( str ) click to toggle source

Return if the given string matches the UUID regular expression

str

The String to compare to REGEX

Examples:

Torid::UUID.match( "0004fda3-8c73-5e0f-bae4-e9c86e3684a5" ) # => MatchData

Returns

Returns MatchData or nil if there is no match

# File lib/torid/uuid.rb, line 36
def self.match( str )
  REGEX.match( str )
end

Public Instance Methods

==(other) click to toggle source

Compare the equality of UUID's

Examples

uuid == other_uuid

Returns

Returns true or false

# File lib/torid/uuid.rb, line 171
def ==(other)
  other.is_a?(::Torid::UUID) &&
    other.node_id == self.node_id &&
    other.timestamp == self.timestamp
end
Also aliased as: eql?
bytes() click to toggle source

Return the UUID as 16 bytes of raw data.

Copied from lexical_uuid

Examples

uuid.bytes # => "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5"

Returns

Returns a binary String

# File lib/torid/uuid.rb, line 130
def bytes
  @bytes ||= [ @timestamp >> 32,
               @timestamp & 0xFFFF_FFFF,
               @node_id   >> 32,
               @node_id   & 0xFFFF_FFFF ].pack("NNNN")
end
hash() click to toggle source

Generate the hash of the UUID for ruby hash equality

This allows two UUID objects that have the same node_id and timestamp to be considered the same object for keys in Hash.

Examples

one   = Torid.uuid
other = Torid::UUID.from( one.bytes )
h     = { one => "a value" }
h.has_key?( other )  # => true
# File lib/torid/uuid.rb, line 188
def hash
  [node_id, timestamp, ::Torid::UUID].hash
end
node_id_s() click to toggle source

Return the hexidcimal UUID string representation of just the node_id. This is just the last 2 parts

# File lib/torid/uuid.rb, line 156
def node_id_s
  node_bytes = [ @node_id >> 32, @node_id & 0xFFFF_FFFF].pack("NN")
  elements   = node_bytes.unpack("CCa6")
  node         = elements[-1].unpack('C*')
  elements[-1] = '%02x%02x%02x%02x%02x%02x' % node
  "%02x%02x-%s" % elements
end
time() click to toggle source

Return the Time value the internal microsecond timestamp represents.

Examples

uuid.time # => Time

Returns

Returns a Time instance

# File lib/torid/uuid.rb, line 117
def time
  @time ||= Time.at( timestamp / 1_000_000.0 )
end
to_s() click to toggle source

Return the hexadecimal UUID string representation. This is the standard 8-4-4-4-12 UUID string representation.

Copied from simple_uuid via lexical_uuid.

Examples

uuid.to_s  # => "0004fda3-8c73-5e0f-bae4-e9c86e3684a5"

Returns

Returns a String

# File lib/torid/uuid.rb, line 147
def to_s
  elements     = bytes.unpack("NnnCCa6")
  node         = elements[-1].unpack('C*')
  elements[-1] = '%02x%02x%02x%02x%02x%02x' % node
  "%08x-%04x-%04x-%02x%02x-%s" % elements
end

Internal

↑ top

Public Class Methods

from_bytes( bytes ) click to toggle source

Create a new UUID from an existing 16 byte String

str

The String from which to create the UUID.

Copied from lexical_uuid

Returns

Returns a Torid::UUID

# File lib/torid/uuid.rb, line 79
def self.from_bytes( bytes )
  time_high, time_low, node_high, node_low = bytes.unpack("NNNN")
  timestamp = ( time_high << 32 ) | time_low
  node_id   = ( node_high << 32 ) | node_low
  new( timestamp, node_id )
end
from_string( str ) click to toggle source

Create a new UUID from an existing string in the 8-4-4-4-12 format

str

The String from which to create the UUID.

Copied from lexical_uuid

Returns

Returns a Torid::UUID

# File lib/torid/uuid.rb, line 66
def self.from_string( str )
  hex   = str.split('-').join
  bytes = Array( hex ).pack("H32")
  from_bytes( bytes )
end
new( timestamp = nil, node_id = nil ) click to toggle source

Create a new UUID.

UUID's should only be created by calling one of the public methods that generate id's. See `Torid.uuid` or `Torid::Generator.next`. This constructor should not be called by users of this library.

timestamp

an Integer value representing UNIX timestamp in microseconds

node_id

an Integer value representing the unique node id where this UUID is generatoed

# File lib/torid/uuid.rb, line 102
def initialize( timestamp = nil, node_id = nil )
  @timestamp = timestamp
  @node_id   = node_id
  @bytes     = nil
  @time      = nil
end