ruby-ulid 0.0.15 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a620e80f82e91c778329ccf7da8cca96bda4b12e047610b9543768c5ec85d22
-  data.tar.gz: ea28469d63348758f52e1460b5330ce177ad2281e63060800a0669054758f3ee
+  metadata.gz: f0aff39d0f8044f373d8dcdea149f26501e0118dfc0876f060b1b757a4d2a49e
+  data.tar.gz: 02df0ea7a5fe5f8dabd1179988cfe4c2574debf3ad7200d11445eef932dd7443
 SHA512:
-  metadata.gz: acb07ae797c3a06a6626d34e15dc1056a30586e8bc151a3773770259d2f4047d0708593e702fbd67a7609758165f20a15f208fede068717a5555733535ed4bde
-  data.tar.gz: 57c9819d86f2a0f002cf3b9a7b76b3a36bc412fa874d50136ec296f1217fb905fa19feb52de2c9d5250547da384580cf882121f0e331054cd665bd113d1f10e3
+  metadata.gz: ab036ed40e4f2740de9d37e44d2c6d4d233fa0071f95383accb2334c4d1f85b30b24eea902e0e29c34fefc8749b8caf5d1f9df6c52f93fe2e76c89aa0912d11e
+  data.tar.gz: d8ac11f63e5b301ed8b1eacd0d1211fd4b3a0bd79ccae8fe87050833cf305a7345da1dc136b95ecccfcafc6110cf9a281afb0f15db1fe2e01984bf320f82b7e5

data/README.md

@@ -1,6 +1,6 @@
 # ruby-ulid
 
-A handy `ULID` library
+## Overview
 
 The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec). It has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
 This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
@@ -33,16 +33,26 @@ Instead, herein is proposed ULID:
 - No special characters (URL safe)
 - Monotonic sort order (correctly detects and handles the same millisecond)
 
-## Install
+## Usage
+
+### Install
 
 Require Ruby 2.6 or later
 
+This command will install the latest version into your environment
+
 ```console
 $ gem install ruby-ulid
-#=> Installed
+Should be installed!
 ```
 
-## Usage
+Add this line to your application/library's `Gemfile` is needed in basic use-case
+
+```ruby
+gem 'ruby-ulid', '>= 0.1.0', '< 0.2.0'
+```
+
+### Generator and Parser
 
 The generated `ULID` is an object not just a string.
 It means easily get the timestamps and binary formats.
@@ -52,9 +62,12 @@ require 'ulid'
 
 ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
 ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
+ulid.milliseconds #=> 1619544442826
 ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
+ulid.timestamp #=> "01F4A5Y1YA"
+ulid.randomness #=> "QCYAYCTC7GRMJ9AA"
+ulid.to_i #=> 1957909092946624190749577070267409738
 ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
-ulid.pattern #=> /(?<timestamp>01F4A5Y1YA)(?<randomness>QCYAYCTC7GRMJ9AA)/i
 ```
 
 You can get the objects from exists encoded ULIDs
@@ -64,6 +77,8 @@ ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259
 ulid.to_time #=> 2016-07-30 23:54:10.259 UTC
 ```
 
+### Sortable with the timestamp
+
 ULIDs are sortable when they are generated in different timestamp with milliseconds precision
 
 ```ruby
@@ -71,19 +86,20 @@ ulids = 1000.times.map do
   sleep(0.001)
   ULID.generate
 end
-ulids.sort == ulids #=> true
 ulids.uniq(&:to_time).size #=> 1000
+ulids.sort == ulids #=> true
 ```
 
-`ULID.generate` can take fixed `Time` instance
+`ULID.generate` can take fixed `Time` instance. The shorthand is `ULID.at`
 
 ```ruby
-time = Time.at(946684800, in: 'UTC') #=> 2000-01-01 00:00:00 UTC
+time = Time.at(946684800).utc #=> 2000-01-01 00:00:00 UTC
 ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB00N018DCPJA4H9379P)
 ULID.generate(moment: time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB006WQT3JTMN0T14EBP)
+ULID.at(time) #=> ULID(2000-01-01 00:00:00.000 UTC: 00VHNCZB002W5BGWWKN76N22H6)
 
 ulids = 1000.times.map do |n|
-  ULID.generate(moment: time + n)
+  ULID.at(time + n)
 end
 ulids.sort == ulids #=> true
 ```
