ruby-ulid 0.0.12 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0adfc974863e1b2d248eac28305322e20d6b2dc94465b7ca3462fdd2c8676352
-  data.tar.gz: caecb83a030fa1eda5534e748ee3206208ebf25a1d9f76d33ad04030b4ea0f0c
+  metadata.gz: 29a9e3cd7ec91b93c24691976fef74ea5ab0cbc8f4fa237f449fa9322e42c6d2
+  data.tar.gz: 9a3c0e12e7d2fe8b6057662ebf6a392c749f7254ee41c4e77221a2e9f45ff6ac
 SHA512:
-  metadata.gz: 4a216a8032385e9be00252fb0d9faf1aaa18bdfe75a0ae4b0a2cb1aa438a8786a7e9c477debd87fb6871274c0a50e1579cee41584513199c47b0198c51c6ac6a
-  data.tar.gz: 664d85fe6070a9c0017e831727a33a87799d1b10e7c4992b44b77be288fcc3cab51ecb528ce01fe0ce5d7a6262f61a2786ce30c54dcd90e8ef36c698f3f76f45
+  metadata.gz: 53a12c330c32f76f13e651cef96ce29a6a442cf3dc7742faf2409a0ee17c7dfdcee1031c17696cd51d7bd3cf5b22b2df34b8be5a203cd1d4fd5df079eb357b82
+  data.tar.gz: f6c8f8850272353bbd32cc15d437d0b021c13d9bc93c5c988255d6c50fe21ff41aef5b719261ca95b00c129024fe325e2d3c8683c70f9b55e89a09a261fff31f

data/README.md

@@ -1,10 +1,10 @@
 # ruby-ulid
 
-A handy `ULID` library
+## Overview
 
