ruby-ulid 0.0.17 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a9e3cd7ec91b93c24691976fef74ea5ab0cbc8f4fa237f449fa9322e42c6d2
-  data.tar.gz: 9a3c0e12e7d2fe8b6057662ebf6a392c749f7254ee41c4e77221a2e9f45ff6ac
+  metadata.gz: 8b1641b0894c0140c3a9c6f59fa8abcfca386362ad1aaa92fe196f3bf5f75cf1
+  data.tar.gz: 932fa04dceb504330289d4236f9670fecd702989504bdd402873d60c0bb1c0e5
 SHA512:
-  metadata.gz: 53a12c330c32f76f13e651cef96ce29a6a442cf3dc7742faf2409a0ee17c7dfdcee1031c17696cd51d7bd3cf5b22b2df34b8be5a203cd1d4fd5df079eb357b82
-  data.tar.gz: f6c8f8850272353bbd32cc15d437d0b021c13d9bc93c5c988255d6c50fe21ff41aef5b719261ca95b00c129024fe325e2d3c8683c70f9b55e89a09a261fff31f
+  metadata.gz: f073c7b240ef96b511c84c6bc5649c483fc97c62a3892f58531b6f36e8235e49dcd865433fe522eec48a3532c98c4deec8713f453a4b2a117157788eabddaf6b
+  data.tar.gz: a2486bbefd62d0d019c15044c9d67b6aabc33e370f4ee88239c1e2b33a40738c736fcc9221dd3ce457eabf83a3580be5dc501fef0c359345a453331bdd62d139

data/README.md

@@ -49,7 +49,7 @@ Should be installed!
 Add this line to your application/library's `Gemfile` is needed in basic use-case
 
 ```ruby
-gem 'ruby-ulid', '0.0.16'
+gem 'ruby-ulid', '0.0.18'
 ```
 
 ### Generator and Parser
@@ -62,7 +62,11 @@ require 'ulid'
 
 ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
 ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
+ulid.milliseconds #=> 1619544442826
 ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
+ulid.timestamp #=> "01F4A5Y1YA"
+ulid.randomness #=> "QCYAYCTC7GRMJ9AA"
+ulid.to_i #=> 1957909092946624190749577070267409738
 ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
 ```
 
@@ -86,15 +90,16 @@ ulids.uniq(&:to_time).size #=> 1000
 ulids.sort == ulids #=> true
 ```
 
-`ULID.generate` can take fixed `Time` instance
+`ULID.generate` can take fixed `Time` instance. The shorthand is `ULID.at`
 
 ```ruby
 time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
 ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
 ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
+ULID.at(time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB002W5BGWWKN76N22H6)
 
 ulids = 1000.times.map do |n|
-  ULID.generate(moment: time + n)
+  ULID.at(time + n)
 end
 ulids.sort == ulids #=> true
 ```
@@ -173,6 +178,13 @@ ulids.grep_v(one_of_the_above)
 #=> I hope the results should be actually you want!
 ```
 
+If you want to manually handle the Time objects, `ULID.floor` returns new `Time` with truncating excess precisions in ULID spec.
+
+```ruby
+time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.123456789 UTC
+ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
+```
+
 ### Scanner for string (e.g. `JSON`)
 
 For rough operations, `ULID.scan` might be useful.
@@ -215,6 +227,18 @@ ULID.scan(json).to_a
 #  ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
 ```
 
+`ULID#patterns` is a util for text based operations.
+The results and spec are not fixed. Should not be used except snippets/console operation
+
+```ruby
+ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
+#=> returns like a fallowing Hash
+{
+  named_captures: /(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)/i,
+  strict_named_captures: /\A(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)\z/i
+}
+```
+
 ### Some methods to help manipulations
 
 `ULID.min` and `ULID.max` return termination values for ULID spec.