@@ -98,7 +114,9 @@ ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in en
 ulids.sort == ulids #=> false
 ```
 
-If you want to ensure `sortable`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
+### How to keep `Sortable` even if in same timestamp
+
+If you want to prefer `sortable`, Use `MonotonicGenerator` instead. It is called as [Monotonicity](https://github.com/ulid/spec/tree/d0c7170df4517939e70129b4d6462cc162f2d5bf#monotonicity) on the spec.
 (Though it starts with new random value when changed the timestamp)
 
 ```ruby
@@ -128,20 +146,47 @@ sample_ulids_by_the_time.take(5) #=>
 ulids.sort == ulids #=> true
 ```
 
-When filtering ULIDs by `Time`, we should consider to handle the precision.
-So this gem provides `ULID.range` to generate `Range[ULID]` from given `Range[Time]`
+### 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
+
+```ruby
+include_end = ulid1..ulid2
+exclude_end = ulid1...ulid2
+
+ulids.grep(one_of_the_above)
+ulids.grep_v(one_of_the_above)
+```
+
+When want to filter ULIDs with `Time`, we should consider to handle the precision.
+So this gem provides `ULID.range` to generate reasonable `Range[ULID]` from `Range[Time]`
 
 ```ruby
 # Both of below, The begin of `Range[ULID]` will be the minimum in the floored milliseconds of the time1
 include_end = ULID.range(time1..time2) #=> The end of `Range[ULID]` will be the maximum in the floored milliseconds of the time2
 exclude_end = ULID.range(time1...time2) #=> The end of `Range[ULID]` will be the minimum in the floored milliseconds of the time2
 
+# 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(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
+
 # So you can use the generated range objects as below
-ulids.grep(include_end)
-ulids.grep(exclude_end)
+ulids.grep(one_of_the_above)
+ulids.grep_v(one_of_the_above)
 #=> I hope the results should be actually you want!
 ```
 
+If you want to manually handle the Time objects, `ULID.floor` returns new `Time` with truncating excess precisions in ULID spec.
+
+```ruby
+time = Time.at(946684800, Rational('123456.789')).utc #=> 2000-01-01 00:00:00.123456789 UTC
+ULID.floor(time) #=> 2000-01-01 00:00:00.123 UTC
+```
+
+### Scanner for string (e.g. `JSON`)
+
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
@@ -174,26 +219,45 @@ 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)]
+```
+
+`ULID#patterns` is a util for text based operations.
+The results and spec are not fixed. Should not be used except snippets/console operation
+
+```ruby
+ULID.parse('01F4GNBXW1AM2KWW52PVT3ZY9X').patterns
+#=> returns like a fallowing Hash
+{
+  named_captures: /(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)/i,
+  strict_named_captures: /\A(?<timestamp>01F4GNBXW1)(?<randomness>AM2KWW52PVT3ZY9X)\z/i
+}
 ```
 
+### Some methods to help manipulations
+
 `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
+`ULID#next` and `ULID#succ` returns next(successor) ULID.
+Especially `ULID#succ` makes it possible `Range[ULID]#each`.
+
+NOTE: But basically `Range[ULID]#each` should not be used, incrementing 128 bits IDs are not reasonable operation in most case
 
 ```ruby
 ULID.parse('01BX5ZZKBKZZZZZZZZZZZZZZZY').next.to_s #=> "01BX5ZZKBKZZZZZZZZZZZZZZZZ"
@@ -209,12 +273,66 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+`ULID.sample` returns random ULIDs.
+
+Basically ignores 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)]
+```
+
+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.
-The imported timestamp is meaningless. So ULID's benefit will lost
+The imported timestamp is meaningless. So ULID's benefit will lost.
 
 ```ruby
+# Currently experimental feature, so needed to load the extension.
+require 'ulid/uuid'
+
 # 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"
@@ -239,6 +357,50 @@ ULID.min == reversed_min #=> false
 ULID.max == reversed_max #=> false
 ```
 
