ruby-ulid 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1179379859a437f04ff904c941372fffc4aa3027d550ae50c67f744e4899d9a
-  data.tar.gz: 71781ee8481373bb7229f10f88a1703b2653c11a4f18cbc7b50eb4adbec58908
+  metadata.gz: cc7674472c14c213d6fe01c6994520b33bc82ab164b538948a4f1b532d0d88f2
+  data.tar.gz: 85987c59ca6f119d40caaf69cc830a8e1b5cc2f9ea3250c315be2f9d8b7faa09
 SHA512:
-  metadata.gz: 6d48e489221851290a486ffe3a39847196e900bb54751fa7d0c808f7580c8838d1a6382b203da1b90ad4f74dd9e998239e0a6c996b06d99881c39489ff607697
-  data.tar.gz: fbef689db966901800b24e18820ee6744aeeaeb2476f14349b74d634ed1e5d359a4bff4abb3eb0eee94e4d0183f5db1420719d7e94afd3e803d21d62510087d7
+  metadata.gz: f56db0a74a7a6559189039a9f7f13a1f514b4fc956f7993a52ca16a7a978b4b93aa352b9f74b72da73c7b0485ebe1f80052d2e3c7b04a1baba231d06ba594f42
+  data.tar.gz: 597260a0eb43c0fdc187aeb961521fbce22c68fc75b35d445e73d60564b72208aaf1e83a8428daa99423e001572f187872f4077445d6bced8b35d197d7e700ff

data/lib/ulid.rb

@@ -18,18 +18,25 @@ class ULID
   class OverflowError < Error; end
   class ParserError < Error; end
 
+  encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
   # Crockford's Base32. Excluded I, L, O, U.
   # @see https://www.crockford.com/base32.html
-  ENCODING_CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.chars.map(&:freeze).freeze
+  ENCODING_CHARS = encoding_string.chars.map(&:freeze).freeze
 
   TIME_PART_LENGTH = 10
   RANDOMNESS_PART_LENGTH = 16
   ENCODED_ID_LENGTH = TIME_PART_LENGTH + RANDOMNESS_PART_LENGTH
-  TIME_OCTETS_LENGTH = 6
+  TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
-  OCTETS_LENGTH = TIME_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
+  OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
+  MAX_INTEGER = 340282366920938463463374607431768211455
+  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIME_PART_LENGTH - 1}})(?<randomness>[#{encoding_string}]{#{RANDOMNESS_PART_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
 
   # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
   # @see https://bugs.ruby-lang.org/issues/15958
@@ -76,7 +83,7 @@ class ULID
 
   MONOTONIC_GENERATOR = MonotonicGenerator.new
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
 
   # @param [Integer, Time] moment
   # @param [Integer] entropy
@@ -100,6 +107,52 @@ class ULID
     MONOTONIC_GENERATOR.generate
   end
 
+  # @param [String, #to_str] string
+  # @return [Enumerator]
+  # @yieldparam [ULID] ulid
+  # @yieldreturn [self]
+  def self.scan(string)
+    string = string.to_str
+    return to_enum(__callee__, string) unless block_given?
+    string.scan(PATTERN) do |pair|
+      yield parse(pair.join)
+    end
+    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
+  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)
+
+    new milliseconds: milliseconds, entropy: entropy
+  end
+
   # @return [Integer]
   def self.current_milliseconds
     time_to_milliseconds(Time.now)
@@ -146,6 +199,29 @@ class ULID
     true
   end
 
+  # @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
+
+  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
+  # @param [Array<Integer>] reversed_digits
+  # @return [Integer]
+  def self.inverse_of_digits(reversed_digits)
+    base = 256
+    num = 0
+    reversed_digits.each do |digit|
+      num = (num * base) + digit
+    end
+    num
+  end
+
   attr_reader :milliseconds, :entropy
 
   # @param [Integer] milliseconds
@@ -172,7 +248,7 @@ class ULID
 
   # @return [Integer]
   def to_i
-    @integer ||= inverse_of_digits(octets)
+    @integer ||= self.class.inverse_of_digits(octets)
   end
   alias_method :hash, :to_i
 
@@ -210,22 +286,42 @@ class ULID
 
   # @return [Time]
   def to_time
-    @time ||= Time.at(0, @milliseconds, :millisecond).utc
+    @time ||= Time.at(0, @milliseconds, :millisecond).utc.freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    @octets ||= (time_octets + randomness_octets).freeze
+    @octets ||= (timestamp_octets + randomness_octets).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
-  def time_octets
-    @time_octets ||= octets_from_integer(@milliseconds, length: TIME_OCTETS_LENGTH).freeze
+  def timestamp_octets
+    @timestamp_octets ||= self.class.octets_from_integer(@milliseconds, length: TIMESTAMP_OCTETS_LENGTH).freeze
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    @randomness_octets ||= octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+    @randomness_octets ||= self.class.octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+  end
+
+  # @return [String]
+  def timestamp
+    @timestamp ||= matchdata[:timestamp].freeze
+  end
+
+  # @return [String]
+  def randomness
+    @randomness ||= matchdata[:randomness].freeze
+  end
+
+  # @return [Regexp]
+  def pattern
+    @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
+  end
+
+  # @return [Regexp]
+  def strict_pattern
+    @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
   end
 
   # @raise [OverflowError] if the next entropy part is larger than the ULID limit
@@ -242,31 +338,14 @@ class ULID
     octets
     succ
     to_i
+    strict_pattern
     super
   end
 
   private
 
-  # @param [Integer] integer
-  # @param [Integer] length
-  # @return [Array<Integer>]
-  def octets_from_integer(integer, length:)
-    digits = integer.digits(256)
-    (length - digits.size).times do
-      digits.push 0
-    end
-    digits.reverse!
-  end
-
-  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
-  # @param [Array<Integer>] reversed_digits
-  # @return [Integer]
-  def inverse_of_digits(reversed_digits)
-    base = 256
-    num = 0
-    reversed_digits.each do |digit|
-      num = (num * base) + digit
-    end
-    num
+  # @return [MatchData]
+  def matchdata
+    @matchdata ||= STRICT_PATTERN.match(to_str).freeze
   end
 end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -5,12 +5,16 @@ class ULID
   TIME_PART_LENGTH: 10
   RANDOMNESS_PART_LENGTH: 16
   ENCODED_ID_LENGTH: 26
-  TIME_OCTETS_LENGTH: 6
+  TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
   MAX_MILLISECONDS: 281474976710655
   MAX_ENTROPY: 1208925819614629174706175
+  MAX_INTEGER: 340282366920938463463374607431768211455
   TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
+  PATTERN: Regexp
+  STRICT_PATTERN: Regexp
+  UUIDV4_PATTERN: Regexp
   MONOTONIC_GENERATOR: MonotonicGenerator
   include Comparable
 
@@ -33,17 +37,24 @@ class ULID
   end
 
   type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
-  type time_octets = [Integer, Integer, Integer, Integer, Integer, Integer]
+  type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer]
   type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer]
 
-  @string: String
-  @integer: Integer
-  @octets: octets
-  @time_octets: time_octets
-  @randomness_octets: randomness_octets
-  @inspect: String
-  @time: Time
-  @next: ULID
+  @milliseconds: Integer
+  @entropy: Integer
+  @string: String?
+  @integer: Integer?
+  @octets: octets?
+  @timestamp_octets: timestamp_octets?
+  @randomness_octets: randomness_octets?
+  @timestamp: String?
+  @randomness: String?
+  @inspect: String?
+  @time: Time?
+  @next: ULID?
+  @pattern: Regexp?
+  @strict_pattern: Regexp?
+  @matchdata: MatchData?
 
   def self.generate: (?moment: Time | Integer, ?entropy: Integer) -> ULID
   def self.monotonic_generate: -> ULID
@@ -51,7 +62,13 @@ class ULID
   def self.time_to_milliseconds: (Time time) -> Integer
   def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> ULID
+  def self.from_uuidv4: (String uuid) -> ULID
+  def self.from_integer: (Integer integer) -> 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.inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
@@ -66,14 +83,17 @@ class ULID
   alias == eql?
   def ===: (untyped other) -> bool
   def to_time: -> Time
+  def timestamp: -> String
+  def randomness: -> String
+  def pattern: -> Regexp
+  def strict_pattern: -> Regexp
   def octets: -> octets
-  def time_octets: -> time_octets
+  def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
   def next: -> ULID
   alias succ next
   def freeze: -> self
 
   private
-  def octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
-  def inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
+  def matchdata: -> MatchData
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-29 00:00:00.000000000 Z
+date: 2021-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base