@@ -266,9 +290,12 @@ ULID.sample(5)
 ### UUIDv4 converter for migration use-cases
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
-The imported timestamp is meaningless. So ULID's benefit will lost
+The imported timestamp is meaningless. So ULID's benefit will lost.
 
 ```ruby
+# Currently experimental feature, so needed to load the extension.
+require 'ulid/uuid'
+
 # Basically reversible 
 ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39') #=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
 ulid.to_uuidv4 #=> "0983d0a2-ff15-4d83-8f37-7dd945b5aa39"
@@ -322,7 +349,7 @@ Major methods can be replaced as below.
 -ULID.generate
 +ULID.generate.to_s
 -ULID.at(time)
-+ULID.generate(moment: time).to_s
++ULID.at(time).to_s
 -ULID.time(string)
 +ULID.parse(string).to_time
 -ULID.min_ulid_at(time)

data/lib/ulid.rb

@@ -17,33 +17,44 @@ class ULID
   class ParserError < Error; end
   class SetupError < ScriptError; end
 
+  # `Subset` of Crockford's Base32. Just excluded I, L, O, U, -.
+  # refs:
+  #   * https://www.crockford.com/base32.html
+  #   * https://github.com/ulid/spec/pull/57
+  #   * https://github.com/kachick/ruby-ulid/issues/57
   encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
-  # Crockford's Base32. Excluded I, L, O, U.
-  # @see https://www.crockford.com/base32.html
-  ENCODING_CHARS = encoding_string.chars.map(&:freeze).freeze
+  encoding_chars = encoding_string.chars.map(&:freeze).freeze
 
-  TIMESTAMP_PART_LENGTH = 10
-  RANDOMNESS_PART_LENGTH = 16
-  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  TIMESTAMP_ENCODED_LENGTH = 10
+  RANDOMNESS_ENCODED_LENGTH = 16
+  ENCODED_LENGTH = TIMESTAMP_ENCODED_LENGTH + RANDOMNESS_ENCODED_LENGTH
   TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
   OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
-  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIMESTAMP_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_LENGTH}})/i.freeze
+  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIMESTAMP_ENCODED_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_ENCODED_LENGTH}})/i.freeze
   STRICT_PATTERN = /\A#{PATTERN.source}\z/i.freeze
 
-  # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
-  UUIDV4_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i.freeze
-
   # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
   # @see https://bugs.ruby-lang.org/issues/15958
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
   UNDEFINED = BasicObject.new
+  # @return [String]
+  def UNDEFINED.to_s
+    'ULID::UNDEFINED'
+  end
+
+  # @return [String]
+  def UNDEFINED.inspect
+    to_s
+  end
   Kernel.instance_method(:freeze).bind(UNDEFINED).call
 
+  private_class_method :new
+
   # @param [Integer, Time] moment
   # @param [Integer] entropy
   # @return [ULID]
@@ -51,6 +62,14 @@ class ULID
     new milliseconds: milliseconds_from_moment(moment), entropy: entropy
   end
 
+  # Short hand of `ULID.generate(moment: time)`
+  # @param [Time] time
+  # @return [ULID]
+  def self.at(time)
+    raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === time
+    new milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy
+  end
+
   # @param [Integer, Time] moment
   # @return [ULID]
   def self.min(moment: 0)
@@ -101,38 +120,23 @@ class ULID
     self
   end
 
-  # @param [String, #to_str] uuid
-  # @return [ULID]
-  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
-  def self.from_uuidv4(uuid)
-    begin
-      uuid = uuid.to_str
-      prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
-      raise "given string is not matched to pattern #{UUIDV4_PATTERN.inspect}" unless UUIDV4_PATTERN.match?(prefix_trimmed)
-      normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
-      from_integer(normalized.to_i(16))
-    rescue => err
-      raise ParserError, "parsing failure as #{err.inspect} for given #{uuid}"
-    end
-  end
-
   # @param [Integer, #to_int] integer
   # @return [ULID]
   # @raise [OverflowError] if the given integer is larger than the ULID limit
   # @raise [ArgumentError] if the given integer is negative number
-  # @todo Need optimized for performance
   def self.from_integer(integer)
     integer = integer.to_int
     raise OverflowError, "integer overflow: given #{integer}, max: #{MAX_INTEGER}" unless integer <= MAX_INTEGER
     raise ArgumentError, "integer should not be negative: given: #{integer}" if integer.negative?
 
-    octets = octets_from_integer(integer, length: OCTETS_LENGTH).freeze
-    time_octets = octets.slice(0, TIMESTAMP_OCTETS_LENGTH).freeze
-    randomness_octets = octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH).freeze
-    milliseconds = inverse_of_digits(time_octets)
-    entropy = inverse_of_digits(randomness_octets)
+    n32encoded = integer.to_s(32).rjust(ENCODED_LENGTH, '0')
+    n32encoded_timestamp = n32encoded.slice(0, TIMESTAMP_ENCODED_LENGTH)
+    n32encoded_randomness = n32encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH)
+
+    milliseconds = n32encoded_timestamp.to_i(32)
+    entropy = n32encoded_randomness.to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy
+    new milliseconds: milliseconds, entropy: entropy, integer: integer
   end
 
   # @param [Range<Time>, Range<nil>] time_range
@@ -239,7 +243,7 @@ class ULID
     'Z' => 31
   }.freeze
 
-  N32_CHAR_BY_CROCKFORD_BASE32_CHAR = ENCODING_CHARS.each_with_object({}) do |encoding_char, map|
+  N32_CHAR_BY_CROCKFORD_BASE32_CHAR = encoding_chars.each_with_object({}) do |encoding_char, map|
     if n = crockford_base32_mappings[encoding_char]
       char_32 = n32_char_by_number.fetch(n)
       map[encoding_char] = char_32
@@ -258,21 +262,12 @@ class ULID
     begin
       string = string.to_str
       raise "given argument does not match to `#{STRICT_PATTERN.inspect}`" unless STRICT_PATTERN.match?(string)