+## How to migrate from other gems
+
+As far as I know, major prior arts are below
+
+### [ulid gem](https://rubygems.org/gems/ulid) - [rafaelsales/ulid](https://github.com/rafaelsales/ulid)
+
+It is just providing basic `String` generator only.
+So you can replace the code as below
+
+```diff
+-ULID.generate
++ULID.generate.to_s
+```
+
+NOTE: It had crucial issue for handling precision, in version before `1.3.0`, when you extract timestamps from old generated ULIDs, it might be not accurate value.
+
+1. [Sort order does not respect millisecond ordering](https://github.com/rafaelsales/ulid/issues/22)
+1. [Fixed in this PR](https://github.com/rafaelsales/ulid/pull/23)
+1. [Released in 1.3.0](https://github.com/rafaelsales/ulid/compare/1.2.0...v1.3.0)
+
+### [ulid-ruby gem](https://rubygems.org/gems/ulid-ruby) - [abachman/ulid-ruby](https://github.com/abachman/ulid-ruby)
+
+It is providing basic generator(except monotonic generator) and parser.
+Major methods can be replaced as below.
+
+```diff
+-ULID.generate
++ULID.generate.to_s
+-ULID.at(time)
++ULID.at(time).to_s
+-ULID.time(string)
++ULID.parse(string).to_time
+-ULID.min_ulid_at(time)
++ULID.min(time).to_s
+-ULID.max_ulid_at(time)
++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.
+
+1. [Parsed time object has more than milliseconds](https://github.com/abachman/ulid-ruby/issues/3)
+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)
+
 ## References
 
 - [Repository](https://github.com/kachick/ruby-ulid)

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
@@ -17,61 +16,113 @@ 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 = 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_PART_LENGTH = 10
-  RANDOMNESS_PART_LENGTH = 16
-  ENCODED_ID_LENGTH = TIMESTAMP_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  TIMESTAMP_ENCODED_LENGTH = 10
+  RANDOMNESS_ENCODED_LENGTH = 16
+  ENCODED_LENGTH = TIMESTAMP_ENCODED_LENGTH + RANDOMNESS_ENCODED_LENGTH
   TIMESTAMP_OCTETS_LENGTH = 6
   RANDOMNESS_OCTETS_LENGTH = 10
   OCTETS_LENGTH = TIMESTAMP_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
   MAX_MILLISECONDS = 281474976710655
   MAX_ENTROPY = 1208925819614629174706175
   MAX_INTEGER = 340282366920938463463374607431768211455
-  PATTERN = /(?<timestamp>[0-7][#{encoding_string}]{#{TIMESTAMP_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.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'
 
+  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
 
-  # @param [Integer, Time] moment
+  # Short hand of `ULID.generate(moment: time)`
+  # @param [Time] time
   # @return [ULID]
-  def self.min(moment: 0)
+  def self.at(time)
+    raise ArgumentError, 'ULID.at takes only `Time` instance' unless Time === time
+    from_milliseconds_and_entropy(milliseconds: milliseconds_from_time(time), entropy: reasonable_entropy)
+  end
+
+  # @param [Time, Integer] moment
+  # @return [ULID]
+  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
 
-  # @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)
+  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(*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
-      Warning.warn(warning)
+      RANDOM_INTEGER_GENERATOR
     end
 
-    MONOTONIC_GENERATOR.generate
+    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 period && (number > possibilities)
+        raise ArgumentError, "given number `#{number}` is larger than given possibilities `#{possibilities}`"
+      end
+
+      Array.new(number) { from_integer(int_generator.call) }
+    else
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)"
+    end
   end
 
   # @param [String, #to_str] string
@@ -79,77 +130,68 @@ 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 [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
+  # @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
-  # @todo Need optimized for performance
   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?
 
-    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)
+    n32encoded = integer.to_s(32).rjust(ENCODED_LENGTH, '0')
+    n32encoded_timestamp = n32encoded.slice(0, TIMESTAMP_ENCODED_LENGTH)
+    n32encoded_randomness = n32encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH)
+
+    milliseconds = n32encoded_timestamp.to_i(32)
+    entropy = n32encoded_randomness.to_i(32)
 
-    new milliseconds: milliseconds, entropy: entropy
+    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
+      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
+      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
@@ -161,6 +203,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
@@ -168,23 +212,34 @@ 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)
+  private_class_method 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
+    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
     SecureRandom.random_number(MAX_ENTROPY)
