ruby-ulid 0.0.18 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b1641b0894c0140c3a9c6f59fa8abcfca386362ad1aaa92fe196f3bf5f75cf1
-  data.tar.gz: 932fa04dceb504330289d4236f9670fecd702989504bdd402873d60c0bb1c0e5
+  metadata.gz: f4101c27c1bd3f61d9882bb06444cb929975461e4e8258d44869e40a564a8ede
+  data.tar.gz: 716df050e1cff54368ad826d04065eea06e7fdcca9973509bdd69c980ce2c347
 SHA512:
-  metadata.gz: f073c7b240ef96b511c84c6bc5649c483fc97c62a3892f58531b6f36e8235e49dcd865433fe522eec48a3532c98c4deec8713f453a4b2a117157788eabddaf6b
-  data.tar.gz: a2486bbefd62d0d019c15044c9d67b6aabc33e370f4ee88239c1e2b33a40738c736fcc9221dd3ce457eabf83a3580be5dc501fef0c359345a453331bdd62d139
+  metadata.gz: c4e70f2f648e8cb165cf03014a35d8c83a879a037eecc89f4b0d91717ccc3107a19ae12372dd6788ae601abbc6498a01e0cad08247f684d1bc5b72c0a43d017c
+  data.tar.gz: 821bdac8833a3034b5842133961d8bb1c8e6c9f67c487ec25533c0ee23f3933a6bc71ef0b995cda957706f3bf6813c08a3e7e1d4f1ab8d749522db76892101ed

data/README.md