-      n32encoded = convert_crockford_base32_to_n32(string.upcase)
-      timestamp = n32encoded.slice(0, TIMESTAMP_PART_LENGTH)
-      randomness = n32encoded.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
-      milliseconds = timestamp.to_i(32)
-      entropy = randomness.to_i(32)
     rescue => err
       raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
     end
 
-    new milliseconds: milliseconds, entropy: entropy
-  end
-
-  # @api private
-  private_class_method def self.convert_crockford_base32_to_n32(string)
-    string.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+    n32encoded = string.upcase.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+    from_integer(n32encoded.to_i(32))
   end
 
   # @return [Boolean]
@@ -284,18 +279,6 @@ class ULID
     true
   end
 
-  # @api private
-  # @param [Integer] integer
-  # @param [Integer] length
-  # @return [Array<Integer>]
-  def self.octets_from_integer(integer, length:)
-    digits = integer.digits(256)
-    (length - digits.size).times do
-      digits.push 0
-    end
-    digits.reverse!
-  end
-
   # @api private
   # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
   # @param [Array<Integer>] reversed_digits
@@ -309,6 +292,15 @@ class ULID
     num
   end
 
+  # @api private
+  # @param [MonotonicGenerator] generator
+  # @return [ULID]
+  def self.from_monotonic_generator(generator)
+    raise ArgumentError, 'this method provided only for MonotonicGenerator' unless MonotonicGenerator === generator
+    new milliseconds: generator.latest_milliseconds, entropy: generator.latest_entropy
+  end
+
+  # @api private
   # @return [ArgumentError]
   private_class_method def self.argument_error_for_range_building(argument)
     ArgumentError.new "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{argument.inspect}"
@@ -319,15 +311,21 @@ class ULID
   # @api private
   # @param [Integer] milliseconds
   # @param [Integer] entropy
+  # @param [Integer] integer
   # @return [void]
   # @raise [OverflowError] if the given value is larger than the ULID limit
   # @raise [ArgumentError] if the given milliseconds and/or entropy is negative number
-  def initialize(milliseconds:, entropy:)
-    milliseconds = milliseconds.to_int
-    entropy = entropy.to_int
-    raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
-    raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
-    raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
+  def initialize(milliseconds:, entropy:, integer: UNDEFINED)
+    if UNDEFINED.equal?(integer)
+      milliseconds = milliseconds.to_int
+      entropy = entropy.to_int
+
+      raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
+      raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
+      raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
+    else
+      @integer = integer
+    end
 
     @milliseconds = milliseconds
     @entropy = entropy
@@ -335,18 +333,22 @@ class ULID
 
   # @return [String]
   def to_s
-    @string ||= convert_n32_to_crockford_base32(to_i.to_s(32).rjust(ENCODED_ID_LENGTH, '0').upcase).freeze
+    @string ||= to_i.to_s(32).upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0').freeze
   end
 
   # @return [Integer]
   def to_i
-    @integer ||= self.class.inverse_of_digits(octets)
+    @integer ||= begin
+      n32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
+      n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
+      (n32encoded_timestamp + n32encoded_randomness).to_i(32)
+    end
   end
   alias_method :hash, :to_i
 
   # @return [Integer, nil]
   def <=>(other)