@@ -193,61 +248,41 @@ class ULID
   # @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(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}"
+    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
-  
-    new milliseconds: milliseconds, entropy: entropy
+
+    from_integer(CrockfordBase32.decode(string))
   end
 
+  # @param [String, #to_str] string
   # @return [Boolean]
   def self.valid?(string)
-    parse(string)
-  rescue Exception
-    false
-  else
-    true
+    string = String.try_convert(string)
+    string ? STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET.match?(string) : false
   end
 
   # @api private
-  # @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
+  # @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?
 
-  # @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
-    end
-    num
-  end
+    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)
 
-  # @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}"
+    new milliseconds: milliseconds, entropy: entropy, integer: integer
   end
 
   attr_reader :milliseconds, :entropy
@@ -255,34 +290,29 @@ class ULID
   # @api private
   # @param [Integer] milliseconds
   # @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:)
-    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?
-
+  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 ||= Integer::Base.string_for(to_i, ENCODING_CHARS).rjust(ENCODED_ID_LENGTH, '0').upcase.freeze
+    @string ||= CrockfordBase32.encode(@integer).freeze
   end
 
   # @return [Integer]
   def to_i
-    @integer ||= self.class.inverse_of_digits(octets)
+    @integer
   end
   alias_method :hash, :to_i
 
   # @return [Integer, nil]
   def <=>(other)
-    other.kind_of?(ULID) ? (to_i <=> other.to_i) : nil
+    (ULID === other) ? (@integer <=> other.to_i) : nil
   end
 
   # @return [String]
@@ -292,7 +322,7 @@ class ULID
 
   # @return [Boolean]
   def eql?(other)
-    other.equal?(self) || (other.kind_of?(ULID) && other.to_i == to_i)
+    equal?(other) || (ULID === other && @integer == other.to_i)
   end
   alias_method :==, :eql?
 
@@ -300,13 +330,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
@@ -325,62 +351,69 @@ class ULID
 
   # @return [Array(Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer)]
   def octets
-    @octets ||= (timestamp_octets + randomness_octets).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 ||= self.class.octets_from_integer(@milliseconds, length: 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 ||= self.class.octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+    octets.slice(TIMESTAMP_OCTETS_LENGTH, RANDOMNESS_OCTETS_LENGTH)
   end
 
   # @return [String]
   def timestamp
-    @timestamp ||= matchdata[:timestamp].freeze
+    @timestamp ||= to_s.slice(0, TIMESTAMP_ENCODED_LENGTH).freeze
   end
 
   # @return [String]
   def randomness
-    @randomness ||= matchdata[:randomness].freeze
+    @randomness ||= to_s.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH).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
+  # @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
+    }
   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)
-  end
-
-  # @return [String]
-  def to_uuidv4
-    @uuidv4 ||= begin
-      # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
-      array = octets.pack('C*').unpack('NnnnnN')
-      array[2] = (array[2] & 0x0fff) | 0x4000
-      array[3] = (array[3] & 0x3fff) | 0x8000
-      ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
+    pred_int = @integer.pred
+    if pred_int <= 0
+      if pred_int == 0
+        MIN
+      else
+        nil
+      end
+    else
+      ULID.from_integer(pred_int)
     end
   end
 
@@ -391,32 +424,35 @@ class ULID
     super
   end
 
-  private
+  # @return [self]
+  def dup
+    self
+  end
 
-  # @return [MatchData]
-  def matchdata
-    @matchdata ||= STRICT_PATTERN.match(to_s).freeze
+  # @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
-    strict_pattern
-    to_uuidv4
+    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
-  MONOTONIC_GENERATOR = MonotonicGenerator.new
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN, :MIN, :MAX
+  private_constant :TIME_FORMAT_IN_INSPECT, :MIN, :MAX, :RANDOM_INTEGER_GENERATOR
 end

data/lib/ulid/crockford_base32.rb

