ruby-ulid 0.7.0 → 0.8.0

data/sig/ulid.rbs

@@ -3,8 +3,6 @@ class ULID < Object
   TIMESTAMP_ENCODED_LENGTH: 10
   RANDOMNESS_ENCODED_LENGTH: 16
   ENCODED_LENGTH: 26
-  TIMESTAMP_OCTETS_LENGTH: 6
-  RANDOMNESS_OCTETS_LENGTH: 10
   OCTETS_LENGTH: 16
   MAX_MILLISECONDS: 281474976710655
   MAX_ENTROPY: 1208925819614629174706175
@@ -14,7 +12,6 @@ class ULID < Object
   PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
   STRICT_PATTERN_WITH_CROCKFORD_BASE32_SUBSET: Regexp
   SCANNING_PATTERN: Regexp
-  UUIDV4_PATTERN: Regexp
   MIN: ULID
   MAX: ULID
   include Comparable
@@ -34,9 +31,37 @@ class ULID < Object
   class UnexpectedError < Error
   end
 
+  class IrreversibleUUIDError < Error
+  end
+
+  module UUID
+    BASE_PATTERN: Regexp
+    V4_PATTERN: Regexp
+
+    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
+      def self.raw_from_octets: (octets) -> Fields
+      def self.forced_v4_from_octets: (octets) -> Fields
+
+      def values: -> Array[Integer]
+
+      private
+
+      def initialize: (?time_low: Integer, ?time_mid: Integer, ?time_hi_and_version: Integer, ?clock_seq_hi_and_res: Integer, ?clk_seq_low: Integer, ?node: Integer) -> void
+    end
+  end
+
   # Private module
   module Utils
-    def self.encode_base32: (milliseconds: milliseconds, entropy: Integer) -> String
+    def self.encode_base32hex: (milliseconds: milliseconds, entropy: Integer) -> String
 
     def self.current_milliseconds: -> milliseconds
 
@@ -48,9 +73,7 @@ class ULID < Object
 
     def self.safe_get_class_name: (untyped object) -> String
 
-    def self.make_sharable_value: (untyped object) -> void
-
-    def self.make_sharable_constantans: (Module) -> void
+    def self.make_sharable_constants: (Module) -> void
 
     def self.ractor_can_make_shareable_time?: -> bool
   end
@@ -59,7 +82,7 @@ class ULID < Object
   module CrockfordBase32
     ENCODING_STRING: String
     CROCKFORD_TR_PATTERN: String
-    BASE32_TR_PATTERN: String
+    BASE32HEX_TR_PATTERN: String
     VARIANT_TR_PATTERN: String
     NORMALIZED_TR_PATTERN: String
 
@@ -69,67 +92,60 @@ class ULID < Object
 
     def self.normalize: (String string) -> String
 
-    def self.from_base32: (String base32encoded) -> String
+    def self.from_base32hex: (String base32hex) -> String
   end
 
   class MonotonicGenerator
     include MonitorMixin
 
-    # Returned value is `basically not` Thread-safety
+    # Returned value is `basically not` Thread-safety\
     # If you want to keep Thread-safety, keep to call {#generate} only in same {#synchronize} block
     #
     # ```ruby
     # generator.synchronize do
-    #   generator.prev
+    #   generator.last
     #   generator.inspect
     #   generator.generate
     # end
     # ```
-    attr_reader prev: ULID | nil
+    attr_reader last: ULID | nil
 
-    # See [How to keep `Sortable` even if in same timestamp](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)
+    # See [How to keep `Sortable` even if in same timestamp](https://github.com/kachick/ruby-ulid#how-to-keep-sortable-even-if-in-same-timestamp)\
     # The `Thread-safety` is implemented with [Monitor](https://bugs.ruby-lang.org/issues/16255)
     def generate: (?moment: moment) -> ULID
 
     # Just providing similar api as `ULID.generate` and `ULID.encode` relation. No performance benefit exists in monotonic generator's one.
     def encode: (?moment: moment) -> String
 
-    # Returned value is `basically not` Thread-safety
+    # Returned value is `basically not` Thread-safety\
     # If you want to keep Thread-safety, keep to call {#generate} only in same {#synchronize} block
     #
     # ```ruby
     # generator.synchronize do
-    #   generator.prev
+    #   generator.last
     #   generator.inspect
     #   generator.generate
     # end
     # ```
     def inspect: -> String
     alias to_s inspect
-    def freeze: -> void
 
     private
 
     def initialize: -> void
 
-    def prev=: (ULID?) -> void
+    def last=: (ULID?) -> void
   end
 
   interface _ToULID
     def to_ulid: () -> ULID
   end
 
