Class: Lobster::Uuid

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/lobster/uuid.rb

Overview

Note:

The naming scheme used for this class is as follows:

  • uuid - An instance of this class.

  • value - Packed string, not human readable. 16 bytes in length.

  • uuid_str - Formatted string, human readable. Formatted as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-12).

Universally unique identifier.

Constant Summary collapse

DEFAULT =

Empty UUID.

Returns:

  • (Uuid)

    UUID with the value 00000000-0000-0000-0000-000000000000.

Uuid.new("\x0" * 16).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value = nil) ⇒ Uuid

Creates a new randomly generated UUID or one from an existing value.

Parameters:

  • value (String, nil) (defaults to: nil)

    When omitted, a random UUID is generated. When specified, a UUID will be created with its value. The value must be a string of 16 bytes (128 bits).



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# File 'lib/lobster/uuid.rb', line 22

def initialize(value = nil)
  if value.nil?
    # When the value is omitted, generate a new, random UUID.
    @value = generate_new

  elsif value.is_a? String
    # A value was provided. It should contain the packed value.
    fail ArgumentError, 'Packed UUID value must be 16 bytes.' unless value.length == 16
    @value = value

  else
    # Got something unexpected.
    fail ArgumentError

  end

  # Prevent modification.
  @value.freeze
end

Instance Attribute Details

#valueString (readonly)

Raw, packed byte string containing the UUID's value.

Returns:

  • (String)

    Packed string, 16 bytes in length.



16
17
18
# File 'lib/lobster/uuid.rb', line 16

def value
  @value
end

Class Method Details

.parse(uuid_str) ⇒ Uuid?

Note:

Casing does not matter for a-f.

Creates a UUID object from its string representation.

Parameters:

  • uuid_str (String)

    UUID in string form. The string must be in the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-12)

Returns:

  • (Uuid, nil)

    nil will be returned if the string doesn't have a properly formatted UUID.



83
84
85
86
87
88
89
90
91
92
93
# File 'lib/lobster/uuid.rb', line 83

def self.parse(uuid_str)
  if valid_str?(uuid_str)
    # Properly formatted UUID string.
    # Pack the UUID into a byte string and return a new instance.
    value = pack_uuid_str(uuid_str)
    Uuid.new(value)
  else
    # Not properly formatted.
    nil
  end
end

.valid_str?(uuid_str) ⇒ Boolean

Determines whether a string contains a valid formatted UUID.

Parameters:

  • uuid_str (String)

    String to check.

Returns:

  • (Boolean)

    true if the string contains a valid formatted UUID, false otherwise.



55
56
57
58
59
60
61
62
63
64
# File 'lib/lobster/uuid.rb', line 55

def self.valid_str?(uuid_str)
  if uuid_str.is_a? String
    # Check the formatting.
    # Note that the validity of the UUID isn't checked.
    !!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.match(uuid_str)
  else
    # A string wasn't passed in.
    fail ArgumentError
  end
end

Instance Method Details

#<=>(other) ⇒ Fixnum

Compares two UUIDs to each other to determine which is lower.

Parameters:

  • other (Uuid, String)

    Other object to compare against.

Returns:

  • (Fixnum)

    -1 if the left UUID is smaller, 0 if they're the same, or 1 if the right UUID is smaller. nil will be returned if the right side isn't a UUID.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
# File 'lib/lobster/uuid.rb', line 160

def <=>(other)
  case other
    when Uuid
      # Compare two UUID instances.
      cmp_uuid(other)

    when String
      if other.length == 16
        # Compare against a packed string
        cmp_packed(other)

      else
        # Compare against a formatted string
        cmp_formatted(other)
      end

    else
      # Everything else can't be compared.
      nil
  end
end

#==(other) ⇒ Boolean

Checks if two UUIDs have the same value.

Parameters:

  • other (Uuid, String)

    Other object to check against.

Returns:

  • (Boolean)

    true if the UUIDs are equal or false if they aren't.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# File 'lib/lobster/uuid.rb', line 98

def ==(other)
  case other
    when Uuid
      # Compare two UUID instances.
      eq_uuid(other)

    when String
      if other.length == 16
        # Compare against a packed string
        eq_packed(other)

      else
        # Compare against a formatted string
        eq_formatted(other)
      end

    else
      # Everything else can't be equated.
      false
  end
end

#hashFixnum

Produces a hash value of the UUID.

Returns:

  • (Fixnum)


224
225
226
# File 'lib/lobster/uuid.rb', line 224

def hash
  Digest::MurmurHash2A.rawdigest(@value)
end

#to_sString

Produces the string representation of the UUID.

Returns:

  • (String)

    UUID in string form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-12)



230
231
232
233
# File 'lib/lobster/uuid.rb', line 230

def to_s
  bytes = @value.bytes
  sprintf('%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x', *bytes)
end