@@ -0,0 +1,68 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  # Currently supporting only for `subset` for actual use-case`
+  # Original decoding spec allows other characters.
+  # But I think ULID should allow `subset` of Crockford's Base32.
+  # 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
+  module CrockfordBase32
+    class SetupError < ScriptError; 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
+
+    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 = CROCKFORD_BASE32_ENCODING_STRING.chars.map(&:freeze).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] string
+    # @return [Integer]
+    def self.decode(string)
+      n32encoded = string.upcase.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+      n32encoded.to_i(32)
+    end
+
+    # @param [Integer] integer
+    # @return [String]
+    def self.encode(integer)
+      n32encoded = integer.to_s(32)
+      n32encoded.upcase.gsub(N32_CHAR_PATTERN, CROCKFORD_BASE32_CHAR_BY_N32_CHAR).rjust(ENCODED_LENGTH, '0')
+    end
+  end
+end

data/lib/ulid/monotonic_generator.rb

@@ -8,6 +8,7 @@ class ULID
     attr_accessor :latest_milliseconds, :latest_entropy
 
     def initialize
+      @mutex = Thread::Mutex.new
       reset
     end
 
@@ -19,14 +20,15 @@ class ULID
       milliseconds = ULID.milliseconds_from_moment(moment)
       raise ArgumentError, "milliseconds should not be negative: given: #{milliseconds}" if milliseconds.negative?
 
-      if @latest_milliseconds < milliseconds
-        @latest_milliseconds = milliseconds
-        @latest_entropy = ULID.reasonable_entropy
-      else
-        @latest_entropy += 1
+      @mutex.synchronize do
+        if @latest_milliseconds < milliseconds
+          @latest_milliseconds = milliseconds
+          @latest_entropy = ULID.reasonable_entropy
+        else
+          @latest_entropy += 1
+        end
+        ULID.from_milliseconds_and_entropy(milliseconds: @latest_milliseconds, entropy: @latest_entropy)
       end
-
-      ULID.new milliseconds: @latest_milliseconds, entropy: @latest_entropy
     end
 
     # @api private

data/lib/ulid/uuid.rb

@@ -0,0 +1,38 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+# Extracted features around UUID from some reasons
+# ref:
+#  * https://github.com/kachick/ruby-ulid/issues/105
+#  * https://github.com/kachick/ruby-ulid/issues/76
+class ULID
+  # 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.freeze
+  private_constant :UUIDV4_PATTERN
+
+  # @param [String, #to_str] uuid
+  # @return [ULID]
+  # @raise [ParserError] if the given format is not correct for UUIDv4 specs
+  def self.from_uuidv4(uuid)
+    uuid = String.try_convert(uuid)
+    raise ArgumentError, 'ULID.from_uuidv4 takes only strings' unless uuid
+
+    prefix_trimmed = uuid.sub(/\Aurn:uuid:/, '')
+    unless UUIDV4_PATTERN.match?(prefix_trimmed)
+      raise ParserError, "given `#{uuid}` does not match to `#{UUIDV4_PATTERN.inspect}`"
+    end
+
+    normalized = prefix_trimmed.gsub(/[^0-9A-Fa-f]/, '')
+    from_integer(normalized.to_i(16))
+  end
+
+  # @return [String]
+  def to_uuidv4
+    # This code referenced https://github.com/ruby/ruby/blob/121fa24a3451b45c41ac0a661b64e9fc8600e589/lib/securerandom.rb#L221-L241
+    array = octets.pack('C*').unpack('NnnnnN')
+    array[2] = (array[2] & 0x0fff) | 0x4000
+    array[3] = (array[3] & 0x3fff) | 0x8000
+    ('%08x-%04x-%04x-%04x-%04x%08x' % array).freeze
+  end
+end

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -1,10 +1,10 @@
 # Classes
 class ULID
   VERSION: String
-  ENCODING_CHARS: Array[String]
-  TIMESTAMP_PART_LENGTH: 10
-  RANDOMNESS_PART_LENGTH: 16
-  ENCODED_ID_LENGTH: 26
+  CROCKFORD_BASE32_ENCODING_STRING: String
+  TIMESTAMP_ENCODED_LENGTH: 10
+  RANDOMNESS_ENCODED_LENGTH: 16
+  ENCODED_LENGTH: 26
   TIMESTAMP_OCTETS_LENGTH: 6
   RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