-  type full_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
-  type timestamp_octets = [Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
-  type randomness_octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
+  type octets = [Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer] | Array[Integer]
   type period = Range[Time] | Range[nil] | Range[ULID]
 
   @integer: Integer
   @encoded: String
-  @timestamp: String?
-  @randomness: String?
-  @inspect: String?
-  @time: Time?
 
   # Retuns a ULID
   #
@@ -167,14 +183,13 @@ class ULID < Object
   #
   def self.generate: (?moment: moment, ?entropy: Integer) -> ULID
 
-  # Retuns encoded and normalzied String.
-  # It has same arguments signatures as `.generate`. So can be used for just ID creation usecases without needless object creation.
-  #
-  # NOTE: Difference of ULID#encode, returned String is NOT frozen.
+  # Retuns encoded and normalzied String.\
+  # It has same arguments signatures as `.generate`\
+  # So can be used for just ID creation usecases without needless object creation.
   #
   def self.encode: (?moment: moment, ?entropy: Integer) -> String
 
-  # Shorthand of `ULID.generate(moment: Time)`
+  # Shorthand of `ULID.generate(moment: Time)`\
   # See also [ULID.generate](https://kachick.github.io/ruby-ulid/ULID.html#generate-class_method)
   #
   # ```ruby
@@ -188,7 +203,8 @@ class ULID < Object
   # ```
   def self.at: (Time time) -> ULID
 
-  # `ULID` can be element of the `Range`. If you generated the IDs in monotonic generator, ID based filtering is easy and reliable
+  # `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
@@ -236,16 +252,18 @@ class ULID < Object
   # ```
   def self.parse: (_ToStr string) -> ULID
 
-  # Return Time instance from encoded String.
+  type time_in = String | Integer | nil
+
+  # Return Time instance from encoded String.\
   # See also `ULID.encode` for similar purpose.
   #
-  # NOTE: Difference of ULID#to_time, returned Time is NOT frozen.
-  #
   # ```ruby
   # time = ULID.decode_time('01ARZ3NDEKTSV4RRFFQ69G5FAV')
   # #=> 2016-07-30 23:54:10.259 UTC
+  # ULID.decode_time('01ARZ3NDEKTSV4RRFFQ69G5FAV', in: '+09:00')
+  # #=> 2016-07-31 08:54:10.259 +0900
   # ```
-  def self.decode_time: (_ToStr string, ?in: String | Integer | nil) -> Time
+  def self.decode_time: (_ToStr string, ?in: time_in) -> Time
 
   # Get ULID instance from unnormalized String that encoded in Crockford's base32.
   #
@@ -262,18 +280,35 @@ class ULID < Object
   # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
   def self.parse_variant_format: (_ToStr string) -> ULID
 
+  # Load a UUID-like string without checking version and variants.
+  #
   # ```ruby
-  # # Currently experimental feature, so needed to load the extension.
-  # require 'ulid/uuid'
+  # ULID.from_uuidish('123e4567-e89b-12d3-a456-426614174000')
+  # #=> ULID(2605-08-20 10:28:29.979 UTC: 0J7S2PFT4V2B9T8NJ2CRA1EG00)
+  # ```
+  #
+  # See also [ULID.from_uuidv4]
+  def self.from_uuidish: (String uuidish) -> ULID
+
+  # Load a UUIDv4 string with checking version and variants.
   #
-  # # Basically reversible
-  # ulid = ULID.from_uuidv4('0983d0a2-ff15-4d83-8f37-7dd945b5aa39')
+  # ```ruby
+  # 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"
+  # ULID.from_uuidv4('123e4567-e89b-12d3-a456-426614174000')
+  # #=> ULID::ParserError
   # ```
   #
-  # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
+  # See also [ULID.from_uuidish]
   def self.from_uuidv4: (String uuid) -> ULID
+
+  # Load integer as ULID
+  #
+  # ```ruby
+  # ulid = ULID.parse('01GTXYCWNDKRYH14DBZ77TRSD7')
+  # ULID.from_integer(ulid.to_i)
+  # #=> ULID(2023-03-07 11:48:07.469 UTC: 01GTXYCWNDKRYH14DBZ77TRSD7)
+  # ```
   def self.from_integer: (Integer integer) -> ULID
 
   # Returns termination values for ULID spec.
@@ -334,7 +369,8 @@ class ULID < Object
   # # ULID(2665-03-16 14:50:22.724 UTC: 0KYFW9DWM4CEGFNTAC6YFAVVJ6)]
   # ```
   #
-  # You can specify a range object for the timestamp restriction, See also [ULID.range](https://kachick.github.io/ruby-ulid/ULID.html#range-class_method).
+  # You can specify a range object for the timestamp restriction.\
+  # See also [ULID.range](https://kachick.github.io/ruby-ulid/ULID.html#range-class_method)
   #
   # ```ruby
   # ulid1 = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA') #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
@@ -395,19 +431,6 @@ class ULID < Object
   def self.valid_as_variant_format?: (_ToStr string) -> bool
                              | (untyped) -> false
 
-  # DEPRECATED Use valid_as_variant_format? instead
-  #
-  # Returns `true` if it is normalized string.
-  # Basically the difference of normalized? is to accept downcase or not. This returns true for downcased ULIDs.
-  #
-  # ```ruby
-  # ULID.valid?(ULID.generate.to_s.downcase) #=> true
-  # ```
-  #
-  # See also [ulid/spec#57](https://github.com/ulid/spec/pull/57) and [ulid/spec#3](https://github.com/ulid/spec/issues/3)
-  def self.valid?: (_ToStr string) -> bool
-                 | (untyped) -> false
-
   # Returns parsed ULIDs from given String for rough operations.
   #
   # ```ruby
@@ -450,6 +473,7 @@ class ULID < Object
   def self.scan:  (_ToStr string) -> Enumerator[self, singleton(ULID)]
                 | (_ToStr string) { (ULID ulid) -> void } -> singleton(ULID)
 
+  # Returns nil if given object is not a ULID
   def self.try_convert: (_ToULID) -> ULID
                       | (untyped) -> nil
 
@@ -459,14 +483,16 @@ class ULID < Object
   # ulid.milliseconds #=> 1619544442826
   # ```
   attr_reader milliseconds: Integer
+
   attr_reader entropy: Integer
 
+  # Private api. (Actually defined protected visibility)
+  attr_reader encoded: String
+
   # ```ruby
   # ulid = ULID.generate
   # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
   # ulid.encode #=> "01F4A5Y1YAQCYAYCTC7GRMJ9AA"
-  # ulid.encode.frozen? #=> true
-  # ulid.encode.equal?(ulid.to_s) #=> true
   # ```
   def encode: -> String
   alias to_s encode
@@ -489,7 +515,7 @@ class ULID < Object
   # #=> true
   # ```
   #
-  # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future.
+  # To be precise, this sorting unaffected with `case sensitive or not` and might handle [ulid/spec#57](https://github.com/ulid/spec/pull/57) in future.\
   # So preferable than `lexicographically sortable` in actual case.
   #
   # This returns -1 | 0 | 1 for ULIDs. However defined as returning Integer. It is caused on ruby/rbs current definition.
@@ -499,6 +525,8 @@ class ULID < Object
   def <=>: (ULID other) -> Integer
          | (untyped other) -> nil
 
+  # Returns human readable strings that used by Kernel.#p
+  #
   # ```ruby
   # ulid = ULID.generate
   # ulid.inspect #=> "ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)"
@@ -513,7 +541,7 @@ class ULID < Object
           | (untyped other) -> false
   alias == eql?
 
-  # Return `true` for same value of ULID, variant formats of strings, same Time in ULID precision(msec).
+  # Return `true` for same value of ULID, variant formats of strings, same Time in ULID precision(msec).\
   # Do not consider integer, octets and partial strings, then returns `false`.
   #
   # ```ruby
@@ -533,12 +561,15 @@ class ULID < Object
          | (untyped other) -> false
 
   # ```ruby
-  # 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.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA').to_time
+  # #=> 2021-04-27 17:27:22.826 UTC
+  # ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA').to_time(in: '+09:00')
+  # #=> 2021-04-28 02:27:22.826 +0900
   # ```
-  def to_time: -> Time
+  def to_time: (?in: time_in) -> Time
 
+  # Returns timestamp(prefix) part of encoded ULID
+  #
   # ```ruby
   # ulid = ULID.generate
   # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
@@ -546,6 +577,8 @@ class ULID < Object
   # ```
   def timestamp: -> String
 
+  # Returns randomness(suffix) part of encoded ULID
+  #
   # ```ruby
   # ulid = ULID.generate
   # #=> ULID(2021-04-27 17:27:22.826 UTC: 01F4A5Y1YAQCYAYCTC7GRMJ9AA)
@@ -553,27 +586,15 @@ class ULID < Object
   # ```
   def randomness: -> String
 
-  # Intentionally avoiding to use `Record type` ref: https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/docs/syntax.md#record-type
-  # Because the returning values are not fixed.
-  def patterns: -> Hash[Symbol, Regexp | String]
-  def octets: -> full_octets
-  def timestamp_octets: -> timestamp_octets
-  def randomness_octets: -> randomness_octets
-
-  # ```ruby
-  # # Currently experimental feature, so needed to load the extension.
-  # require 'ulid/uuid'
+  # Returns 6 + 10 octets(bytes) represented with Array[Integer]
   #
-  # # 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"
+  # ```ruby
+  # ulid = ULID.parse('01F4A5Y1YAQCYAYCTC7GRMJ9AA')
+  # ulid.octets #=> [1, 121, 20, 95, 7, 202, 187, 60, 175, 51, 76, 60, 49, 73, 37, 74]
   # ```
-  #
-  # See also [Why this is experimental?](https://github.com/kachick/ruby-ulid/issues/76)
-  def to_uuidv4: -> String
+  def octets: -> octets
 
-  # Returns next(successor) ULID.
+  # 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
@@ -598,7 +619,6 @@ class ULID < Object
   #
   # See also [ULID#succ](https://kachick.github.io/ruby-ulid/ULID.html#succ-instance_method)
   def pred: -> ULID?
-  def freeze: -> self
 
   def marshal_dump: -> Integer
 
@@ -607,16 +627,45 @@ class ULID < Object
   # Returns `self`
   def to_ulid: -> self
 
-  # Returns `self`. Not a new instance.
-  def dup: -> self
+  # Generate a UUID-like string that does not set the version and variants field.\
+  # It means wrong in UUIDv4 spec, but reversible
+  #
+  # ```ruby
+  # ulid = ULID.parse('01GTXYCWNDKRYH14DBZ77TRSD7')
+  # ulid.to_uuidish #-> '0186bbe6-72ad-9e3d-1091-abf9cfac65a7'
+  # ULID.from_uuidish(ulid.to_uuidish) #=> ULID(2023-03-07 11:48:07.469 UTC: 01GTXYCWNDKRYH14DBZ77TRSD7)
+  # ```
+  #
+  # See also [ULID.from_uuidish], [ULID#to_uuidv4], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
+  def to_uuidish: -> String
 
-  # Same API as [Object#clone](https://github.com/ruby/rbs/blob/4fb4c33b2325d1a73d79ff7aaeb49f21cec1e0e5/core/object.rbs#L79)
-  # But actually returns `self`. Not a new instance.
-  def clone: (?freeze: bool) -> self
+  # Generate a UUIDv4-like string that sets the version and variants field.\
+  # It may conform to the UUID specification, but it is irreversible with the source ULID and may conflict with some other ULIDs.\
+  # You can specify `force` keyword argument to turn off the irreversible check
+  #
+  # ```ruby
+  # uuid = '0983d0a2-ff15-4d83-8f37-7dd945b5aa39'
+  # ulid = ULID.from_uuidv4(uuid)
+  # ulid.to_uuidv4 #=> 0983d0a2-ff15-4d83-8f37-7dd945b5aa39
+  # ```
+  #
+  # ```ruby
+  # ulid = ULID.from_uuidish('0186bbe6-72ad-9e3d-1091-abf9cfac65a7')
+  # ulid.to_uuidv4 #=> ULID::IrreversibleUUIDError
+  # ulid.to_uuidv4(force: true) #=> '0186bbe6-72ad-4e3d-9091-abf9cfac65a7'
+  # ```
+  #
+  # See also [ULID.from_uuidv4], [ULID#to_uuidish], [ulid/spec#64](https://github.com/ulid/spec/issues/64)
+  def to_uuidv4: (?force: boolish) -> String
+
+  # Returns same ID with different Ruby object.
+  def dup: -> ULID
+
+  # Returns same ID with different Ruby object.::Array::_Pattern\
+  # `freeze` keyarg is just provided for standardized API with `Object#clone`, however it accepts only `true`.
+  def clone: (?freeze: true) -> ULID
 
   private
 
   def initialize: (milliseconds: milliseconds, entropy: Integer, integer: Integer, encoded: String) -> void
-
-  def cache_all_instance_variables: -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-ulid
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Kenichi Kamiya
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-05 00:00:00.000000000 Z
+date: 2023-03-08 00:00:00.000000000 Z
 dependencies: []
 description: "    generator, optional monotonicity, parser and tools for ULID (RBS
   included)\n"
@@ -38,7 +38,7 @@ metadata:
   source_code_uri: https://github.com/kachick/ruby-ulid
   bug_tracker_uri: https://github.com/kachick/ruby-ulid/issues
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -46,15 +46,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.2
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: ULID manipulation library
 test_files: []