-The `ULID` spec is defined on [ulid/spec](https://github.com/ulid/spec).
+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.
-Also providing rbs signature files.
+Also providing [ruby/rbs](https://github.com/ruby/rbs) signature files.
 
 ---
 
@@ -28,19 +28,31 @@ Instead, herein is proposed ULID:
 - 1.21e+24 unique ULIDs per millisecond
 - Lexicographically sortable!
 - Canonically encoded as a 26 character string, as opposed to the 36 character UUID
-- Uses Crockford's base32 for better efficiency and readability (5 bits per character)
+- Uses [Crockford's base32](https://www.crockford.com/base32.html) for better efficiency and readability (5 bits per character) # See also exists issues in [Note](#note)
 - Case insensitive
 - 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.0.16'
+```
+
+### Generator and Parser
 
 The generated `ULID` is an object not just a string.
 It means easily get the timestamps and binary formats.
@@ -52,36 +64,17 @@ ulid = ULID.generate #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GR
 ulid.to_time #=> 2021-04-27 17:27:22.826 UTC
 ulid.to_s #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
 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
-```
-
-Generator can take `Time` instance
-
-```ruby
-time = Time.at(946684800, in: '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)
-
-ulids = 1000.times.map do
-  ULID.generate(moment: time)
-end
-ulids.sort == ulids #=> false
-
-ulids = 1000.times.map do |n|
-  ULID.generate(moment: time + n)
-end
-ulids.sort == ulids #=> true
 ```
 
-You can parse from exists IDs
-
-FYI: Current parser/validator/matcher implementation aims `strict`, It might be changed in [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57).
+You can get the objects from exists encoded ULIDs
 
 ```ruby
 ulid = ULID.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV') #=> ULID(2016-07-30 23:54:10.259 UTC: 01ARZ3NDEKTSV4RRFFQ69G5FAV)
 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
@@ -89,8 +82,21 @@ 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
+
+```ruby
+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)
+
+ulids = 1000.times.map do |n|
+  ULID.generate(moment: time + n)
+end
+ulids.sort == ulids #=> true
 ```
 
 The basic generator prefers `randomness`, it does not guarantee `sortable` for same milliseconds ULIDs.
@@ -103,32 +109,72 @@ ulids.uniq(&:to_time).size #=> 35 (the size is not fixed, might be changed in en
 ulids.sort == ulids #=> false
 ```
 
-If you want to prefer `sortable` rather than the `strict randomness`, 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
 monotonic_generator = ULID::MonotonicGenerator.new
-monotonic_ulids = 10000.times.map do
+ulids = 10000.times.map do
   monotonic_generator.generate
 end
-sample_ulids_by_the_time = monotonic_ulids.uniq(&:to_time)
-sample_ulids_by_the_time.size #=> 34 (the size is not fixed, might be changed in environment)
-sample_ulids_by_the_time.take(10).map(&:randomness)
-#=>
-["JZW56CTA8704D5AQ",
- "JGEBH2A2B2EA97MW",
- "0XPE4NS3MZH0NAJ4",
- "E0S3ZAVADFBPW57Y",
- "E5CX1T6281443THQ",
- "3SK8WHSH03CVF7J2",
- "DDS35BT0R20P3V49",
- "60KG2W9FVEN1ZX8C",
- "X59YJVXXVH7AXJJE",
- "1ZBQ7SNGFKXGH1Y4"]
+sample_ulids_by_the_time = ulids.uniq(&:to_time)
+sample_ulids_by_the_time.size #=> 32 (the size is not fixed, might be changed in environment)
+
+# In same milliseconds creation, it just increments the end of randomness part
+ulids.take(5) #=>
+# [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK5),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK6),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK7),
+#  ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK8)]
+
+# When the milliseconds is updated, it starts with new randomness
+sample_ulids_by_the_time.take(5) #=>
+# [ULID(2021-05-02 15:23:48.917 UTC: 01F4PTVCSN9ZPFKYTY2DDJVRK4),
+#  ULID(2021-05-02 15:23:48.918 UTC: 01F4PTVCSPF2KXG4ABT7CK3204),
+#  ULID(2021-05-02 15:23:48.919 UTC: 01F4PTVCSQF1GERBPCQV6TCX2K),
+#  ULID(2021-05-02 15:23:48.920 UTC: 01F4PTVCSRBXN2H4P1EYWZ27AK),
+#  ULID(2021-05-02 15:23:48.921 UTC: 01F4PTVCSSK0ASBBZARV7013F8)]
 
-monotonic_ulids.sort == monotonic_ulids #=> true
+ulids.sort == ulids #=> true
+```
+
+### 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(one_of_the_above)
+ulids.grep_v(one_of_the_above)
+#=> I hope the results should be actually you want!
 ```
 
+### Scanner for string (e.g. `JSON`)
+
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
@@ -161,14 +207,16 @@ 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
+
 `ULID.min` and `ULID.max` return termination values for ULID spec.
 
 ```ruby
@@ -180,7 +228,10 @@ ULID.min(moment: time) #=> ULID(2000-01-01 00:00:00.123 UTC: 00VHNCZB3V000000000
 ULID.max(moment: 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"
@@ -196,15 +247,103 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
-UUIDv4 converter for migration use-cases. (Of course the timestamp will be useless one. Sortable benefit is lost.)
+`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.
+The imported timestamp is meaningless. So ULID's benefit will lost
 
 ```ruby
-ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
-#=> ULID(2301-07-10 00:28:28.821 UTC: 09GF8A5ZRN9P1RYDVXV52VBAHS)
+# 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"
+
+uuid_v4s = 10000.times.map { SecureRandom.uuid }
+uuid_v4s.uniq.size == 10000 #=> Probably `true`
+
+ulids = uuid_v4s.map { |uuid_v4| ULID.from_uuidv4(uuid_v4) }
+ulids.map(&:to_uuidv4) == uuid_v4s #=> **Probably** `true` except below examples.
+
+# NOTE: Some boundary values are not reversible. See below.
+
+ULID.min.to_uuidv4 #=> "00000000-0000-4000-8000-000000000000"
+ULID.max.to_uuidv4 #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
+
+# These importing results are same as https://github.com/ahawker/ulid/tree/96bdb1daad7ce96f6db8c91ac0410b66d2e1c4c1 on CPython 3.9.4
+reversed_min = ULID.from_uuidv4('00000000-0000-4000-8000-000000000000') #=> ULID(1970-01-01 00:00:00.000 UTC: 00000000008008000000000000)
+reversed_max = ULID.from_uuidv4('ffffffff-ffff-4fff-bfff-ffffffffffff') #=> ULID(10889-08-02 05:31:50.655 UTC: 7ZZZZZZZZZ9ZZVZZZZZZZZZZZZ)
+
+# But they are not reversible! Need to consider this issue in https://github.com/kachick/ruby-ulid/issues/76
+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.generate(moment: time).to_s
+-ULID.time(string)
++ULID.parse(string).to_time
+-ULID.min_ulid_at(time)
++ULID.min(moment: time).to_s
+-ULID.max_ulid_at(time)
++ULID.max(moment: 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)
 - [API documents](https://kachick.github.io/ruby-ulid/)
 - [ulid/spec](https://github.com/ulid/spec)
-- [Another choices are UUIDv6, UUIDv7, UUIDv8. But they are still in draft state](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html)
+
+## Note
+
+- Another choices for sortable and randomness IDs, [UUIDv6, UUIDv7, UUIDv8 might be the one. (But they are still in draft state)](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html), I will track them in [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)
+- Current parser/validator/matcher aims to cover `subset of Crockford's base32`. Suggesting it in [ulid/spec#57](https://github.com/ulid/spec/pull/57). Be that as it may, I might provide special handler or converter for the exception in [ruby-ulid#57](https://github.com/kachick/ruby-ulid/issues/57) and/or [ruby-ulid#78](https://github.com/kachick/ruby-ulid/issues/78)

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
@@ -16,6 +15,7 @@ class ULID
   class Error < StandardError; end
   class OverflowError < Error; end
   class ParserError < Error; end
+  class SetupError < ScriptError; end
 
   encoding_string = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
   # Crockford's Base32. Excluded I, L, O, U.
@@ -35,12 +35,15 @@ class ULID
   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
+  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
 
   # 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
+  Kernel.instance_method(:freeze).bind(UNDEFINED).call
+
   # @param [Integer, Time] moment
   # @param [Integer] entropy
   # @return [ULID]
@@ -51,27 +54,38 @@ class ULID
   # @param [Integer, Time] moment
   # @return [ULID]
   def self.min(moment: 0)
-    generate(moment: moment, entropy: 0)
+    0.equal?(moment) ? MIN : generate(moment: moment, entropy: 0)
   end
 
   # @param [Integer, Time] moment
   # @return [ULID]
   def self.max(moment: MAX_MILLISECONDS)
-    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)
+    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 
+  # @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
@@ -121,6 +135,43 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @param [Range<Time>, Range<nil>] time_range
+  # @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?
+
+    case begin_time
+    when Time
+      begin_ulid = min(moment: begin_time)
+    when nil
+      begin_ulid = MIN
+    else
+      raise argument_error_for_range_building(time_range)
+    end
+
+    case end_time
+    when Time
+      if exclude_end
+        end_ulid = min(moment: end_time)
+      else
+        end_ulid = max(moment: end_time)
+      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
+    else
+      raise argument_error_for_range_building(time_range)
+    end
+
+    begin_ulid.freeze
+    end_ulid.freeze
+
+    Range.new(begin_ulid, end_ulid, exclude_end)
+  end
+
   # @param [Time] time
   # @return [Time]
   def self.floor(time)
@@ -131,49 +182,99 @@ 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
 
+  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
-  # @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)
+      raise "given argument does not match to `#{STRICT_PATTERN.inspect}`" unless STRICT_PATTERN.match?(string)
+      n32encoded = convert_crockford_base32_to_n32(string.upcase)
+      timestamp = n32encoded.slice(0, TIMESTAMP_PART_LENGTH)
+      randomness = n32encoded.slice(TIMESTAMP_PART_LENGTH, RANDOMNESS_PART_LENGTH)
+      milliseconds = timestamp.to_i(32)
+      entropy = randomness.to_i(32)
     rescue => err
       raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
     end
-  
+
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @api private
+  private_class_method def self.convert_crockford_base32_to_n32(string)
+    string.gsub(CROCKFORD_BASE32_CHAR_PATTERN, N32_CHAR_BY_CROCKFORD_BASE32_CHAR)
+  end
+
   # @return [Boolean]
   def self.valid?(string)
     parse(string)
@@ -208,6 +309,11 @@ class ULID
     num
   end
 
+  # @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}"
+  end
+
   attr_reader :milliseconds, :entropy
 
   # @api private
@@ -228,10 +334,9 @@ class ULID
   end
 
   # @return [String]
-  def to_str
-    @string ||= Integer::Base.string_for(to_i, ENCODING_CHARS).rjust(ENCODED_ID_LENGTH, '0').upcase.freeze
+  def to_s
+    @string ||= convert_n32_to_crockford_base32(to_i.to_s(32).rjust(ENCODED_ID_LENGTH, '0').upcase).freeze
   end
-  alias_method :to_s, :to_str
 
   # @return [Integer]
   def to_i
@@ -246,7 +351,7 @@ class ULID
 
   # @return [String]
   def inspect
-    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{to_str})".freeze
+    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{to_s})".freeze
   end
 
   # @return [Boolean]