@@ -12,10 +12,11 @@ class ULID
   MAX_ENTROPY: 1208925819614629174706175
   MAX_INTEGER: 340282366920938463463374607431768211455
   TIME_FORMAT_IN_INSPECT: '%Y-%m-%d %H:%M:%S.%3N %Z'
-  PATTERN: Regexp
-  STRICT_PATTERN: Regexp
+  RANDOM_INTEGER_GENERATOR: ^() -> Integer
+  PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
+  SCANNING_PATTERN: Regexp
   UUIDV4_PATTERN: Regexp
-  MONOTONIC_GENERATOR: MonotonicGenerator
   MIN: ULID
   MAX: ULID
   include Comparable
@@ -32,6 +33,19 @@ class ULID
   class ParserError < Error
   end
 
+  module CrockfordBase32
+    class SetupError < ScriptError
+    end
+
+    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
+
+    def self.encode: (Integer integer) -> String
+    def self.decode: (String string) -> Integer
+  end
+
   class MonotonicGenerator
     attr_accessor latest_milliseconds: Integer
     attr_accessor latest_entropy: Integer
@@ -44,50 +58,43 @@ class ULID
   type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, 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]
+  type period = Range[Time] | Range[nil] | Range[ULID]
 
   @milliseconds: Integer
   @entropy: Integer
   @string: String?
-  @integer: Integer?
-  @octets: octets?
-  @timestamp_octets: timestamp_octets?
-  @randomness_octets: randomness_octets?
+  @integer: Integer
   @timestamp: String?
   @randomness: String?
   @inspect: String?
   @time: Time?
-  @next: ULID?
-  @pattern: Regexp?
-  @strict_pattern: Regexp?
-  @uuidv4: String?
-  @matchdata: MatchData?
 
-  def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
-  def self.monotonic_generate: -> ULID
+  def self.generate: (?moment: moment, ?entropy: Integer) -> self
+  def self.at: (Time time) -> self
   def self.current_milliseconds: -> Integer
-  def self.milliseconds_from_time: (Time time) -> Integer
   def self.milliseconds_from_moment: (moment moment) -> Integer
-  def self.range: (Range[Time] | Range[nil] time_range) -> Range[ULID]
+  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.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.octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
-  def self.inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
+  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) -> void
+  def initialize: (milliseconds: Integer, entropy: Integer, integer: Integer) -> void
   def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
   def <=>: (ULID other) -> Integer
-         | (untyped other) -> Integer?
+         | (untyped other) -> nil
   def inspect: -> String
   def eql?: (untyped other) -> bool
   alias == eql?
@@ -95,8 +102,7 @@ class ULID
   def to_time: -> Time
   def timestamp: -> String
   def randomness: -> String
-  def pattern: -> Regexp
-  def strict_pattern: -> Regexp
+  def patterns: -> Hash[Symbol, Regexp | String]
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
@@ -105,9 +111,11 @@ 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.argument_error_for_range_building: (untyped argument) -> ArgumentError
-  def matchdata: -> MatchData
+  def self.milliseconds_from_time: (Time time) -> Integer
   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.15
+  version: 0.1.0
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-04 00:00:00.000000000 Z
+date: 2021-05-09 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
@@ -84,10 +64,10 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
-description: "    ULID(Universally Unique Lexicographically Sortable Identifier) has
-  useful specs for applications (e.g. `Database key`). \n    This gem aims to provide
-  the generator, monotonic generator, parser and handy manipulation features around
-  the ULID.\n    Also providing `rbs` signature files.\n"
+description: |2
+      The ULID(Universally Unique Lexicographically Sortable Identifier) has useful specs for applications (e.g. `Database key`), especially possess all `uniqueness`, `randomness`, `extractable timestamps` and `sortable` features.
+      This gem aims to provide the generator, monotonic generator, parser and handy manipulation features around the ULID.
+      Also providing `ruby/rbs` signature files.
 email:
 - kachick1+ruby@gmail.com
 executables: []
@@ -97,7 +77,9 @@ files:
 - LICENSE
 - README.md
 - lib/ulid.rb
+- lib/ulid/crockford_base32.rb
 - lib/ulid/monotonic_generator.rb
+- lib/ulid/uuid.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid