ruby-ulid 0.0.16 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a83604732cdc37f8015ee9382884e950852f8c9c82aba107ea4b3c065c5a4d
-  data.tar.gz: 06e7b69a5838786f4d23da19f5e1f00fb3173014e7438459165b66703637851a
+  metadata.gz: 29a9e3cd7ec91b93c24691976fef74ea5ab0cbc8f4fa237f449fa9322e42c6d2
+  data.tar.gz: 9a3c0e12e7d2fe8b6057662ebf6a392c749f7254ee41c4e77221a2e9f45ff6ac
 SHA512:
-  metadata.gz: 6ca46525e80b1d832a703b8cb867466327de333853ee236654f722dc6abc30f46fd149ca9633c42ececcea08db2a01a6d82ab60f8eeb61ebb947f0441436dd96
-  data.tar.gz: ccd08e78dfb047f82af02eeaf14ccd12fcb05fe882edeb2bf48c2e7ec5b9fd698feccf0b9f9e187aaff97c2e793f671a3f9d32c11e3741656c3df94f944bc808
+  metadata.gz: 53a12c330c32f76f13e651cef96ce29a6a442cf3dc7742faf2409a0ee17c7dfdcee1031c17696cd51d7bd3cf5b22b2df34b8be5a203cd1d4fd5df079eb357b82
+  data.tar.gz: f6c8f8850272353bbd32cc15d437d0b021c13d9bc93c5c988255d6c50fe21ff41aef5b719261ca95b00c129024fe325e2d3c8683c70f9b55e89a09a261fff31f

data/README.md

@@ -207,12 +207,12 @@ EOD
 
 ULID.scan(json).to_a
 #=>