-    other.kind_of?(ULID) ? (to_i <=> other.to_i) : nil
+    (ULID === other) ? (to_i <=> other.to_i) : nil
   end
 
   # @return [String]
@@ -356,7 +358,7 @@ class ULID
 
   # @return [Boolean]
   def eql?(other)
-    other.equal?(self) || (other.kind_of?(ULID) && other.to_i == to_i)
+    equal?(other) || (ULID === other && to_i == other.to_i)
   end
   alias_method :==, :eql?
 
@@ -389,39 +391,49 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    @octets ||= (timestamp_octets + randomness_octets).freeze
+    @octets ||= octets_from_integer(to_i).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
   def timestamp_octets
-    @timestamp_octets ||= self.class.octets_from_integer(@milliseconds, length: TIMESTAMP_OCTETS_LENGTH).freeze
+    @timestamp_octets ||= octets.slice(0, TIMESTAMP_OCTETS_LENGTH).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    @randomness_octets ||= self.class.octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+    @randomness_octets ||= octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH).freeze
   end
 
   # @return [String]
   def timestamp
-    @timestamp ||= matchdata[:timestamp].freeze
+    @timestamp ||= to_s.slice(0, TIMESTAMP_ENCODED_LENGTH).freeze
   end
 
   # @return [String]
   def randomness
-    @randomness ||= matchdata[:randomness].freeze
+    @randomness ||= to_s.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH).freeze
+  end
+
+  # @note Providing for rough operations. The keys and values is not fixed.
+  # @return [Hash{Symbol => Regexp, String}]
+  def patterns
+    named_captures = /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
+    {
+      named_captures: named_captures,
+      strict_named_captures: /\A#{named_captures.source}\z/i.freeze
+    }
   end
 
-  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
+  # @deprecated Use {#patterns} instead. ref: https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def pattern
-    @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
+    patterns.fetch(:named_captures)
   end
 
-  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
+  # @deprecated Use {#patterns} instead. ref: https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def strict_pattern
-    @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
+    patterns.fetch(:strict_named_captures)
   end
 
   # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
@@ -439,17 +451,6 @@ class ULID
     @pred ||= self.class.from_integer(pre_int)
   end
 
-  # @return [String]
-  def to_uuidv4
-    @uuidv4 ||= begin
-      # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
-      array = octets.pack('C*').unpack('NnnnnN')
-      array[2] = (array[2] & 0x0fff) | 0x4000
-      array[3] = (array[3] & 0x3fff) | 0x8000
-      ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
-    end
-  end
-
   # @return [self]
   def freeze
     # Need to cache before freezing, because frozen objects can't assign instance variables
@@ -459,14 +460,14 @@ class ULID
 
   private
 
-  # @api private
-  def convert_n32_to_crockford_base32(string)
-    string.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR)
-  end
-
-  # @return [MatchData]
-  def matchdata
-    @matchdata ||= STRICT_PATTERN.match(to_s).freeze
+  # @param [Integer] integer
+  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
+  def octets_from_integer(integer)
+    digits = integer.digits(256)
+    (OCTETS_LENGTH - digits.size).times do
+      digits.push 0
+    end
+    digits.reverse!
   end
 
   # @return [void]
@@ -476,8 +477,8 @@ class ULID
     to_i
     succ
     pred
-    strict_pattern
-    to_uuidv4
+    timestamp
+    randomness
   end
 end
 
@@ -488,5 +489,5 @@ class ULID
   MIN = parse('00000000000000000000000000').freeze
   MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX, :CROCKFORD_BASE32_CHAR_PATTERN, :N32_CHAR_BY_CROCKFORD_BASE32_CHAR, :CROCKFORD_BASE32_CHAR_BY_N32_CHAR, :N32_CHAR_PATTERN, :UNDEFINED
+  private_constant :TIME_FORMAT_IN_INSPECT, :MIN, :MAX, :CROCKFORD_BASE32_CHAR_PATTERN, :N32_CHAR_BY_CROCKFORD_BASE32_CHAR, :CROCKFORD_BASE32_CHAR_BY_N32_CHAR, :N32_CHAR_PATTERN, :UNDEFINED
 end

data/lib/ulid/monotonic_generator.rb

@@ -26,7 +26,7 @@ class ULID
         @latest_entropy += 1
       end
 
-      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
+      ULID.from_monotonic_generator(self)
     end
 
     # @api private

data/lib/ulid/uuid.rb

@@ -0,0 +1,37 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+# Extracted features around UUID from some reasons
+# ref:
+#  * https://github.com/kachick/ruby-ulid/issues/105
+#  * https://github.com/kachick/ruby-ulid/issues/76
+class ULID
+  # Imported from https://stackoverflow.com/a/38191104/1212807, thank you!
+  UUIDV4_PATTERN = /\A[0-9A-F]{8}-[0-9A-F]{4}-[4][0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}\z/i.freeze
+  private_constant :UUIDV4_PATTERN
+
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    begin
+      uuid = uuid.to_str
+      prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
+      raise "given string is not matched to pattern #{UUIDV4_PATTERN.inspect}" unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+      from_integer(normalized.to_i(16))
+    rescue => err
+      raise ParserError, "parsing failure as #{err.inspect} for given #{uuid}"
+    end
+  end
+
+  # @return [String]
+  def to_uuidv4
+    # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
+    array = octets.pack('C*').unpack('NnnnnN')
+    array[2] = (array[2] & 0x0fff) | 0x4000
+    array[3] = (array[3] & 0x3fff) | 0x8000
+    ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
+  end
+end

data/lib/ulid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 class ULID
-  VERSION = '0.0.17'
+  VERSION = '0.0.18'
 end

data/sig/ulid.rbs

@@ -1,10 +1,9 @@
 # Classes
 class ULID
   VERSION: String
-  ENCODING_CHARS: Array[String]
-  TIMESTAMP_PART_LENGTH: 10
-  RANDOMNESS_PART_LENGTH: 16
-  ENCODED_ID_LENGTH: 26
+  TIMESTAMP_ENCODED_LENGTH: 10
+  RANDOMNESS_ENCODED_LENGTH: 16
+  ENCODED_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
@@ -64,12 +63,9 @@ class ULID
   @inspect: String?
   @time: Time?
   @next: ULID?
-  @pattern: Regexp?
-  @strict_pattern: Regexp?
-  @uuidv4: String?
-  @matchdata: MatchData?
 
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
+  def self.at: (Time time) -> ULID
   def self.current_milliseconds: -> Integer
   def self.milliseconds_from_time: (Time time) -> Integer
   def self.milliseconds_from_moment: (moment moment) -> Integer
@@ -86,16 +82,17 @@ class ULID
   def self.valid?: (untyped string) -> bool
   def self.scan:  (String string) -> Enumerator[ULID, singleton(ULID)]
                 | (String string) { (ULID ulid) -> void } -> singleton(ULID)
-  def self.octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
+  def self.octets_from_integer: (Integer integer) -> octets
   def self.inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
+  def self.from_monotonic_generator: (MonotonicGenerator generator) -> ULID
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
-  def initialize: (milliseconds: Integer, entropy: Integer) -> void
+  def initialize: (milliseconds: Integer, entropy: Integer, ?integer: Integer) -> void
   def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
   def <=>: (ULID other) -> Integer
-         | (untyped other) -> Integer?
+         | (untyped other) -> nil
   def inspect: -> String
   def eql?: (untyped other) -> bool
   alias == eql?
@@ -103,6 +100,7 @@ class ULID
   def to_time: -> Time
   def timestamp: -> String
   def randomness: -> String
+  def patterns: -> Hash[Symbol, Regexp | String]
   def pattern: -> Regexp
   def strict_pattern: -> Regexp
   def octets: -> octets
@@ -115,9 +113,6 @@ class ULID
   def freeze: -> self
 
   private
-  def self.convert_crockford_base32_to_n32: (String) -> String
   def self.argument_error_for_range_building: (untyped argument) -> ArgumentError
-  def convert_n32_to_crockford_base32: (String) -> String
-  def matchdata: -> MatchData
   def cache_all_instance_variables: -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.18
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-06 00:00:00.000000000 Z
+date: 2021-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rbs
@@ -78,6 +78,7 @@ files:
 - README.md
 - lib/ulid.rb
 - lib/ulid/monotonic_generator.rb
+- lib/ulid/uuid.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid