rbs 3.4.0 → 3.4.1

data/core/object_space/weak_key_map.rbs

@@ -1,10 +1,62 @@
 %a{annotate:rdoc:skip}
 module ObjectSpace
   # <!-- rdoc-file=weakmap.c -->
-  # An ObjectSpace::WeakKeyMap object holds references to any objects, but objects
-  # uses as keys can be garbage collected.
+  # An ObjectSpace::WeakKeyMap is a key-value map that holds weak references to
+  # its keys, so they can be garbage collected when there is no more references.
   #
-  # Objects used as values can't be garbage collected until the key is.
+  # Unlike ObjectSpace::WeakMap:
+  #
+  # *   references to values are *strong*, so they aren't garbage collected while
+  #     they are in the map;
+  # *   keys are compared by value (using Object#eql?), not by identity;
+  # *   only garbage-collectable objects can be used as keys.
+  #
+  #         map = ObjectSpace::WeakKeyMap.new
+  #         val = Time.new(2023, 12, 7)
+  #         key = "name"
+  #         map[key] = val
+  #
+  #         # Value is fetched by equality: the instance of string "name" is
+  #         # different here, but it is equal to the key
+  #         map["name"] #=> 2023-12-07 00:00:00 +0200
+  #
+  #         val = nil
+  #         GC.start
+  #         # There is no more references to `val`, yet the pair isn't
+  #         # garbage-collected.
+  #         map["name"] #=> 2023-12-07 00:00:00 +0200
+  #
+  #         key = nil
+  #         GC.start
+  #         # There is no more references to `key`, key and value are
+  #         # garbage-collected.
+  #         map["name"] #=> nil
+  #
+  #
+  # (Note that GC.start is used here only for demonstrational purposes and might
+  # not always lead to demonstrated results.)
+  #
+  # The collection is especially useful for implementing caches of lightweight
+  # value objects, so that only one copy of each value representation would be
+  # stored in memory, but the copies that aren't used would be garbage-collected.
+  #
+  #     CACHE = ObjectSpace::WeakKeyMap
+  #
+  #     def make_value(**)
+  #        val = ValueObject.new(**)
+  #        if (existing = @cache.getkey(val))
+  #           # if the object with this value exists, we return it
+  #           existing
+  #        else
+  #           # otherwise, put it in the cache
+  #           @cache[val] = true
+  #           val
+  #        end
+  #     end
+  #
+  # This will result in `make_value` returning the same object for same set of
+  # attributes always, but the values that aren't needed anymore woudn't be
+  # sitting in the cache forever.
   #
   class WeakKeyMap[Key, Value]
     public
@@ -23,7 +75,7 @@ module ObjectSpace
     #   rdoc-file=weakmap.c
     #   - map[key] = value -> value
     # -->
-    # Associates the given `value` with the given `key`; returns `value`.
+    # Associates the given `value` with the given `key`
     #
     # The reference to `key` is weak, so when there is no other reference to `key`
     # it may be garbage collected.
@@ -51,7 +103,8 @@ module ObjectSpace
     # If no block is given and `key` is found, deletes the entry and returns the
     # associated value:
     #     m = ObjectSpace::WeakKeyMap.new
-    #     m["foo"] = 1
+    #     key = "foo" # to hold reference to the key
+    #     m[key] = 1
     #     m.delete("foo") # => 1
     #     m["foo"] # => nil
     #
@@ -60,13 +113,14 @@ module ObjectSpace
     # If a block is given and `key` is found, ignores the block, deletes the entry,
     # and returns the associated value:
     #     m = ObjectSpace::WeakKeyMap.new
-    #     m["foo"] = 2
-    #     h.delete("foo") { |key| raise 'Will never happen'} # => 2
+    #     key = "foo" # to hold reference to the key
+    #     m[key] = 2
+    #     m.delete("foo") { |key| raise 'Will never happen'} # => 2
     #
-    # If a block is given and `key` is not found, calls the block and returns the
-    # block's return value:
+    # If a block is given and `key` is not found, yields the `key` to the block and
+    # returns the block's return value:
     #     m = ObjectSpace::WeakKeyMap.new
-    #     h.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"
+    #     m.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"
     #
     def delete: (Key) -> Value?
               | [T] (Key) { (Key) -> T } -> (Value | T)
@@ -77,6 +131,19 @@ module ObjectSpace
     # -->
     # Returns the existing equal key if it exists, otherwise returns `nil`.
     #