-[ULID(2021-04-30 05:51:57.119 UTC: 01F4GNAV5ZR6FJQ5SFQC7WDSY3),
- ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
- ULID(2021-04-30 05:52:56.707 UTC: 01F4GNCNC3CH0BCRZBPPDEKBKS),
- ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
- ULID(2021-04-30 05:53:04.852 UTC: 01F4GNCXAMXQ1SGBH5XCR6ZH0M),
- ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
+# [ULID(2021-04-30 05:51:57.119 UTC: 01F4GNAV5ZR6FJQ5SFQC7WDSY3),
+#  ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+#  ULID(2021-04-30 05:52:56.707 UTC: 01F4GNCNC3CH0BCRZBPPDEKBKS),
+#  ULID(2021-04-30 05:52:32.641 UTC: 01F4GNBXW1AM2KWW52PVT3ZY9X),
+#  ULID(2021-04-30 05:53:04.852 UTC: 01F4GNCXAMXQ1SGBH5XCR6ZH0M),
+#  ULID(2021-04-30 05:53:12.478 UTC: 01F4GND4RYYSKNAADHQ9BNXAWJ)]
 ```
 
 ### Some methods to help manipulations
@@ -247,6 +247,22 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+`ULID.sample` returns random ULIDs ignoring the generating time
+
+```ruby
+ULID.sample #=> ULID(2545-07-26 06:51:20.085 UTC: 0GGKQ45GMNMZR6N8A8GFG0ZXST)
+ULID.sample #=> ULID(5098-07-26 21:31:06.946 UTC: 2SSBNGGYA272J7BMDCG4Z6EEM5)
+ULID.sample(0) #=> []
+ULID.sample(1) #=> [ULID(2241-04-16 03:31:18.440 UTC: 07S52YWZ98AZ8T565MD9VRYMQH)]
+ULID.sample(5)
+#=>
+#[ULID(5701-04-29 12:41:19.647 UTC: 3B2YH2DV0ZYDDATGTYSKMM1CMT),
+# ULID(2816-08-01 01:21:46.612 UTC: 0R9GT6RZKMK3RG02Q2HAFVKEY2),
+# ULID(10408-10-05 17:06:27.848 UTC: 7J6CPTEEC86Y24EQ4F1Y93YYN0),
+# ULID(2741-09-02 16:24:18.803 UTC: 0P4Q4V34KKAJW46QW47WQB5463),
+# ULID(2665-03-16 14:50:22.724 UTC: 0KYFW9DWM4CEGFNTAC6YFAVVJ6)]
+```
+
 ### UUIDv4 converter for migration use-cases
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.

data/lib/ulid.rb

@@ -3,7 +3,6 @@
 # Copyright (C) 2021 Kenichi Kamiya
 
 require 'securerandom'
-require 'integer/base'
 
 # @see https://github.com/ulid/spec
 # @!attribute [r] milliseconds
@@ -42,6 +41,9 @@ class ULID
   # @see https://bugs.ruby-lang.org/issues/15958
   TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
 
+  UNDEFINED = BasicObject.new
+  Kernel.instance_method(:freeze).bind(UNDEFINED).call
+
   # @param [Integer, Time] moment
   # @param [Integer] entropy
   # @return [ULID]
@@ -61,18 +63,29 @@ class ULID
     MAX_MILLISECONDS.equal?(moment) ? MAX : generate(moment: moment, entropy: MAX_ENTROPY)
   end
 
-  # @deprecated This method actually changes class state. Use {ULID::MonotonicGenerator} instead.
-  # @raise [OverflowError] if the entropy part is larger than the ULID limit in same milliseconds
-  # @return [ULID]
-  def self.monotonic_generate
-    warning = "`ULID.monotonic_generate` actually changes class state. Use `ULID::MonotonicGenerator` instead."
-    if RUBY_VERSION >= '3.0'
-      Warning.warn(warning, category: :deprecated)
+  # @param [Integer] number
+  # @return [ULID, Array<ULID>]
+  # @raise [ArgumentError] if the given number is lager than ULID spec limits or given negative number 
+  # @note Major difference of `Array#sample` interface is below
+  #   * Do not ensure the uniqueness
+  #   * Do not take random generator for the arguments
+  #   * Raising error instead of truncating elements for the given number
+  def self.sample(number=UNDEFINED)
+    if UNDEFINED.equal?(number)
+      from_integer(SecureRandom.random_number(MAX_INTEGER))
     else
-      Warning.warn(warning)
-    end
+      begin
+        int = number.to_int
+      rescue
+         # Can not use `number.to_s` and `number.inspect` for considering BasicObject here
+        raise TypeError, 'accepts no argument or integer only'
+      end
 
-    MONOTONIC_GENERATOR.generate
+      if int > MAX_INTEGER || int.negative?
+        raise ArgumentError, "given number is larger than ULID limit #{MAX_INTEGER} or negative: #{number.inspect}"
+      end
+      int.times.map { from_integer(SecureRandom.random_number(MAX_INTEGER)) }
+    end
   end
 
   # @param [String, #to_str] string
@@ -133,7 +146,7 @@ class ULID
     when Time
       begin_ulid = min(moment: begin_time)
     when nil
-      begin_ulid = min
+      begin_ulid = MIN
     else
       raise argument_error_for_range_building(time_range)
     end
@@ -147,7 +160,7 @@ class ULID
       end
     when nil
       # The end should be max and include end, because nil end means to cover endless ULIDs until the limit
-      end_ulid = max
+      end_ulid = MAX
       exclude_end = false
     else
       raise argument_error_for_range_building(time_range)
@@ -169,51 +182,32 @@ class ULID
     end
   end
 
+  # @api private
   # @return [Integer]
   def self.current_milliseconds
     milliseconds_from_time(Time.now)
   end
 
+  # @api private
   # @param [Time] time
   # @return [Integer]
   def self.milliseconds_from_time(time)
     (time.to_r * 1000).to_i
   end
 
+  # @api private
   # @param [Time, Integer] moment
   # @return [Integer]
   def self.milliseconds_from_moment(moment)
     moment.kind_of?(Time) ? milliseconds_from_time(moment) : moment.to_int
   end
 
+  # @api private
   # @return [Integer]
   def self.reasonable_entropy
     SecureRandom.random_number(MAX_ENTROPY)
   end
 
-  # @api private
-  # @deprecated Just exists to compare performance with old implementation. ref: https://github.com/kachick/ruby-ulid/issues/7
-  # @param [String, #to_str] string
-  # @return [ULID]
-  # @raise [ParserError] if the given format is not correct for ULID specs
-  # @raise [OverflowError] if the given value is larger than the ULID limit
-  def self.parse_with_integer_base(string)
-    begin
-      string = string.to_str
-      unless string.size == ENCODED_ID_LENGTH
-        raise "parsable string must be #{ENCODED_ID_LENGTH} characters, but actually given #{string.size} characters"
-      end
-      timestamp = string.slice(0, TIMESTAMP_PART_LENGTH)
-      randomness = string.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
-      milliseconds = Integer::Base.parse(timestamp, ENCODING_CHARS)
-      entropy = Integer::Base.parse(randomness, ENCODING_CHARS)
-    rescue => err
-      raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
-    end
-  
-    new milliseconds: milliseconds, entropy: entropy
-  end
-
   n32_chars = [*'0'..'9', *'A'..'V'].map(&:freeze).freeze
   raise SetupError, 'obvious bug exists in the mapping algorithm' unless n32_chars.size == 32
 
@@ -245,15 +239,21 @@ class ULID
     'Z' => 31
   }.freeze
 
-  REPLACING_MAP = 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
     end
   end.freeze
-  raise SetupError, 'obvious bug exists in the mapping algorithm' unless REPLACING_MAP.keys == crockford_base32_mappings.keys
-  REPLACING_PATTERN = /[#{REPLACING_MAP.keys.join}]/.freeze
+  raise SetupError, 'obvious bug exists in the mapping algorithm' unless N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys == crockford_base32_mappings.keys
+  CROCKFORD_BASE32_CHAR_PATTERN = /[#{N32_CHAR_BY_CROCKFORD_BASE32_CHAR.keys.join}]/.freeze
+
+  CROCKFORD_BASE32_CHAR_BY_N32_CHAR = N32_CHAR_BY_CROCKFORD_BASE32_CHAR.invert.freeze
+  N32_CHAR_PATTERN = /[#{CROCKFORD_BASE32_CHAR_BY_N32_CHAR.keys.join}]/.freeze
 
+  # @param [String, #to_str] string
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for ULID specs
   def self.parse(string)
     begin
       string = string.to_str
@@ -272,7 +272,7 @@ class ULID
 
   # @api private
   private_class_method def self.convert_crockford_base32_to_n32(string)
-    string.gsub(REPLACING_PATTERN, REPLACING_MAP)
+    string.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
   end
 
   # @return [Boolean]
@@ -335,7 +335,7 @@ class ULID
 
   # @return [String]
   def to_s
-    @string ||= Integer::Base.string_for(to_i, ENCODING_CHARS).rjust(ENCODED_ID_LENGTH, '0').upcase.freeze
+    @string ||= convert_n32_to_crockford_base32(to_i.to_s(32).rjust(ENCODED_ID_LENGTH, '0').upcase).freeze
   end
 
   # @return [Integer]
@@ -459,6 +459,11 @@ 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
@@ -482,7 +487,6 @@ require_relative 'ulid/monotonic_generator'
 class ULID
   MIN = parse('00000000000000000000000000').freeze
   MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
-  MONOTONIC_GENERATOR = MonotonicGenerator.new
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX, :REPLACING_PATTERN, :REPLACING_MAP
+  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
 end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -15,11 +15,13 @@ class ULID
   PATTERN: Regexp
   STRICT_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
-  REPLACING_MAP: Hash[String, String]
-  REPLACING_PATTERN: Regexp
-  MONOTONIC_GENERATOR: MonotonicGenerator
+  N32_CHAR_BY_CROCKFORD_BASE32_CHAR: Hash[String, String]
+  CROCKFORD_BASE32_CHAR_PATTERN: Regexp
+  CROCKFORD_BASE32_CHAR_BY_N32_CHAR: Hash[String, String]
+  N32_CHAR_PATTERN: Regexp
   MIN: ULID
   MAX: ULID
+  UNDEFINED: BasicObject
   include Comparable
 
   # The `moment` is a `Time` or `Intger of the milliseconds`
@@ -68,7 +70,6 @@ class ULID
   @matchdata: MatchData?
 
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
-  def self.monotonic_generate: -> ULID
   def self.current_milliseconds: -> Integer
   def self.milliseconds_from_time: (Time time) -> Integer
   def self.milliseconds_from_moment: (moment moment) -> Integer
@@ -80,12 +81,13 @@ class ULID
   def self.from_integer: (Integer integer) -> ULID
   def self.min: (?moment: moment) -> ULID
   def self.max: (?moment: moment) -> ULID
+  def self.sample: -> ULID
+                 | (Integer number) -> Array[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
-  def self.convert_crockford_base32_to_n32: (String) -> String
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
@@ -113,7 +115,9 @@ 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,35 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.16
+  version: 0.0.17
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-05 00:00:00.000000000 Z
+date: 2021-05-06 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: integer-base
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.2
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.1.2
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rbs
   requirement: !ruby/object:Gem::Requirement