@@ -307,11 +412,13 @@ class ULID
     @randomness ||= matchdata[:randomness].freeze
   end
 
+  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def pattern
     @pattern ||= /(?<timestamp>#{timestamp})(?<randomness>#{randomness})/i.freeze
   end
 
+  # @deprecated This method might be changed in https://github.com/kachick/ruby-ulid/issues/84
   # @return [Regexp]
   def strict_pattern
     @strict_pattern ||= /\A#{pattern.source}\z/i.freeze
@@ -332,23 +439,45 @@ class ULID
     @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
+    end
+  end
+
   # @return [self]
   def freeze
-    # Evaluate all caching
-    inspect
-    octets
-    to_i
-    succ
-    pred
-    strict_pattern
+    # Need to cache before freezing, because frozen objects can't assign instance variables
+    cache_all_instance_variables
     super
   end
 
   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_str).freeze
+    @matchdata ||= STRICT_PATTERN.match(to_s).freeze
+  end
+
+  # @return [void]
+  def cache_all_instance_variables
+    inspect
+    octets
+    to_i
+    succ
+    pred
+    strict_pattern
+    to_uuidv4
   end
 end
 
@@ -356,7 +485,8 @@ require_relative 'ulid/version'
 require_relative 'ulid/monotonic_generator'
 
 class ULID
-  MONOTONIC_GENERATOR = MonotonicGenerator.new
+  MIN = parse('00000000000000000000000000').freeze
+  MAX = parse('7ZZZZZZZZZZZZZZZZZZZZZZZZZ').freeze
 
-  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :UUIDV4_PATTERN
+  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.12'
+  VERSION = '0.0.17'
 end

data/sig/ulid.rbs

@@ -15,9 +15,16 @@ class ULID
   PATTERN: Regexp
   STRICT_PATTERN: Regexp
   UUIDV4_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`
   type moment = Time | Integer
 
   class Error < StandardError
@@ -29,6 +36,9 @@ class ULID
   class ParserError < Error
   end
 
+  class SetupError < ScriptError
+  end
+
   class MonotonicGenerator
     attr_accessor latest_milliseconds: Integer
     attr_accessor latest_entropy: Integer
@@ -56,13 +66,14 @@ class ULID
   @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.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.floor: (Time time) -> Time
   def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> ULID
@@ -70,6 +81,8 @@ 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)
@@ -78,8 +91,7 @@ class ULID
   attr_reader milliseconds: Integer
   attr_reader entropy: Integer
   def initialize: (milliseconds: Integer, entropy: Integer) -> void
-  def to_str: -> String
-  alias to_s to_str
+  def to_s: -> String
   def to_i: -> Integer
   alias hash to_i
   def <=>: (ULID other) -> Integer
@@ -96,11 +108,16 @@ class ULID
   def octets: -> octets
   def timestamp_octets: -> timestamp_octets
   def randomness_octets: -> randomness_octets
+  def to_uuidv4: -> String
   def next: -> ULID?
   alias succ next
   def pred: -> 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,29 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.17
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-02 00:00:00.000000000 Z
+date: 2021-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: integer-base
+  name: rbs
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
+        version: 1.2.0
+  type: :development
   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
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
@@ -70,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: []
@@ -82,7 +76,6 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- Steepfile
 - lib/ulid.rb
 - lib/ulid/monotonic_generator.rb
 - lib/ulid/version.rb
@@ -102,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Steepfile

@@ -1,7 +0,0 @@
-target :lib do
-  signature 'sig'
-
-  check 'lib'
-
-  library 'securerandom'
-end