ruby-ulid 0.0.19 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 646d2a4b433ffbe28d4801483d3f1c43cfb5839bf5f80e759447304a1c8dad52
-  data.tar.gz: 1e4ddc37266eb09f3635ba5509e66e6ff93e15fad3e6574fb3b50e8ad9322b10
+  metadata.gz: f0aff39d0f8044f373d8dcdea149f26501e0118dfc0876f060b1b757a4d2a49e
+  data.tar.gz: 02df0ea7a5fe5f8dabd1179988cfe4c2574debf3ad7200d11445eef932dd7443
 SHA512:
-  metadata.gz: 9a564dbad8c3c88b729353826c599e618cd8963806759ce8a6bf041a95aef60044c8f75873560129bcef7550eec226c3bf04bcfec339c4b07fb72c3372342811
-  data.tar.gz: 187c475f9332cb69827e2664193faa7f001cb14a5709b3c28600286ac9e6c1fb3176e14e3a7ae3a658d232af6157a3dea83ad992cee75db966ff80213c3a0e52
+  metadata.gz: ab036ed40e4f2740de9d37e44d2c6d4d233fa0071f95383accb2334c4d1f85b30b24eea902e0e29c34fefc8749b8caf5d1f9df6c52f93fe2e76c89aa0912d11e
+  data.tar.gz: d8ac11f63e5b301ed8b1eacd0d1211fd4b3a0bd79ccae8fe87050833cf305a7345da1dc136b95ecccfcafc6110cf9a281afb0f15db1fe2e01984bf320f82b7e5

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.19'
+gem 'ruby-ulid', '>= 0.1.0', '< 0.2.0'
 ```
 
 ### Generator and Parser
@@ -243,13 +243,15 @@ ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
 
 `ULID.min` and `ULID.max` return termination values for ULID spec.
 
+It can take `Time` instance as an optional argument. Then returns min/max ID that has limit of randomness part in the time.
+
 ```ruby
 ULID.min #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000)
 ULID.max #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ)
 
 time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.123456789 UTC
-ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
-ULID.max(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
+ULID.min(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V0000000000000000)
+ULID.max(time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3VZZZZZZZZZZZZZZZZ)
 ```
 
 `ULID#next` and `ULID#succ` returns next(successor) ULID.
@@ -388,9 +390,9 @@ Major methods can be replaced as below.
 -ULID.time(string)
 +ULID.parse(string).to_time
 -ULID.min_ulid_at(time)
-+ULID.min(moment: time).to_s
++ULID.min(time).to_s
 -ULID.max_ulid_at(time)
-+ULID.max(moment: time).to_s
++ULID.max(time).to_s
 ```
 
 NOTE: It is still having precision issue similar as `ulid gem` in the both generator and parser. I sent PRs.

data/lib/ulid.rb

@@ -51,7 +51,7 @@ class ULID
   # @param [Integer] entropy
   # @return [ULID]
   def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
-    new milliseconds: milliseconds_from_moment(moment), entropy: entropy
+    from_milliseconds_and_entropy(milliseconds: milliseconds_from_moment(moment), entropy: entropy)
   end
 
   # Short hand of `ULID.generate(moment: time)`
@@ -59,18 +59,18 @@ class ULID
   # @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
+    from_milliseconds_and_entropy(milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy)
   end
 
-  # @param [Integer, Time] moment
+  # @param [Time, Integer] moment
   # @return [ULID]
-  def self.min(moment: 0)
+  def self.min(moment=0)
     0.equal?(moment) ? MIN : generate(moment: moment, entropy: 0)
   end
 
-  # @param [Integer, Time] moment
+  # @param [Time, Integer] moment
   # @return [ULID]
-  def self.max(moment: MAX_MILLISECONDS)
+  def self.max(moment=MAX_MILLISECONDS)
     MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment: moment, entropy: MAX_ENTROPY)
   end
 
@@ -112,11 +112,11 @@ class ULID
       raise ArgumentError, 'accepts no argument or integer only' unless Integer === number
 
       if number > MAX_INTEGER || number.negative?
-        raise ArgumentError, "given number #{number} is larger than ULID limit #{MAX_INTEGER} or negative: #{number.inspect}"
+        raise ArgumentError, "given number `#{number}` is larger than ULID limit `#{MAX_INTEGER}` or negative"
       end
 
       if period && (number > possibilities)
-        raise ArgumentError, "given number #{number} is larger than given possibilities #{possibilities}"
+        raise ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`"
       end
 
       Array.new(number) { from_integer(int_generator.call) }
@@ -139,12 +139,12 @@ class ULID
     self
   end
 
-  # @param [Integer, #to_int] integer
+  # @param [Integer] 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 ArgumentError, 'ULID.from_integer takes only `Integer`' unless Integer === integer
     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?
 
@@ -160,29 +160,29 @@ class ULID
 
   # @param [Range<Time>, Range<nil>, Range[ULID]] period
   # @return [Range<ULID>]
-  # @raise [ArgumentError] if the given period is not a `Range[Time]` or `Range[nil]`
+  # @raise [ArgumentError] if the given period is not a `Range[Time]`, `Range[nil]` or `Range[ULID]`
   def self.range(period)
-    raise ArgumentError, 'ULID.range takes only `Range[Time]` or `Range[nil]`' unless Range === period
+    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?
     return period if self === begin_element && self === end_element
 
     case begin_element
     when Time
-      begin_ulid = min(moment: begin_element)
+      begin_ulid = min(begin_element)
     when nil
       begin_ulid = MIN
     when self
       begin_ulid = begin_element
     else
-      raise ArgumentError, "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{period.inspect}"
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
     case end_element
     when Time
       if exclude_end
-        end_ulid = min(moment: end_element)
+        end_ulid = min(end_element)
       else
-        end_ulid = max(moment: end_element)
+        end_ulid = max(end_element)
       end
     when nil
       # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
@@ -191,7 +191,7 @@ class ULID
     when self
       end_ulid = end_element
     else
-      raise ArgumentError, "ULID.range takes only `Range[Time]` or `Range[nil]`, given: #{period.inspect}"
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
     begin_ulid.freeze
@@ -218,6 +218,7 @@ class ULID
     milliseconds_from_time(Time.now)
   end
 
+  # @api private
   # @param [Time] time
   # @return [Integer]
   private_class_method def self.milliseconds_from_time(time)
@@ -266,11 +267,22 @@ class ULID
   end
 
   # @api private
-  # @param [MonotonicGenerator] generator
+  # @param [Integer] milliseconds
+  # @param [Integer] entropy
   # @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
+  # @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 self.from_milliseconds_and_entropy(milliseconds:, entropy:)
+    raise ArgumentError, 'milliseconds and entropy should be an `Integer`' unless Integer === milliseconds && Integer === entropy
+    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?
+
+    n32encoded_timestamp = milliseconds.to_s(32).rjust(TIMESTAMP_ENCODED_LENGTH, '0')
+    n32encoded_randomness = entropy.to_s(32).rjust(RANDOMNESS_ENCODED_LENGTH, '0')
+    integer = (n32encoded_timestamp + n32encoded_randomness).to_i(32)
+
+    new milliseconds: milliseconds, entropy: entropy, integer: integer
   end
 
   attr_reader :milliseconds, :entropy
@@ -280,42 +292,27 @@ class ULID
   # @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:, integer: nil)
-    if integer
-      @integer = integer
-    else
-      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?
-    end
-
+  def initialize(milliseconds:, entropy:, integer:)
+    # All arguments check should be done with each constructors, not here
+    @integer = integer
     @milliseconds = milliseconds
     @entropy = entropy
   end
 
   # @return [String]
   def to_s
-    @string ||= CrockfordBase32.encode(to_i).freeze
+    @string ||= CrockfordBase32.encode(@integer).freeze
   end
 
   # @return [Integer]
   def to_i
-    @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
+    @integer
   end
   alias_method :hash, :to_i
 
   # @return [Integer, nil]
   def <=>(other)
-    (ULID === other) ? (to_i <=> other.to_i) : nil
+    (ULID === other) ? (@integer <=> other.to_i) : nil
   end
 
   # @return [String]
@@ -325,7 +322,7 @@ class ULID
 
   # @return [Boolean]
   def eql?(other)
-    equal?(other) || (ULID === other && to_i == other.to_i)
+    equal?(other) || (ULID === other && @integer == other.to_i)
   end
   alias_method :==, :eql?
 
@@ -333,7 +330,7 @@ class ULID
   def ===(other)
     case other
     when ULID
-      to_i == other.to_i
+      @integer == other.to_i
     when String
       to_s == other.upcase
     else
@@ -354,7 +351,7 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    digits = to_i.digits(256)
+    digits = @integer.digits(256)
     (OCTETS_LENGTH - digits.size).times do
       digits.push 0
     end
@@ -393,7 +390,7 @@ class ULID
 
   # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
   def succ
-    succ_int = to_i.succ
+    succ_int = @integer.succ
     if succ_int >= MAX_INTEGER
       if succ_int == MAX_INTEGER
         MAX
@@ -408,7 +405,7 @@ class ULID
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
-    pred_int = to_i.pred
+    pred_int = @integer.pred
     if pred_int <= 0
       if pred_int == 0
         MIN
@@ -427,6 +424,18 @@ class ULID
     super
   end
 
+  # @return [self]
+  def dup
+    self
+  end
+
+  # @return [self]
+  def clone(freeze: true)
+    self
+  end
+
+  undef_method :instance_variable_set
+
   private
 
   # @return [void]

data/lib/ulid/monotonic_generator.rb

@@ -27,7 +27,7 @@ class ULID
         else
           @latest_entropy += 1
         end
-        ULID.from_monotonic_generator(self)
+        ULID.from_milliseconds_and_entropy(milliseconds: @latest_milliseconds, entropy: @latest_entropy)
       end
     end
 

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -63,33 +63,33 @@ class ULID
   @milliseconds: Integer
   @entropy: Integer
   @string: String?
-  @integer: Integer?
+  @integer: Integer
   @timestamp: String?
   @randomness: String?
   @inspect: String?
   @time: Time?
 
-  def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
-  def self.at: (Time time) -> ULID
+  def self.generate: (?moment: moment, ?entropy: Integer) -> self
+  def self.at: (Time time) -> self
   def self.current_milliseconds: -> Integer
   def self.milliseconds_from_moment: (moment moment) -> Integer
   def self.range: (period period) -> Range[ULID]
   def self.floor: (Time time) -> Time
   def self.reasonable_entropy: -> Integer
-  def self.parse: (String string) -> ULID
+  def self.parse: (String string) -> self
   def self.from_uuidv4: (String uuid) -> ULID
-  def self.from_integer: (Integer integer) -> ULID
-  def self.min: (?moment: moment) -> ULID
-  def self.max: (?moment: moment) -> ULID
-  def self.sample: (?period: period) -> ULID
-                 | (Integer number, ?period: period) -> Array[ULID]
+  def self.from_integer: (Integer integer) -> self
+  def self.min: (?moment moment) -> ULID
+  def self.max: (?moment moment) -> ULID
+  def self.sample: (?period: period) -> self
+                 | (Integer number, ?period: period) -> Array[self]
   def self.valid?: (untyped string) -> bool
-  def self.scan:  (String string) -> Enumerator[ULID, singleton(ULID)]
-                | (String string) { (ULID ulid) -> void } -> singleton(ULID)
-  def self.from_monotonic_generator: (MonotonicGenerator generator) -> ULID
+  def self.scan:  (String string) -> Enumerator[self, singleton(ULID)]
+                | (String string) { (self ulid) -> void } -> singleton(ULID)
+  def self.from_milliseconds_and_entropy: (milliseconds: Integer, entropy: Integer) -> self
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
-  def initialize: (milliseconds: Integer, entropy: Integer, ?integer: Integer) -> void
+  def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
   def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
@@ -111,6 +111,9 @@ class ULID
   alias succ next
   def pred: -> ULID?
   def freeze: -> self
+  def dup: -> self
+  # Same as https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79
+  def clone: (?freeze: bool) -> self
 
   private
   def self.milliseconds_from_time: (Time time) -> Integer

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.19
+  version: 0.1.0
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-08 00:00:00.000000000 Z
+date: 2021-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rbs