+    # This might be useful for implementing caches, so that only one copy of some
+    # object would be used everywhere in the program:
+    #
+    #     value = {amount: 1, currency: 'USD'}
+    #
+    #     # Now if we put this object in a cache:
+    #     cache = ObjectSpace::WeakKeyMap.new
+    #     cache[value] = true
+    #
+    #     # ...we can always extract from there and use the same object:
+    #     copy = cache.getkey({amount: 1, currency: 'USD'})
+    #     copy.object_id == value.object_id #=> true
+    #
     def getkey: (untyped) -> Key?
 
     # <!--
@@ -93,7 +160,7 @@ module ObjectSpace
 
     # <!--
     #   rdoc-file=weakmap.c
-    #   - hash.key?(key) -> true or false
+    #   - map.key?(key) -> true or false
     # -->
     # Returns `true` if `key` is a key in `self`, otherwise `false`.
     #

data/core/object_space.rbs

@@ -166,6 +166,7 @@ module ObjectSpace
   #   rdoc-file=gc.rb
   #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
+  # Alias of GC.start
   #
   def self.garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 
@@ -183,6 +184,7 @@ module ObjectSpace
   #   rdoc-file=gc.rb
   #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
+  # Alias of GC.start
   #
   def garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 end

data/core/process.rbs

@@ -1788,7 +1788,6 @@ end
 #     stat = $?       # => #<Process::Status: pid 1262862 exit 99>
 #     stat.class      # => Process::Status
 #     stat.to_i       # => 25344
-#     stat >> 8       # => 99
 #     stat.stopped?   # => false
 #     stat.exited?    # => true
 #     stat.exitstatus # => 99
@@ -1798,7 +1797,8 @@ class Process::Status < Object
   #   rdoc-file=process.c
   #   - stat & mask -> integer
   # -->
-  # This method is deprecated; use other attribute methods.
+  # This method is deprecated as #to_i value is system-specific; use predicate
+  # methods like #exited? or #stopped?, or getters like #exitstatus or #stopsig.
   #
   # Returns the logical AND of the value of #to_i with `mask`:
   #
@@ -1828,7 +1828,8 @@ class Process::Status < Object
   #   rdoc-file=process.c
   #   - stat >> places -> integer
   # -->
-  # This method is deprecated; use other predicate methods.
+  # This method is deprecated as #to_i value is system-specific; use predicate
+  # methods like #exited? or #stopped?, or getters like #exitstatus or #stopsig.
   #
   # Returns the value of #to_i, shifted `places` to the right:
   #

data/core/range.rbs

@@ -871,15 +871,16 @@ class Range[out Elem] < Object
   #     (1..2).overlap?(3..4)      # => false
   #     (1...3).overlap?(3..4)     # => false
   #
-  # This method assumes that there is no minimum value because Ruby lacks a
-  # standard method for determining minimum values. This assumption is invalid.
-  # For example, there is no value smaller than `-Float::INFINITY`, making
-  # `(...-Float::INFINITY)` an empty set. Consequently, `(...-Float::INFINITY)`
-  # has no elements in common with itself, yet
-  # `(...-Float::INFINITY).overlap?((...-Float::INFINITY))<tt> returns true due to
-  # this assumption. In general, if <tt>r = (...minimum); r.overlap?(r)` returns
-  # `true`, where `minimum` is a value that no value is smaller than. Such values
-  # include `-Float::INFINITY`, `[]`, `""`, and classes without subclasses.
+  # Note that the method wouldn't make any assumptions about the beginless range
+  # being actually empty, even if its upper bound is the minimum possible value of
+  # its type, so all this would return `true`:
+  #
+  #     (...-Float::INFINITY).overlap?(...-Float::INFINITY) # => true
+  #     (..."").overlap?(..."") # => true
+  #     (...[]).overlap?(...[]) # => true
+  #
+  # Even if those ranges are effectively empty (no number can be smaller than
+  # `-Float::INFINITY`), they are still considered overlapping with themselves.
   #
   # Related: Range#cover?.
   #

data/core/refinement.rbs

@@ -46,15 +46,24 @@ class Refinement < Module
   #   rdoc-file=eval.c
   #   - refined_class    -> class
   # -->
+  # Deprecated; prefer #target.
+  #
   # Return the class refined by the receiver.
   #
   def refined_class: () -> Module
 
   # <!--
   #   rdoc-file=eval.c
-  #   - target    -> class
+  #   - target    -> class_or_module
   # -->
   # Return the class or module refined by the receiver.
   #
+  #     module M
+  #       refine String do
+  #       end
+  #     end
+  #
+  #     M.refinements[0].target # => String
+  #
   def target: () -> Module
 end

