Class: Torid::UUID

Inherits:
Object
  • Object
show all
Defined in:
lib/torid/uuid.rb

Overview

Public: 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

Constant Summary collapse

REGEX =

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

%r{([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})}i

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(timestamp = nil, node_id = nil) ⇒ UUID

Internal: 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



102
103
104
105
106
107
 
# 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

Instance Attribute Details

#node_id ⇒ Object (readonly)

Public: The 64bit node id



90
91
92
 
# File 'lib/torid/uuid.rb', line 90

def node_id
  @node_id
end

#timestamp ⇒ Object (readonly)

Public: The 64bit microsecond UNIX timestamp



87
88
89
 
# File 'lib/torid/uuid.rb', line 87

def timestamp
  @timestamp
end

Class Method Details

.from(str) ⇒ Object

Public: 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 a Torid::UUID Raises ArgumentError if the String is not convertable to a UUID.

Raises:

  • (ArgumentError) 


53
54
55
56
57
 
# 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

.from_bytes(bytes) ⇒ Object

Internal: Create a new UUID from an existing 16 byte String

str - The String from which to create the UUID.

Copied from lexical_uuid

Returns a Torid::UUID



79
80
81
82
83
84
 
# 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) ⇒ Object

Internal: 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 a Torid::UUID



66
67
68
69
70
 
# 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

.match(str) ⇒ Object

Public: 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 MatchData or nil if there is no match



36
37
38
 
# File 'lib/torid/uuid.rb', line 36

def self.match( str )
  REGEX.match( str )
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Public: Compare the equality of UUID’s

Examples

uuid == other_uuid

Returns true or false



171
172
173
174
175
 
# 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

#bytes ⇒ Object

Public: 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 a binary String



130
131
132
133
134
135
 
# 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 ⇒ Object

Public: 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



188
189
190
 
# File 'lib/torid/uuid.rb', line 188

def hash
  [node_id, timestamp, ::Torid::UUID].hash
end

#node_id_s ⇒ Object

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



156
157
158
159
160
161
162
 
# 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 ⇒ Object

Public: Return the Time value the internal microsecond timestamp represents.

Examples

uuid.time # => Time

Returns a Time instance



117
118
119
 
# File 'lib/torid/uuid.rb', line 117

def time
  @time ||= Time.at( timestamp / 1_000_000.0 )
end

#to_s ⇒ Object

Public: 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 a String



147
148
149
150
151
152
 
# 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