ruby-ulid 0.7.0 → 0.8.0

data/lib/ulid.rb

@@ -9,6 +9,7 @@ require_relative('ulid/version')
 require_relative('ulid/errors')
 require_relative('ulid/crockford_base32')
 require_relative('ulid/utils')
+require_relative('ulid/uuid')
 require_relative('ulid/monotonic_generator')
 
 # @see https://github.com/ulid/spec
@@ -23,8 +24,6 @@ class ULID
   RANDOMNESS_ENCODED_LENGTH = 16
   ENCODED_LENGTH = 26
 
-  TIMESTAMP_OCTETS_LENGTH = 6
-  RANDOMNESS_OCTETS_LENGTH = 10
   OCTETS_LENGTH = 16
 
   MAX_MILLISECONDS = 281474976710655
@@ -33,12 +32,12 @@ class ULID
 
   # @see https://github.com/ulid/spec/pull/57
   # Currently not used as a constant, but kept as a reference for now.
-  PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /(?<timestamp>[0-7][#{CrockfordBase32::ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}})(?<randomness>[#{CrockfordBase32::ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}})/i.freeze
+  PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /(?<timestamp>[0-7][#{CrockfordBase32::ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}})(?<randomness>[#{CrockfordBase32::ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}})/i
 
-  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /\A#{PATTERN_WITH_CROCKFORD_BASE32_SUBSET.source}\z/i.freeze
+  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /\A#{PATTERN_WITH_CROCKFORD_BASE32_SUBSET.source}\z/i
 
   # Optimized for `ULID.scan`, might be changed the definition with gathered `ULID.scan` spec changed.
-  SCANNING_PATTERN = /\b[0-7][#{CrockfordBase32::ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CrockfordBase32::ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}\b/i.freeze
+  SCANNING_PATTERN = /\b[0-7][#{CrockfordBase32::ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CrockfordBase32::ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}\b/i
 
   # Similar as Time#inspect since Ruby 2.7, however it is NOT same.
   # Time#inspect trancates needless digits. Keeping full milliseconds with "%3N" will fit for ULID.
@@ -50,17 +49,19 @@ class ULID
     SecureRandom.random_number(MAX_INTEGER)
   }.freeze
 
-  Utils.make_sharable_constantans(self)
+  Utils.make_sharable_constants(self)
 
   private_constant(
     :PATTERN_WITH_CROCKFORD_BASE32_SUBSET,
     :STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET,
     :SCANNING_PATTERN,
     :TIME_FORMAT_IN_INSPECT,
-    :RANDOM_INTEGER_GENERATOR
+    :RANDOM_INTEGER_GENERATOR,
+    :OCTETS_LENGTH,
+    :UUID
   )
 
-  private_class_method(:new)
+  private_class_method(:new, :allocate)
 
   # @param [Integer, Time] moment
   # @param [Integer] entropy
@@ -69,12 +70,12 @@ class ULID
   # @raise [ArgumentError] if the given milliseconds and/or entropy is negative number
   def self.generate(moment: Utils.current_milliseconds, entropy: Utils.reasonable_entropy)
     milliseconds = Utils.milliseconds_from_moment(moment)
-    base32_encoded = Utils.encode_base32(milliseconds: milliseconds, entropy: entropy)
+    base32hex = Utils.encode_base32hex(milliseconds:, entropy:)
     new(
-      milliseconds: milliseconds,
-      entropy: entropy,
-      integer: base32_encoded.to_i(32),
-      encoded: CrockfordBase32.from_base32(base32_encoded).freeze
+      milliseconds:,
+      entropy:,
+      integer: Integer(base32hex, 32, exception: true),
+      encoded: CrockfordBase32.from_base32hex(base32hex).freeze
     )
   end
 
@@ -84,8 +85,8 @@ class ULID
   # @param [Integer] entropy
   # @return [String]
   def self.encode(moment: Utils.current_milliseconds, entropy: Utils.reasonable_entropy)
-    base32_encoded = Utils.encode_base32(milliseconds: Utils.milliseconds_from_moment(moment), entropy: entropy)
-    CrockfordBase32.from_base32(base32_encoded)
+    base32hex = Utils.encode_base32hex(milliseconds: Utils.milliseconds_from_moment(moment), entropy:)
+    CrockfordBase32.from_base32hex(base32hex)
   end
 
   # Short hand of `ULID.generate(moment: time)`
@@ -100,13 +101,13 @@ class ULID
   # @param [Time, Integer] moment
   # @return [ULID]
   def self.min(moment=0)
-    0.equal?(moment) ? MIN : generate(moment: moment, entropy: 0)
+    0.equal?(moment) ? MIN : generate(moment:, entropy: 0)
   end
 
   # @param [Time, Integer] moment
   # @return [ULID]
   def self.max(moment=MAX_MILLISECONDS)
-    MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment: moment, entropy: MAX_ENTROPY)
+    MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment:, entropy: MAX_ENTROPY)
   end
 
   # @param [Range<Time>, Range<nil>, Range[ULID], nil] period
@@ -181,20 +182,20 @@ class ULID
     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?
 
-    base32encoded = integer.to_s(32).rjust(ENCODED_LENGTH, '0')
-    base32encoded_timestamp = base32encoded.slice(0, TIMESTAMP_ENCODED_LENGTH)
-    base32encoded_randomness = base32encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH)
+    base32hex = integer.to_s(32).rjust(ENCODED_LENGTH, '0')
+    base32hex_timestamp = base32hex.slice(0, TIMESTAMP_ENCODED_LENGTH)
+    base32hex_randomness = base32hex.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH)
 
-    raise(UnexpectedError) unless base32encoded_timestamp && base32encoded_randomness
+    raise(UnexpectedError) unless base32hex_timestamp && base32hex_randomness
 
-    milliseconds = base32encoded_timestamp.to_i(32)
-    entropy = base32encoded_randomness.to_i(32)
+    milliseconds = Integer(base32hex_timestamp, 32, exception: true)
+    entropy = Integer(base32hex_randomness, 32, exception: true)
 
     new(
-      milliseconds: milliseconds,
-      entropy: entropy,
-      integer: integer,
-      encoded: CrockfordBase32.from_base32(base32encoded).freeze
+      milliseconds:,
+      entropy:,
+      integer:,
+      encoded: CrockfordBase32.from_base32hex(base32hex).freeze
     )
   end
 
@@ -205,12 +206,10 @@ class ULID
     raise(ArgumentError, 'ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`') unless Range === period
 
     begin_element, end_element, exclude_end = period.begin, period.end, period.exclude_end?
-    new_begin, new_end = false, false
 
     begin_ulid = (
       case begin_element
       when Time
-        new_begin = true
         min(begin_element)
       when nil
         MIN
@@ -224,7 +223,6 @@ class ULID
     end_ulid = (
       case end_element
       when Time
-        new_end = true
         exclude_end ? min(end_element) : max(end_element)
       when nil
         exclude_end = false
@@ -237,9 +235,6 @@ class ULID
       end
     )
 
-    begin_ulid.freeze if new_begin
-    end_ulid.freeze if new_end
-
     Range.new(begin_ulid, end_ulid, exclude_end)
   end
 
@@ -283,7 +278,7 @@ class ULID
   # @return [Time]
   # @raise [ParserError] if the given format is not correct for ULID specs
   def self.decode_time(string, in: 'UTC')
-    in_for_time_at = binding.local_variable_get(:in) # Needed because `in` is a reserved word.
+    in_for_time_at = { in: }.fetch(:in)
     string = String.try_convert(string)
     raise(ArgumentError, 'ULID.decode_time takes only strings') unless string
 
@@ -304,7 +299,7 @@ class ULID
     raise(ArgumentError, 'ULID.normalize takes only strings') unless string
 
     # Ensure the ULID correctness, because CrockfordBase32 does not always mean to satisfy ULID format
-    parse_variant_format(string).to_s
+    parse_variant_format(string).encode
   end
 
   # @param [String, #to_str] string
@@ -327,19 +322,6 @@ class ULID
     true
   end
 
-  # @deprecated Use [.valid_as_variant_format?] or [.normalized?] instead
-  #
-  # Returns `true` if it is normalized string.
-  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
-  #
-  # @return [Boolean]
-  def self.valid?(string)
-    warn_kwargs = (RUBY_VERSION >= '3.0') ? { category: :deprecated } : {}
-    Warning.warn('ULID.valid? is deprecated. Use ULID.valid_as_variant_format? or ULID.normalized? instead.', **warn_kwargs)
-    string = String.try_convert(string)
-    string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
-  end
-
   # @param [ULID, #to_ulid] object
   # @return [ULID, nil]
   # @raise [TypeError] if `object.to_ulid` did not return ULID instance
@@ -359,7 +341,36 @@ class ULID
     end
   end
 
-  attr_reader(:milliseconds, :entropy)
+  # @param [String, #to_str] uuidish
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUID`ish` format
+  def self.from_uuidish(uuidish)
+    from_integer(UUID.parse_any_to_int(uuidish))
+  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)
+    from_integer(UUID.parse_v4_to_int(uuid))
+  end
+
+  attr_reader(:milliseconds, :entropy, :encoded)
+  protected(:encoded)
+
+  # @param [Integer] milliseconds
+  # @param [Integer] entropy
+  # @param [Integer] integer
+  # @param [String] encoded
+  # @return [void]
+  def initialize(milliseconds:, entropy:, integer:, encoded:)
+    # All arguments check should be done with each constructors, not here
+    @integer = integer
+    @encoded = encoded
+    @milliseconds = milliseconds
+    @entropy = entropy
+    freeze
+  end
 
   # @return [String]
   def encode
@@ -384,7 +395,7 @@ class ULID
 
   # @return [String]
   def inspect
-    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{@encoded})".freeze
+    "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{@encoded})"
   end
 
   # @return [Boolean]