@@ -10,7 +10,7 @@ Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
 
 ![ULIDlogo](https://raw.githubusercontent.com/kachick/ruby-ulid/main/logo.png)
 
-![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test.yml/badge.svg?branch=main)
+![Build Status](https://github.com/kachick/ruby-ulid/actions/workflows/test_behaviors.yml/badge.svg?branch=main)
 [![Gem Version](https://badge.fury.io/rb/ruby-ulid.png)](http://badge.fury.io/rb/ruby-ulid)
 
 ## Universally Unique Lexicographically Sortable Identifier
@@ -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.18'
+gem 'ruby-ulid', '>= 0.1.3', '< 0.2.0'
 ```
 
 ### Generator and Parser
@@ -146,6 +146,8 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
+Same generator does not generate duplicated ULIDs even in multi threads environment. It is implemented with [Thread::Mutex](https://github.com/ruby/ruby/blob/5f8bca32571fa9c651f6903d36f66082363f8879/thread_sync.c#L1572-L1582)
+
 ### Filtering IDs with `Time`
 
 `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
@@ -168,7 +170,7 @@ exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the
 
 # Below patterns are acceptable
 pinpointing = ULID.range(time1..time1) #=> This will match only for all IDs in `time1`
-until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
+# until_the_end = ULID.range(..time1) #=> This will match only for all IDs upto `time1` (The `nil` starting `Range` can be used since Ruby 2.7)
 until_the_end = ULID.range(ULID.min.to_time..time1) #=> This is same as above for Ruby 2.6
 until_the_ulid_limit = ULID.range(time1..) # This will match only for all IDs from `time1` to max value of the ULID limit
 
@@ -243,13 +245,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.
@@ -271,7 +275,9 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
-`ULID.sample` returns random ULIDs ignoring the generating time
+`ULID.sample` returns random ULIDs.
+
+Basically ignores generating time.
 
 ```ruby
 ULID.sample #=> ULID(2545-07-26 06:51:20.085 UTC: 0GGKQ45GMNMZR6N8A8GFG0ZXST)
@@ -287,6 +293,39 @@ ULID.sample(5)
 # ULID(2665-03-16 14:50:22.724 UTC: 0KYFW9DWM4CEGFNTAC6YFAVVJ6)]
 ```
 
+You can specify a range object for the timestamp restriction, see also `ULID.range`.
+
+```ruby
+ulid1 = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
+ulid2 = ULID.parse('01F4PTVCSN9ZPFKYTY2DDJVRK4') #=> ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4)
+ulids = ULID.sample(1000, period: ulid1..ulid2)
+ulids.uniq.size #=> 1000
+ulids.take(10)
+#=>
+#[ULID(2021-05-02 06:57:19.954 UTC: 01F4NXW02JNB8H0J0TK48JD39X),
+# ULID(2021-05-02 07:06:07.458 UTC: 01F4NYC372GVP7NS0YAYQGT4VZ),
+# ULID(2021-05-01 06:16:35.791 UTC: 01F4K94P6F6P68K0H64WRDSFKW),
+# ULID(2021-04-27 22:17:37.844 UTC: 01F4APHGSMFJZQTGXKZBFFBPJP),
+# ULID(2021-04-28 20:17:55.357 UTC: 01F4D231MXQJXAR8G2JZHEJNH3),
+# ULID(2021-04-30 07:18:54.307 UTC: 01F4GTA2332AS2VPHC4FMKC7R5),
+# ULID(2021-05-02 12:26:03.480 UTC: 01F4PGNXARG554Y3HYVBDW4T9S),
+# ULID(2021-04-29 09:52:15.107 UTC: 01F4EGP483ZX2747FQPWQNPPMW),
+# ULID(2021-04-29 03:18:24.152 UTC: 01F4DT4Z4RA0QV8WFQGRAG63EH),
+# ULID(2021-05-02 13:27:16.394 UTC: 01F4PM605ABF5SDVMEHBH8JJ9R)]
+ULID.sample(10, period: ulid1.to_time..ulid2.to_time)
+#=>
+# [ULID(2021-04-29 06:44:41.513 UTC: 01F4E5YPD9XQ3MYXWK8ZJKY8SW),
+#  ULID(2021-05-01 00:35:06.629 UTC: 01F4JNKD85SVK1EAEYSJGF53A2),
+#  ULID(2021-05-02 12:45:28.408 UTC: 01F4PHSEYRG9BWBEWMRW1XE6WW),
+#  ULID(2021-05-01 03:06:09.130 UTC: 01F4JY7ZBABCBMX16XH2Q4JW4W),
+#  ULID(2021-04-29 21:38:58.109 UTC: 01F4FS45DX4049JEQK4W6TER6G),
+#  ULID(2021-04-29 17:14:14.116 UTC: 01F4F9ZDQ449BE8BBZFEHYQWG2),
+#  ULID(2021-04-30 16:18:08.205 UTC: 01F4HS5DPD1HWDVJNJ6YKJXKSK),
+#  ULID(2021-04-30 10:31:33.602 UTC: 01F4H5ATF2A1CSQF0XV5NKZ288),
+#  ULID(2021-04-28 16:49:06.484 UTC: 01F4CP4PDM214Q6H3KJP7DYJRR),
+#  ULID(2021-04-28 15:05:06.808 UTC: 01F4CG68ZRST94T056KRZ5K9S4)]
+```
+
 ### UUIDv4 converter for migration use-cases
 
 `ULID.from_uuidv4` and `ULID#to_uuidv4` is the converter.
@@ -296,7 +335,7 @@ The imported timestamp is meaningless. So ULID's benefit will lost.
 # Currently experimental feature, so needed to load the extension.
 require 'ulid/uuid'
 
-# Basically reversible 
+# 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"
 
@@ -353,9 +392,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.
@@ -364,6 +403,12 @@ NOTE: It is still having precision issue similar as `ulid gem` in the both gener
 1. [Fix to handle timestamp precision in parser](https://github.com/abachman/ulid-ruby/pull/5)
 1. [Fix to handle timestamp precision in generator](https://github.com/abachman/ulid-ruby/pull/4)
 
+### Compare performance with them
+
+See [Benchmark](https://github.com/kachick/ruby-ulid/wiki/Benchmark).
+
+The results are not something to be proud of.
+
 ## References
 
 - [Repository](https://github.com/kachick/ruby-ulid)

data/lib/ulid.rb

@@ -15,15 +15,12 @@ class ULID
   class Error < StandardError; end
   class OverflowError < Error; end
   class ParserError < Error; end
-  class SetupError < ScriptError; end
+  class UnexpectedError < Error; 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'
-  encoding_chars = encoding_string.chars.map(&:freeze).freeze
+  # Excluded I, L, O, U, -.
+  # This is the encoding patterns.
+  # The decoding issue is written in ULID::CrockfordBase32
+  CROCKFORD_BASE32_ENCODING_STRING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
 
   TIMESTAMP_ENCODED_LENGTH = 10
   RANDOMNESS_ENCODED_LENGTH = 16
@@ -34,32 +31,28 @@ class ULID
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
-  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
+
+  # @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][#{CROCKFORD_BASE32_ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}})(?<randomness>[#{CROCKFORD_BASE32_ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}})/i.freeze
+
+  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET = /\A#{PATTERN_WITH_CROCKFORD_BASE32_SUBSET.source}\z/i.freeze
+
+  # Optimized for `ULID.scan`, might be changed the definition with gathered `ULID.scan` spec changed.
+  # This can't contain `\b` for considering UTF-8 (e.g. Japanese), so intentional `false negative` definition.
+  SCANNING_PATTERN = /[0-7][#{CROCKFORD_BASE32_ENCODING_STRING}]{#{TIMESTAMP_ENCODED_LENGTH - 1}}[#{CROCKFORD_BASE32_ENCODING_STRING}]{#{RANDOMNESS_ENCODED_LENGTH}}/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]
   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)`
@@ -67,43 +60,69 @@ 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
 
-  # @param [Integer] number
-  # @return [ULID, Array<ULID>]
-  # @raise [ArgumentError] if the given number is lager than ULID spec limits or given negative number 
+  RANDOM_INTEGER_GENERATOR = -> {
+    SecureRandom.random_number(MAX_INTEGER)
+  }
+
+  # @param [Range<Time>, Range<nil>, Range[ULID], nil] period
+  # @overload sample(number, period: nil)
+  #   @param [Integer] number
+  #   @return [Array<ULID>]
+  #   @raise [ArgumentError] if the given number is lager than `ULID spec limits` or `Possibilities of given period`, or given negative number
+  # @overload sample(period: nil)
+  #   @return [ULID]
   # @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))
+  def self.sample(*args, period: nil)
+    int_generator = if period
+      ulid_range = range(period)
+      min, max, exclude_end = ulid_range.begin.to_i, ulid_range.end.to_i, ulid_range.exclude_end?
+
+      possibilities = (max - min) + (exclude_end ? 0 : 1)
+      raise ArgumentError, "given range `#{ulid_range.inspect}` does not have possibilities" unless possibilities.positive?
+
+      -> {
+        SecureRandom.random_number(possibilities) + min
+      }
     else
-      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'
+      RANDOM_INTEGER_GENERATOR
+    end
+
+    case args.size
+    when 0
+      from_integer(int_generator.call)
+    when 1
+      number = args.first
+      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"
       end
 
-      if int > MAX_INTEGER || int.negative?
-        raise ArgumentError, "given number is larger than ULID limit #{MAX_INTEGER} or negative: #{number.inspect}"
+      if period && (number > possibilities)
+        raise ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`"
       end
-      int.times.map { from_integer(SecureRandom.random_number(MAX_INTEGER)) }
+
+      Array.new(number) { from_integer(int_generator.call) }
+    else
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)"
     end
   end
 
@@ -112,20 +131,21 @@ class ULID
   # @yieldparam [ULID] ulid
   # @yieldreturn [self]
   def self.scan(string)
-    string = string.to_str
+    string = String.try_convert(string)
+    raise ArgumentError, 'ULID.scan takes only strings' unless string
     return to_enum(__callee__, string) unless block_given?
-    string.scan(PATTERN) do |pair|
-      yield parse(pair.join)
+    string.scan(SCANNING_PATTERN) do |matched|
+      yield parse(matched)
     end
     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?
 
@@ -139,35 +159,40 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy, integer: integer
   end
 
-  # @param [Range<Time>, Range<nil>] time_range
+  # @param [Range<Time>, Range<nil>, Range[ULID]] period
   # @return [Range<ULID>]
-  # @raise [ArgumentError] if the given time_range is not a `Range[Time]` or `Range[nil]`
-  def self.range(time_range)
-    raise argument_error_for_range_building(time_range) unless time_range.kind_of?(Range)
-    begin_time, end_time, exclude_end = time_range.begin, time_range.end, time_range.exclude_end?
+  # @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]`, `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_time
+    case begin_element
     when Time
-      begin_ulid = min(moment: begin_time)
+      begin_ulid = min(begin_element)
     when nil
       begin_ulid = MIN
+    when self
+      begin_ulid = begin_element
     else
-      raise argument_error_for_range_building(time_range)
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
-    case end_time
+    case end_element
     when Time
       if exclude_end
-        end_ulid = min(moment: end_time)
+        end_ulid = min(end_element)
       else
-        end_ulid = max(moment: end_time)
+        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
       end_ulid = MAX
       exclude_end = false
+    when self
+      end_ulid = end_element
     else
-      raise argument_error_for_range_building(time_range)
+      raise ArgumentError, "ULID.range takes only `Range[Time]`, `Range[nil]` or `Range[ULID]`, given: #{period.inspect}"
     end
 
     begin_ulid.freeze
@@ -179,6 +204,8 @@ class ULID
   # @param [Time] time
   # @return [Time]
   def self.floor(time)
+    raise ArgumentError, 'ULID.floor takes only `Time` instance' unless Time === time
+
     if RUBY_VERSION >= '2.7'
       time.floor(3)
     else
@@ -195,7 +222,7 @@ class ULID
   # @api private
   # @param [Time] time
   # @return [Integer]
-  def self.milliseconds_from_time(time)
+  private_class_method def self.milliseconds_from_time(time)
     (time.to_r * 1000).to_i
   end
 
@@ -203,107 +230,91 @@ class ULID
   # @param [Time, Integer] moment
   # @return [Integer]
   def self.milliseconds_from_moment(moment)
-    moment.kind_of?(Time) ? milliseconds_from_time(moment) : moment.to_int
+    case moment
+    when Integer
+      moment
+    when Time
+      milliseconds_from_time(moment)
+    else
+      raise ArgumentError, '`moment` should be a `Time` or `Integer as milliseconds`'
+    end
   end
 
-  # @api private
   # @return [Integer]
-  def self.reasonable_entropy
+  private_class_method def self.reasonable_entropy
     SecureRandom.random_number(MAX_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
-
-  n32_char_by_number = {}
-  n32_chars.each_with_index do |char, index|
-    n32_char_by_number[index] = char
-  end
-  n32_char_by_number.freeze
-
-  # Currently supporting only for `subset for actual use-case`
-  # See below
-  #   * https://github.com/ulid/spec/pull/57
-  #   * https://github.com/kachick/ruby-ulid/issues/57
-  #   * https://github.com/kachick/ruby-ulid/issues/78
-  crockford_base32_mappings = {
-    'J' => 18,
-    'K' => 19,
-    'M' => 20,
-    'N' => 21,
-    'P' => 22,
-    'Q' => 23,
-    'R' => 24,
-    'S' => 25,
-    'T' => 26,
-    'V' => 27,
-    'W' => 28,
-    'X' => 29,
-    'Y' => 30,
-    'Z' => 31
-  }.freeze
-
-  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 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
-      raise "given argument does not match to `#{STRICT_PATTERN.inspect}`" unless STRICT_PATTERN.match?(string)
-    rescue => err
-      raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
+    string = String.try_convert(string)
+    raise ArgumentError, 'ULID.parse takes only strings' unless string
+
+    unless STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string)
+      raise ParserError, "given `#{string}` does not match to `#{STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.inspect}`"
     end
 
-    n32encoded = string.upcase.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
-    from_integer(n32encoded.to_i(32))
+    from_integer(CrockfordBase32.decode(string))
   end
 
   # @return [Boolean]
-  def self.valid?(string)
-    parse(string)
-  rescue Exception
-    false
-  else
-    true
+  def self.valid?(object)
+    string = String.try_convert(object)
+    string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
-  # @api private
-  # @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
+  # @param [ULID, #to_ulid] object
+  # @return [ULID, nil]
+  # @raise [TypeError] if `object.to_ulid` did not return ULID instance
+  def self.try_convert(object)
+    begin
+      converted = object.to_ulid
+    rescue NoMethodError
+      nil
+    else
+      if ULID === converted
+        converted
+      else
+        object_class_name = safe_get_class_name(object)
+        converted_class_name = safe_get_class_name(converted)
+        raise TypeError, "can't convert #{object_class_name} to ULID (#{object_class_name}#to_ulid gives #{converted_class_name})"
+      end
     end
-    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
+  # @param [BasicObject] object
+  # @return [String]
+  private_class_method def self.safe_get_class_name(object)
+    fallback = 'UnknownObject'
+
+    begin
+      name = String.try_convert(object.class.name)
+    rescue Exception
+      fallback
+    else
+      name || fallback
+    end
   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}"
+  # @param [Integer] milliseconds
+  # @param [Integer] entropy
+  # @return [ULID]
+  # @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
@@ -313,42 +324,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: 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
-
+  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 ||= to_i.to_s(32).upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0').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]
@@ -358,7 +354,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?
 
@@ -366,13 +362,9 @@ class ULID
   def ===(other)
     case other
     when ULID
-      self == other
+      @integer == other.to_i
     when String
-      begin
-        self == self.class.parse(other)
-      rescue Exception
-        false
-      end
+      to_s == other.upcase
     else
       false
     end
@@ -391,17 +383,21 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    @octets ||= octets_from_integer(to_i).freeze
+    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
-    @timestamp_octets ||= octets.slice(0, TIMESTAMP_OCTETS_LENGTH).freeze
+    octets.slice(0, TIMESTAMP_OCTETS_LENGTH)
   end
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def randomness_octets
-    @randomness_octets ||= octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH).freeze
+    octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH)
   end
 
   # @return [String]
@@ -424,31 +420,33 @@ class ULID
     }
   end
 
-  # @deprecated Use {#patterns} instead. ref: https://github.com/kachick/ruby-ulid/issues/84
-  # @return [Regexp]
-  def pattern
-    patterns.fetch(:named_captures)
-  end
-
-  # @deprecated Use {#patterns} instead. ref: https://github.com/kachick/ruby-ulid/issues/84
-  # @return [Regexp]
-  def strict_pattern
-    patterns.fetch(:strict_named_captures)
-  end
-
   # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
-  def next
-    next_int = to_i.next
-    return nil if next_int > MAX_INTEGER
-    @next ||= self.class.from_integer(next_int)
+  def succ
+    succ_int = @integer.succ
+    if succ_int >= MAX_INTEGER
+      if succ_int == MAX_INTEGER
+        MAX
+      else
+        nil
+      end
+    else
+      ULID.from_integer(succ_int)
+    end
   end
-  alias_method :succ, :next
+  alias_method :next, :succ
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
-    pre_int = to_i.pred
-    return nil if pre_int.negative?
-    @pred ||= self.class.from_integer(pre_int)
+    pred_int = @integer.pred
+    if pred_int <= 0
+      if pred_int == 0
+        MIN
+      else
+        nil
+      end
+    else
+      ULID.from_integer(pred_int)
+    end
   end
 
   # @return [self]
@@ -458,36 +456,40 @@ class ULID
     super
   end
 
-  private
+  # @return [self]
+  def to_ulid
+    self
+  end
 
-  # @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!
+  # @return [self]
+  def dup
+    self
   end
 
+  # @return [self]
+  def clone(freeze: true)
+    self
+  end
+
+  undef_method :instance_variable_set
+
+  private
+
   # @return [void]
   def cache_all_instance_variables
     inspect
-    octets
-    to_i
-    succ
-    pred
     timestamp
     randomness
   end
 end
 
 require_relative 'ulid/version'
+require_relative 'ulid/crockford_base32'
 require_relative 'ulid/monotonic_generator'
 
 class ULID
   MIN = parse('00000000000000000000000000').freeze
   MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
 
-  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
+  private_constant :TIME_FORMAT_IN_INSPECT, :MIN, :MAX, :RANDOM_INTEGER_GENERATOR
 end