data/core/string.rbs

@@ -3163,31 +3163,30 @@ class String
 
   # <!--
   #   rdoc-file=complex.c
-  #   - str.to_c  ->  complex
-  # -->
-  # Returns a complex which denotes the string form.  The parser ignores leading
-  # whitespaces and trailing garbage.  Any digit sequences can be separated by an
-  # underscore.  Returns zero for null or garbage string.
-  #
-  #     '9'.to_c           #=> (9+0i)
-  #     '2.5'.to_c         #=> (2.5+0i)
-  #     '2.5/1'.to_c       #=> ((5/2)+0i)
-  #     '-3/2'.to_c        #=> ((-3/2)+0i)
-  #     '-i'.to_c          #=> (0-1i)
-  #     '45i'.to_c         #=> (0+45i)
-  #     '3-4i'.to_c        #=> (3-4i)
-  #     '-4e2-4e-2i'.to_c  #=> (-400.0-0.04i)
-  #     '-0.0-0.0i'.to_c   #=> (-0.0-0.0i)
-  #     '1/2+3/4i'.to_c    #=> ((1/2)+(3/4)*i)
-  #     'ruby'.to_c        #=> (0+0i)
-  #
-  # Polar form:
-  #     include Math
-  #     "1.0@0".to_c        #=> (1+0.0i)
-  #     "1.0@#{PI/2}".to_c  #=> (0.0+1i)
-  #     "1.0@#{PI}".to_c    #=> (-1+0.0i)
-  #
-  # See Kernel.Complex.
+  #   - to_c -> complex
+  # -->
+  # Returns `self` interpreted as a Complex object; leading whitespace and
+  # trailing garbage are ignored:
+  #
+  #     '9'.to_c                 # => (9+0i)
+  #     '2.5'.to_c               # => (2.5+0i)
+  #     '2.5/1'.to_c             # => ((5/2)+0i)
+  #     '-3/2'.to_c              # => ((-3/2)+0i)
+  #     '-i'.to_c                # => (0-1i)
+  #     '45i'.to_c               # => (0+45i)
+  #     '3-4i'.to_c              # => (3-4i)
+  #     '-4e2-4e-2i'.to_c        # => (-400.0-0.04i)
+  #     '-0.0-0.0i'.to_c         # => (-0.0-0.0i)
+  #     '1/2+3/4i'.to_c          # => ((1/2)+(3/4)*i)
+  #     '1.0@0'.to_c             # => (1+0.0i)
+  #     "1.0@#{Math::PI/2}".to_c # => (0.0+1i)
+  #     "1.0@#{Math::PI}".to_c   # => (-1+0.0i)
+  #
+  # Returns Complex zero if the string cannot be converted:
+  #
+  #     'ruby'.to_c        # => (0+0i)
+  #
+  # See Kernel#Complex.
   #
   def to_c: () -> Complex
 

data/core/thread.rbs

@@ -1626,8 +1626,8 @@ class Thread::Queue < Object
   #   rdoc-file=thread_sync.c
   #   - freeze
   # -->
-  # Raises an exception:
-  #     Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+  # The queue can't be frozen, so this method raises an exception:
+  #     Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
   #
   def freeze: () -> bot
 
@@ -1711,8 +1711,8 @@ class Thread::SizedQueue < Thread::Queue
   #   rdoc-file=thread_sync.c
   #   - freeze
   # -->
-  # Raises an exception:
-  #     Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
+  # The queue can't be frozen, so this method raises an exception:
+  #     Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
   #
   def freeze: () -> bot
 

data/core/trace_point.rbs

@@ -44,6 +44,8 @@
 # :   return from a C-language routine
 # `:raise`
 # :   raise an exception
+# `:rescue`
+# :   rescue an exception
 # `:b_call`
 # :   event hook at block entry
 # `:b_return`
@@ -205,7 +207,7 @@ class TracePoint < Object
   # -->
   # Return the generated binding object from event.
   #
-  # Note that for `c_call` and `c_return` events, the method will return `nil`,
+  # Note that for `:c_call` and `:c_return` events, the method will return `nil`,
   # since C methods themselves do not have bindings.
   #
   def binding: () -> Binding?
@@ -416,7 +418,8 @@ class TracePoint < Object
   #   rdoc-file=trace_point.rb
   #   - raised_exception()
   # -->
-  # Value from exception raised on the `:raise` event
+  # Value from exception raised on the `:raise` event, or rescued on the `:rescue`
+  # event.
   #
   def raised_exception: () -> untyped
 
@@ -424,7 +427,7 @@ class TracePoint < Object
   #   rdoc-file=trace_point.rb
   #   - return_value()
   # -->
-  # Return value from `:return`, `c_return`, and `b_return` event
+  # Return value from `:return`, `:c_return`, and `:b_return` event
   #
   def return_value: () -> untyped
 
@@ -435,7 +438,7 @@ class TracePoint < Object
   # Return the trace object during event
   #
   # Same as the following, except it returns the correct object (the method
-  # receiver) for `c_call` and `c_return` events:
+  # receiver) for `:c_call` and `:c_return` events:
   #
   #     trace.binding.eval('self')
   #

data/lib/rbs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RBS
-  VERSION = "3.4.0"
+  VERSION = "3.4.1"
 end

data/stdlib/bigdecimal/0/big_decimal.rbs

@@ -1711,61 +1711,60 @@ class Complex
 
   # <!--
   #   rdoc-file=complex.c
-  #   - cmp / numeric     ->  complex
-  #   - cmp.quo(numeric)  ->  complex
+  #   - complex / numeric -> new_complex
   # -->
-  # Performs division.
+  # Returns the quotient of `self` and `numeric`:
   #
-  #     Complex(2, 3)  / Complex(2, 3)   #=> ((1/1)+(0/1)*i)
-  #     Complex(900)   / Complex(1)      #=> ((900/1)+(0/1)*i)
-  #     Complex(-2, 9) / Complex(-9, 2)  #=> ((36/85)-(77/85)*i)
-  #     Complex(9, 8)  / 4               #=> ((9/4)+(2/1)*i)
-  #     Complex(20, 9) / 9.8             #=> (2.0408163265306123+0.9183673469387754i)
+  #     Complex(2, 3)  / Complex(2, 3)  # => ((1/1)+(0/1)*i)
+  #     Complex(900)   / Complex(1)     # => ((900/1)+(0/1)*i)
+  #     Complex(-2, 9) / Complex(-9, 2) # => ((36/85)-(77/85)*i)
+  #     Complex(9, 8)  / 4              # => ((9/4)+(2/1)*i)
+  #     Complex(20, 9) / 9.8            # => (2.0408163265306123+0.9183673469387754i)
   #
   def /: (BigDecimal) -> Complex
     | ...
 
   # <!--
   #   rdoc-file=complex.c
-  #   - cmp * numeric  ->  complex
+  #   - complex * numeric -> new_complex
   # -->
-  # Performs multiplication.
+  # Returns the product of `self` and `numeric`:
   #
-  #     Complex(2, 3)  * Complex(2, 3)   #=> (-5+12i)
-  #     Complex(900)   * Complex(1)      #=> (900+0i)
-  #     Complex(-2, 9) * Complex(-9, 2)  #=> (0-85i)
-  #     Complex(9, 8)  * 4               #=> (36+32i)
-  #     Complex(20, 9) * 9.8             #=> (196.0+88.2i)
+  #     Complex(2, 3)  * Complex(2, 3)  # => (-5+12i)
+  #     Complex(900)   * Complex(1)     # => (900+0i)
+  #     Complex(-2, 9) * Complex(-9, 2) # => (0-85i)
+  #     Complex(9, 8)  * 4              # => (36+32i)
+  #     Complex(20, 9) * 9.8            # => (196.0+88.2i)
   #
   def *: (BigDecimal) -> Complex
     | ...
 
   # <!--
   #   rdoc-file=complex.c
-  #   - cmp + numeric  ->  complex
+  #   - complex + numeric -> new_complex
   # -->
-  # Performs addition.
+  # Returns the sum of `self` and `numeric`:
   #
-  #     Complex(2, 3)  + Complex(2, 3)   #=> (4+6i)
-  #     Complex(900)   + Complex(1)      #=> (901+0i)
-  #     Complex(-2, 9) + Complex(-9, 2)  #=> (-11+11i)
-  #     Complex(9, 8)  + 4               #=> (13+8i)
-  #     Complex(20, 9) + 9.8             #=> (29.8+9i)
+  #     Complex(2, 3)  + Complex(2, 3)  # => (4+6i)
+  #     Complex(900)   + Complex(1)     # => (901+0i)
+  #     Complex(-2, 9) + Complex(-9, 2) # => (-11+11i)
+  #     Complex(9, 8)  + 4              # => (13+8i)
+  #     Complex(20, 9) + 9.8            # => (29.8+9i)
   #
   def +: (BigDecimal) -> Complex
     | ...
 
   # <!--
   #   rdoc-file=complex.c
-  #   - cmp - numeric  ->  complex
+  #   - complex - numeric -> new_complex
   # -->
-  # Performs subtraction.
+  # Returns the difference of `self` and `numeric`:
   #
-  #     Complex(2, 3)  - Complex(2, 3)   #=> (0+0i)
-  #     Complex(900)   - Complex(1)      #=> (899+0i)
-  #     Complex(-2, 9) - Complex(-9, 2)  #=> (7+7i)
-  #     Complex(9, 8)  - 4               #=> (5+8i)
-  #     Complex(20, 9) - 9.8             #=> (10.2+9i)
+  #     Complex(2, 3)  - Complex(2, 3)  # => (0+0i)
+  #     Complex(900)   - Complex(1)     # => (899+0i)
+  #     Complex(-2, 9) - Complex(-9, 2) # => (7+7i)
+  #     Complex(9, 8)  - 4              # => (5+8i)
+  #     Complex(20, 9) - 9.8            # => (10.2+9i)
   #
   def -: (BigDecimal) -> Complex
     | ...

data/stdlib/pty/0/pty.rbs

@@ -74,13 +74,7 @@ module PTY
   #
   def self.check: (Integer pid, ?boolish raise) -> Process::Status?
 
-  # <!--
-  #   rdoc-file=ext/pty/pty.c
-  #   - PTY.spawn([env,] command_line)  { |r, w, pid| ... }
-  #   - PTY.spawn([env,] command_line)  => [r, w, pid]
-  #   - PTY.spawn([env,] command, arguments, ...)  { |r, w, pid| ... }
-  #   - PTY.spawn([env,] command, arguments, ...)  => [r, w, pid]
-  # -->
+  # <!-- rdoc-file=ext/pty/pty.c -->
   # Spawns the specified command on a newly allocated pty. You can also use the
   # alias ::getpty.
   #

data/stdlib/socket/0/addrinfo.rbs

@@ -1,3 +1,7 @@
+# <!-- rdoc-file=ext/socket/raddrinfo.c -->
+# The Addrinfo class maps `struct addrinfo` to ruby.  This structure identifies
+# an Internet host and a service.
+#
 class Addrinfo
   # <!--
   #   rdoc-file=ext/socket/lib/socket.rb

data/stdlib/socket/0/basic_socket.rbs

@@ -293,8 +293,10 @@ class BasicSocket < IO
   # is set for the underlying file descriptor. *flags* is zero or more of the
   # `MSG_` options. The result, *mesg*, is the data received.
   #
-  # When recvfrom(2) returns 0, Socket#recv_nonblock returns an empty string as
-  # data. The meaning depends on the socket: EOF on TCP, empty packet on UDP, etc.
+  # When recvfrom(2) returns 0, Socket#recv_nonblock returns nil. In most cases it
+  # means the connection was closed, but for UDP connections it may mean an empty
+  # packet was received, as the underlying API makes it impossible to distinguish
+  # these two cases.
   #
   # ### Parameters
   # *   `maxlen` - the number of bytes to receive from the socket

data/stdlib/socket/0/socket.rbs

@@ -1289,9 +1289,10 @@ class Socket < BasicSocket
   # received. The second element, *sender_addrinfo*, contains protocol-specific
   # address information of the sender.
   #
-  # When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns an empty string
-  # as data. The meaning depends on the socket: EOF on TCP, empty packet on UDP,
-  # etc.
+  # When recvfrom(2) returns 0, Socket#recv_nonblock returns nil. In most cases it
+  # means the connection was closed, but for UDP connections it may mean an empty
+  # packet was received, as the underlying API makes it impossible to distinguish
+  # these two cases.
   #
   # ### Parameters
   # *   `maxlen` - the maximum number of bytes to receive from the socket

data/stdlib/socket/0/udp_socket.rbs

@@ -44,8 +44,10 @@ class UDPSocket < IPSocket
   # received. The second element, *sender_inet_addr*, is an array to represent the
   # sender address.
   #
-  # When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns an empty string
-  # as data. It means an empty packet.
+  # When recvfrom(2) returns 0, Socket#recv_nonblock returns nil. In most cases it
+  # means the connection was closed, but it may also mean an empty packet was
+  # received, as the underlying API makes it impossible to distinguish these two
+  # cases.
   #
   # ### Parameters
   # *   `maxlen` - the number of bytes to receive from the socket

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rbs
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.4.1
 platform: ruby
 authors:
 - Soutaro Matsumoto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-21 00:00:00.000000000 Z
+date: 2023-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abbrev
@@ -529,7 +529,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.0.dev
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Type signature for Ruby.