ruby-ulid 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 323b750a4e11157bd492b31d74833df2042192775c8627917880ef386dee4c1c
-  data.tar.gz: 2dc8a91cbed7b473d6f9e28480dd227ab3469828ab0833f48a754111bd6e926c
+  metadata.gz: 6c0ca476ab05b4b53ce593e893ffdfd6aa72b3c08563116b95f5a22f43a7926b
+  data.tar.gz: 7454acd393c8df299696d2907a71f994643dacc45103e2874561d186e1fa85c5
 SHA512:
-  metadata.gz: e78a5289863c1300a3f4c186b72a0f1d97cd709ce6043b69729d851f5e6ffcedac001e3bb691397d761ee497d609b5292c300db7f2ec3f8cf5be0ee5c095af80
-  data.tar.gz: e19197709d7a896a79c6ebdc40fa919c2e7876284fa1dbf8895498ad7b80e989634cdd3e651362db5cf9f7c627fe17439ccc21e75c8e6598b002da6b19858aa0
+  metadata.gz: bfe19e20452a12edd7472ddaf3b9583d2eaa5640e03a081621c35bcfdf218f9ccf5d7c7625b0850312447f61c0592796d333aa4578a6c2f0281e6ff4e8392efd
+  data.tar.gz: cdd8dba77214852ea70d07a137f75098558097db686a4409dd14e611d533de33f4c510b9a38ee232e918dd0aae6b028f19a4dd7312ac42172890d726091f282b

data/README.md

@@ -38,12 +38,12 @@ Instead, herein is proposed ULID:
 
 ### Install
 
-Tested only in the last 2 Rubies. So you need Ruby 3.1 or higher.
+Tested only in the last 2 Rubies. So you need Ruby 3.2 or higher.
 
 Add this line to your `Gemfile`.
 
 ```ruby
-gem('ruby-ulid', '~> 0.8.0')
+gem('ruby-ulid', '~> 0.9.0')
 ```
 
 And load it.
@@ -53,7 +53,18 @@ require 'ulid'
 ```
 
 NOTE: This README contains information about the development version.\
-If you would like to see released version's one. [Look at the ref](https://github.com/kachick/ruby-ulid/tree/v0.8.0).
+If you would like to see released version's one. [Look at the ref](https://github.com/kachick/ruby-ulid/tree/v0.9.0).
+
+In [Nix](https://nixos.org/), you can skip the installation steps for both ruby and ruby-ulid to try.
+
+```console
+> nix run github:kachick/ruby-ulid#ruby -- -e 'p ULID.generate'
+ULID(2024-03-03 18:37:06.152 UTC: 01HR2SNY789ZZ027EDJEHAGQ62)
+
+> nix run github:kachick/ruby-ulid#irb
+irb(main):001:0> ULID.parse('01H66XG2A9WWYRCYGPA62T4AZA')
+=> ULID(2023-07-25 16:18:12.937 UTC: 01H66XG2A9WWYRCYGPA62T4AZA)
+```
 
 ### Generator and Parser
 
@@ -269,7 +280,7 @@ 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)
 ```
 
-#### As element in Enumerable
+#### As an element in Enumerable and Range
 
 `ULID#next` and `ULID#succ` returns next(successor) ULID.\
 Especially `ULID#succ` makes it possible `Range[ULID]#each`.
@@ -290,6 +301,17 @@ ULID.parse('01BX5ZZKBK0000000000000000').pred.to_s #=> "01BX5ZZKBJZZZZZZZZZZZZZZ
 ULID.parse('00000000000000000000000000').pred #=> nil
 ```
 
+`ULID#+` is also provided to realize `Range#step` since [ruby-3.4.0 spec changes](https://bugs.ruby-lang.org/issues/18368).
+
+```ruby
+# This code works only in ruby-3.4.0dev or later
+(ULID.min...).step(42).take(3)
+# =>
+[ULID(1970-01-01 00:00:00.000 UTC: 00000000000000000000000000),
+ ULID(1970-01-01 00:00:00.000 UTC: 0000000000000000000000001A),
+ ULID(1970-01-01 00:00:00.000 UTC: 0000000000000000000000002M)]
+```
+
 #### Test helpers
 
 `ULID.sample` returns random ULIDs.
@@ -390,6 +412,10 @@ ULID.max.to_uuidish #=> "ffffffff-ffff-ffff-ffff-ffffffffffff"
 ULID.max.to_uuidv4(force: true) #=> "ffffffff-ffff-4fff-bfff-ffffffffffff"
 ```
 
+[UUIDv6, UUIDv7, UUIDv8](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-02.html) are other candidates for sortable and randomness ID.\
+Latest [ruby/securerandom merged the UUIDv7 generator](https://github.com/ruby/securerandom/pull/19).\
+See [tracker](https://bugs.ruby-lang.org/issues/19735) for further detail.
+
 ## Migration from other gems
 
 See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-migration).
@@ -404,9 +430,3 @@ See [wiki page for gem migration](https://github.com/kachick/ruby-ulid/wiki/Gem-
 - [Repository](https://github.com/kachick/ruby-ulid)
 - [API documents](https://kachick.github.io/ruby-ulid/)
 - [ulid/spec](https://github.com/ulid/spec)
-
-## Note
-
-- [UUIDv6, UUIDv7, UUIDv8](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-02.html) is another choice for sortable and randomness ID.
-  \
-  However they remain in draft state. Our tracker is: [ruby-ulid#37](https://github.com/kachick/ruby-ulid/issues/37)

data/lib/ulid/monotonic_generator.rb

@@ -10,7 +10,7 @@ require_relative('utils')
 class ULID
   class MonotonicGenerator
     # @note When use https://github.com/ko1/ractor-tvar might realize Ractor based thread safe monotonic generator.
-    #       However it is a C extention, I'm pending to use it for now.
+    #       However it is a C extension, I'm pending to use it for now.
     include(MonitorMixin)
 
     # @return [ULID, nil]

data/lib/ulid/uuid/fields.rb

@@ -0,0 +1,41 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# shareable_constant_value: literal
+
+# Copyright (C) 2021 Kenichi Kamiya
+
+class ULID
+  module UUID
+    # @see https://www.rfc-editor.org/rfc/rfc4122#section-4.1.2
+    # @note
+    #   - Using `Fields = Data.define do; end` syntax made https://github.com/kachick/ruby-ulid/issues/233 again. So use class syntax instead
+    #   - This file is extracted to avoid YARD warnings "Ruby::ClassHandler: Undocumentable superclass" https://github.com/lsegal/yard/issues/737
+    #     Partially avoiding is hard in YARD, so extracting the code and using exclude filter in yardopts...
+    class Fields < Data.define(:time_low, :time_mid, :time_hi_and_version, :clock_seq_hi_and_res, :clk_seq_low, :node)
+      def self.raw_from_octets(octets)
+        case octets.pack('C*').unpack('NnnnnN')
+        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
+          new(time_low:, time_mid:, time_hi_and_version:, clock_seq_hi_and_res:, clk_seq_low:, node:).freeze
+        end
+      end
+
+      def self.forced_v4_from_octets(octets)
+        case octets.pack('C*').unpack('NnnnnN')
+        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
+          new(
+            time_low:,
+            time_mid:,
+            time_hi_and_version: (time_hi_and_version & 0x0fff) | 0x4000,
+            clock_seq_hi_and_res: (clock_seq_hi_and_res & 0x3fff) | 0x8000,
+            clk_seq_low:,
+            node:
+          ).freeze
+        end
+      end
+
+      def to_s
+        '%08x-%04x-%04x-%04x-%04x%08x' % deconstruct
+      end
+    end
+  end
+end

data/lib/ulid/uuid.rb

@@ -6,6 +6,7 @@
 
 require_relative('errors')
 require_relative('utils')
+require_relative('uuid/fields')
 
 class ULID
   module UUID
@@ -37,36 +38,6 @@ class ULID
 
       parse_any_to_int(encoded)
     end
-
-    # @see https://www.rfc-editor.org/rfc/rfc4122#section-4.1.2
-    # @todo Replace to Data class after dropped Ruby 3.1
-    # @note Using `Fields = Struct.new` syntax made https://github.com/kachick/ruby-ulid/issues/233 again. So use class syntax instead
-    class Fields < Struct.new(:time_low, :time_mid, :time_hi_and_version, :clock_seq_hi_and_res, :clk_seq_low, :node, keyword_init: true)
-      def self.raw_from_octets(octets)
-        case octets.pack('C*').unpack('NnnnnN')
-        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
-          new(time_low:, time_mid:, time_hi_and_version:, clock_seq_hi_and_res:, clk_seq_low:, node:).freeze
-        end
-      end
-
-      def self.forced_v4_from_octets(octets)
-        case octets.pack('C*').unpack('NnnnnN')
-        in [Integer => time_low, Integer => time_mid, Integer => time_hi_and_version, Integer => clock_seq_hi_and_res, Integer => clk_seq_low, Integer => node]
-          new(
-            time_low:,
-            time_mid:,
-            time_hi_and_version: (time_hi_and_version & 0x0fff) | 0x4000,
-            clock_seq_hi_and_res: (clock_seq_hi_and_res & 0x3fff) | 0x8000,
-            clk_seq_low:,
-            node:
-          ).freeze
-        end
-      end
-
-      def to_s
-        '%08x-%04x-%04x-%04x-%04x%08x' % values
-      end
-    end
   end
 
   Ractor.make_shareable(UUID)

data/lib/ulid/version.rb

@@ -3,5 +3,5 @@
 # shareable_constant_value: literal
 
 class ULID
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
 end

data/lib/ulid.rb

@@ -449,33 +449,43 @@ class ULID
     @encoded.slice(TIMESTAMP_ENCODED_LENGTH, RANDOMNESS_ENCODED_LENGTH) || raise(UnexpectedError)
   end
 
-  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
-  def succ
-    succ_int = @integer.succ
-    if succ_int >= MAX_INTEGER
-      if succ_int == MAX_INTEGER
-        MAX
-      else
+  # @param [Integer] other
+  # @return [ULID, nil] when returning URID might be greater than `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
+  def +(other)
+    raise(ArgumentError, 'ULID#+ takes only integers') unless Integer === other
+
+    new_int = @integer + other
+    case new_int
+    when MAX_INTEGER
+      MAX
+    when 0
+      MIN
+    else
+      if new_int > MAX_INTEGER || new_int < 0
         nil
+      else
+        ULID.from_integer(new_int)
       end
-    else
-      ULID.from_integer(succ_int)
     end
   end
+
+  # @param [Integer] other
+  # @return [ULID, nil] when returning URID might be less than `00000000000000000000000000`, returns `nil` instead of ULID
+  def -(other)
+    raise(ArgumentError, 'ULID#- takes only integers') unless Integer === other
+
+    self + -other
+  end
+
+  # @return [ULID, nil] when called on ULID as `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, returns `nil` instead of ULID
+  def succ
+    self + 1
+  end
   alias_method(:next, :succ)
 
   # @return [ULID, nil] when called on ULID as `00000000000000000000000000`, returns `nil` instead of ULID
   def pred
-    pred_int = @integer.pred
-    if pred_int <= 0
-      if pred_int == 0
-        MIN
-      else
-        nil
-      end
-    else
-      ULID.from_integer(pred_int)
-    end
+    self - 1
   end
 
   # @return [Integer]

data/sig/ulid.rbs

@@ -41,17 +41,17 @@ class ULID < Object
     def self.parse_any_to_int: (String) -> Integer
     def self.parse_v4_to_int: (String) -> Integer
 
-    class Fields < Struct[Integer]
-      attr_accessor time_low: Integer
-      attr_accessor time_mid: Integer
-      attr_accessor time_hi_and_version: Integer
-      attr_accessor clock_seq_hi_and_res: Integer
-      attr_accessor clk_seq_low: Integer
-      attr_accessor node: Integer
+    class Fields
+      attr_reader time_low: Integer
+      attr_reader time_mid: Integer
+      attr_reader time_hi_and_version: Integer
+      attr_reader clock_seq_hi_and_res: Integer
+      attr_reader clk_seq_low: Integer
+      attr_reader node: Integer
       def self.raw_from_octets: (octets) -> Fields
       def self.forced_v4_from_octets: (octets) -> Fields
 
-      def values: -> Array[Integer]
+      def deconstruct: -> Array[Integer]
 
       private
 
@@ -147,7 +147,7 @@ class ULID < Object
   @integer: Integer
   @encoded: String
 
-  # Retuns a ULID
+  # Returns a ULID
   #
   # They are sortable when generated in different timestamp with milliseconds precision
   #
@@ -183,7 +183,7 @@ class ULID < Object
   #
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
 
-  # Retuns encoded and normalzied String.\
+  # Returns encoded and normalzied String.\
   # It has same arguments signatures as `.generate`\
   # So can be used for just ID creation usecases without needless object creation.
   #
@@ -594,6 +594,18 @@ class ULID < Object
   # ```
   def octets: -> octets
 
+  # Returns incremented ULID.\
+  # Especially providing for Range#step since ruby-3.4.0 spec changes
+  #
+  # See also [ruby-lang#18368](https://bugs.ruby-lang.org/issues/18368)
+  # ```
+  def +: (Integer other) -> ULID?
+
+  # Returns decremented ULID.\
+  # Providing for realizing natural API convention with the `ULID#+`
+  # ```
+  def -: (Integer other) -> ULID?
+
   # Returns next(successor) ULID.\
   # Especially `ULID#succ` makes it possible `Range[ULID]#each`.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Kenichi Kamiya
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 2024-08-28 00:00:00.000000000 Z
 dependencies: []
 description: "    generator, optional monotonicity, parser and tools for ULID (RBS
   included)\n"
@@ -27,6 +27,7 @@ files:
 - lib/ulid/monotonic_generator.rb
 - lib/ulid/utils.rb
 - lib/ulid/uuid.rb
+- lib/ulid/uuid/fields.rb
 - lib/ulid/version.rb
 - sig/ulid.rbs
 homepage: https://github.com/kachick/ruby-ulid
@@ -34,7 +35,6 @@ licenses:
 - MIT
 metadata:
   documentation_uri: https://kachick.github.io/ruby-ulid/
-  homepage_uri: https://github.com/kachick/ruby-ulid
   source_code_uri: https://github.com/kachick/ruby-ulid
   bug_tracker_uri: https://github.com/kachick/ruby-ulid/issues
   rubygems_mfa_required: 'true'
@@ -46,14 +46,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: ULID manipulation library