@@ -417,47 +428,25 @@ class ULID
   end
 
   # @return [Time]
-  def to_time
-    @time ||= Time.at(0, @milliseconds, :millisecond, in: 'UTC').freeze
+  # @param [String, Integer, nil] in
+  def to_time(in: 'UTC')
+    Time.at(0, @milliseconds, :millisecond, in: { in: }.fetch(:in))
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
     digits = @integer.digits(256)
-    (OCTETS_LENGTH - digits.size).times do
-      digits.push(0)
-    end
-    digits.reverse!
-  end
-
-  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer)]
-  def timestamp_octets
-    octets.slice(0, TIMESTAMP_OCTETS_LENGTH) || raise(UnexpectedError)
-  end
-
-  # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
-  def randomness_octets
-    octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH) || raise(UnexpectedError)
+    digits.fill(0, digits.size, OCTETS_LENGTH - digits.size).reverse
   end
 
   # @return [String]
   def timestamp
-    @timestamp ||= (@encoded.slice(0, TIMESTAMP_ENCODED_LENGTH).freeze || raise(UnexpectedError))
+    @encoded.slice(0, TIMESTAMP_ENCODED_LENGTH) || raise(UnexpectedError)
   end
 
   # @return [String]
   def randomness
-    @randomness ||= (@encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH).freeze || raise(UnexpectedError))
-  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
-    }
+    @encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH) || raise(UnexpectedError)
   end
 
   # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
@@ -489,13 +478,6 @@ class ULID
     end
   end
 
-  # @return [self]
-  def freeze
-    # Need to cache before freezing, because frozen objects can't assign instance variables
-    cache_all_instance_variables
-    super
-  end
-
   # @return [Integer]
   def marshal_dump
     @integer
@@ -509,7 +491,7 @@ class ULID
       integer: unmarshaled.to_i,
       milliseconds: unmarshaled.milliseconds,
       entropy: unmarshaled.entropy,
-      encoded: unmarshaled.to_s
+      encoded: unmarshaled.encoded
     )
   end
 
@@ -518,45 +500,49 @@ class ULID
     self
   end
 
-  # @return [self]
-  def dup
-    self
-  end
-
-  # @return [self]
-  def clone(freeze: true)
-    self
+  # Generate a UUID-like string that does not set the version and variants field.
+  # It means wrong in UUIDv4 spec, but reversible
+  #
+  # @return [String]
+  def to_uuidish
+    UUID::Fields.raw_from_octets(octets).to_s.freeze
   end
 
-  undef_method(:instance_variable_set)
+  # Generate a UUIDv4-like string that sets the version and variants field.
+  # It may conform to the UUID specification, but it is irreversible with the source ULID and may conflict with some other ULIDs.
+  # You can specify `force` keyword argument to turn off the irreversible check
+  #
+  # @raise [IrreversibleUUIDError] if the converted UUID cannot be reversible with the replacing above 2 fields
+  # @see https://github.com/kachick/ruby-ulid/issues/76
+  # @param [bool] force
+  # @return [String]
+  def to_uuidv4(force: false)
+    v4 = UUID::Fields.forced_v4_from_octets(octets)
+    unless force
+      uuidish = UUID::Fields.raw_from_octets(octets)
+      raise(IrreversibleUUIDError) unless uuidish == v4
+    end
 
-  private
+    v4.to_s.freeze
+  end
 
-  # @param [Integer] milliseconds
-  # @param [Integer] entropy
-  # @param [Integer] integer
-  # @param [String] encoded
-  # @return [void]
-  def initialize(milliseconds:, entropy:, integer:, encoded:)
-    # All arguments check should be done with each constructors, not here
-    @integer = integer
-    @encoded = encoded
-    @milliseconds = milliseconds
-    @entropy = entropy
+  # @return [ULID]
+  def dup
+    super.freeze
   end
 
-  # @return [void]
-  def cache_all_instance_variables
-    inspect
-    timestamp
-    randomness
+  # @return [ULID]
+  def clone(freeze: true)
+    raise(ArgumentError, 'unfreezing ULID is an unexpected operation') unless freeze == true
+
+    super
   end
 
-  MIN = parse('00000000000000000000000000').freeze
-  MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
+  MIN = parse('00000000000000000000000000')
+  MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ')
 
-  Utils.make_sharable_value(MIN)
-  Utils.make_sharable_value(MAX)
+  Ractor.make_shareable(MIN)
+  Ractor.make_shareable(MAX)
 
   private_constant(:MIN, :MAX)
 end