ruby-ulid 0.0.12 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0adfc974863e1b2d248eac28305322e20d6b2dc94465b7ca3462fdd2c8676352
-  data.tar.gz: caecb83a030fa1eda5534e748ee3206208ebf25a1d9f76d33ad04030b4ea0f0c
+  metadata.gz: 9e2d0489b211160618fc0ae6ecd30cbbbbaa411683162def97930ca95a860696
+  data.tar.gz: 0063c982795d2a42e2f6bac7b236d831753c685b36f4d047e2999dbe7368c6de
 SHA512:
-  metadata.gz: 4a216a8032385e9be00252fb0d9faf1aaa18bdfe75a0ae4b0a2cb1aa438a8786a7e9c477debd87fb6871274c0a50e1579cee41584513199c47b0198c51c6ac6a
-  data.tar.gz: 664d85fe6070a9c0017e831727a33a87799d1b10e7c4992b44b77be288fcc3cab51ecb528ce01fe0ce5d7a6262f61a2786ce30c54dcd90e8ef36c698f3f76f45
+  metadata.gz: 825dab6b7e01f4e1dee5fcd03031ef27645de6a1b56e8392fd784a55c860268af5b84ae4ac3697cdf3eba630dbae197da28cde4b8fbef043c8d0ff48b587f992
+  data.tar.gz: f2039e401c77cf15bda81d10587085b7fa167c253a19a66bc0b14ee5fda71162325b7a278f2ebb185d53cbb3fd01563ccb4c6875ffbaebf7fc676a2a24c73767

data/README.md

@@ -35,6 +35,8 @@ Instead, herein is proposed ULID:
 
 ## Install
 
+Require Ruby 2.6 or later
+
 ```console
 $ gem install ruby-ulid
 #=> Installed
@@ -55,27 +57,7 @@ ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 7
 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)
@@ -93,6 +75,19 @@ ulids.sort == ulids #=> true
 ulids.uniq(&:to_time).size #=> 1000
 ```
 
+`ULID.generate` can take fixed `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 |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.
 
 ```ruby
@@ -103,7 +98,7 @@ 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.
+If you want to prefer `sortable` rather than the `randomness`, 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
@@ -112,23 +107,41 @@ monotonic_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.size #=> 32 (the size is not fixed, might be changed in environment)
+
+# In same milliseconds creation, it just increments the end of randomness part
+monotonic_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
 ```
 
+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]`
+
+```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
+
+# So you can use the generated range objects as below
+ulids.grep(include_end)
+ulids.grep(exclude_end)
+#=> I hope the results should be actually you want!
+```
+
 For rough operations, `ULID.scan` might be useful.
 
 ```ruby
@@ -205,6 +218,8 @@ ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
 
 ## 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)
+- [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), I will track them in [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)
+- 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).

data/lib/ulid.rb

@@ -121,6 +121,39 @@ class ULID
     new milliseconds: milliseconds, entropy: entropy
   end
 
+  # @param [Range<Time>] time_range
+  # @return [Range<ULID>]
+  def self.range(time_range)
+    raise ArgumentError, 'ULID.range takes only Range[Time]' 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 ArgumentError, 'ULID.range takes only Range[Time]'
+    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 ArgumentError, 'ULID.range takes only Range[Time]'
+    end
+
+    Range.new(begin_ulid, end_ulid, exclude_end)
+  end
+
   # @param [Time] time
   # @return [Time]
   def self.floor(time)

data/lib/ulid/version.rb

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

data/sig/ulid.rbs

@@ -63,6 +63,7 @@ class 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] time_range) -> Range[ULID]
   def self.floor: (Time time) -> Time
   def self.reasonable_entropy: -> Integer
   def self.parse: (String string) -> ULID

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.13
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-02 00:00:00.000000000 Z
+date: 2021-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: integer-base
@@ -30,6 +30,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
@@ -102,14 +116,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: A handy ULID library