rbs 3.3.1 → 3.4.0.pre.1

data/core/float.rbs

@@ -6,8 +6,8 @@
 # should know its esoteric system. See following:
 #
 # *   https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html
-# *   https://github.com/rdp/ruby_tutorials_core/wiki/Ruby-Talk-FAQ#floats_impre
-#     cise
+# *   https://github.com/rdp/ruby_tutorials_core/wiki/Ruby-Talk-FAQ#-why-are-rub
+#     ys-floats-imprecise
 # *   https://en.wikipedia.org/wiki/Floating_point#Accuracy_problems
 #
 #
@@ -109,8 +109,6 @@ class Float < Numeric
   #     10.0 % 4.0            # => 2.0
   #     10.0 % Rational(4, 1) # => 2.0
   #
-  # Float#modulo is an alias for Float#%.
-  #
   def %: (Integer) -> Float
        | (Float) -> Float
        | (Rational) -> Float
@@ -181,9 +179,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -float  ->  float
+  #   - -float -> float
   # -->
-  # Returns `float`, negated.
+  # Returns `self`, negated.
   #
   def -@: () -> Float
 
@@ -326,16 +324,13 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.abs        ->  float
-  #   - float.magnitude  ->  float
+  #   - float.abs ->  float
   # -->
-  # Returns the absolute value of `float`.
-  #
-  #     (-34.56).abs   #=> 34.56
-  #     -34.56.abs     #=> 34.56
-  #     34.56.abs      #=> 34.56
+  # Returns the absolute value of `self`:
   #
-  # Float#magnitude is an alias for Float#abs.
+  #     (-34.56).abs # => 34.56
+  #     -34.56.abs   # => 34.56
+  #     34.56.abs    # => 34.56
   #
   def abs: () -> Float
 
@@ -481,8 +476,6 @@ class Float < Numeric
   #     f.quo(Rational(2, 1)) # => 1.57
   #     f.quo(Complex(2, 0))  # => (1.57+0.0i)
   #
-  # Float#fdiv is an alias for Float#quo.
-  #
   def fdiv: (Complex) -> Complex
           | (Numeric) -> Float
 
@@ -630,8 +623,6 @@ class Float < Numeric
   #     10.0 % 4.0            # => 2.0
   #     10.0 % Rational(4, 1) # => 2.0
   #
-  # Float#modulo is an alias for Float#%.
-  #
   def modulo: (Numeric) -> Float
 
   # <!--
@@ -649,9 +640,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.negative?  ->  true or false
+  #   - negative? -> true or false
   # -->
-  # Returns `true` if `float` is less than 0.
+  # Returns `true` if `self` is less than 0, `false` otherwise.
   #
   def negative?: () -> bool
 
@@ -725,9 +716,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.positive?  ->  true or false
+  #   - positive? -> true or false
   # -->
-  # Returns `true` if `float` is greater than 0.
+  # Returns `true` if `self` is greater than 0, `false` otherwise.
   #
   def positive?: () -> bool
 
@@ -779,8 +770,6 @@ class Float < Numeric
   #     f.quo(Rational(2, 1)) # => 1.57
   #     f.quo(Complex(2, 0))  # => (1.57+0.0i)
   #
-  # Float#fdiv is an alias for Float#quo.
-  #
   def quo: (Complex) -> Complex
          | (Numeric) -> Float
 
@@ -875,9 +864,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.to_f  ->  self
+  #   - to_f -> self
   # -->
-  # Since `float` is already a Float, returns `self`.
+  # Returns `self` (which is already a Float).
   #
   def to_f: () -> Float
 
@@ -895,8 +884,6 @@ class Float < Numeric
   #
   #     (0.3 / 0.1).to_i  # => 2 (!)
   #
-  # Float#to_int is an alias for Float#to_i.
-  #
   def to_i: () -> Integer
 
   # <!-- rdoc-file=numeric.c -->
@@ -910,8 +897,6 @@ class Float < Numeric
   #
   #     (0.3 / 0.1).to_i  # => 2 (!)
   #
-  # Float#to_int is an alias for Float#to_i.
-  #
   alias to_int to_i
 
   # <!--
@@ -994,9 +979,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.zero?  ->  true or false
+  #   - zero? -> true or false
   # -->
-  # Returns `true` if `float` is 0.0.
+  # Returns `true` if `self` is 0.0, `false` otherwise.
   #
   def zero?: () -> bool
 end

data/core/gc.rbs

@@ -44,21 +44,27 @@ module GC
 
   # <!--
   #   rdoc-file=gc.rb
-  #   - GC.start                     -> nil
-  #   - ObjectSpace.garbage_collect  -> nil
-  #   - include GC; garbage_collect  -> nil
-  #   - GC.start(full_mark: true, immediate_sweep: true)           -> nil
-  #   - ObjectSpace.garbage_collect(full_mark: true, immediate_sweep: true) -> nil
-  #   - include GC; garbage_collect(full_mark: true, immediate_sweep: true) -> nil
+  #   - start(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
   # Initiates garbage collection, even if manually disabled.
   #
-  # This method is defined with keyword arguments that default to true:
+  # The `full_mark` keyword argument determines whether or not to perform a major
+  # garbage collection cycle. When set to `true`, a major garbage collection cycle
+  # is ran, meaning all objects are marked. When set to `false`, a minor garbage
+  # collection cycle is ran, meaning only young objects are marked.
   #
-  #     def GC.start(full_mark: true, immediate_sweep: true); end
+  # The `immediate_mark` keyword argument determines whether or not to perform
+  # incremental marking. When set to `true`, marking is completed during the call
+  # to this method. When set to `false`, marking is performed in steps that is
+  # interleaved with future Ruby code execution, so marking might not be completed
+  # during this method call. Note that if `full_mark` is `false` then marking will
+  # always be immediate, regardless of the value of `immediate_mark`.
   #
-  # Use full_mark: false to perform a minor GC. Use immediate_sweep: false to
-  # defer sweeping (use lazy sweep).
+  # The `immedate_sweep` keyword argument determines whether or not to defer
+  # sweeping (using lazy sweep). When set to `true`, sweeping is performed in
+  # steps that is interleaved with future Ruby code execution, so sweeping might
+  # not be completed during this method call. When set to `false`, sweeping is
+  # completed during the call to this method.
   #
   # Note: These keyword arguments are implementation and version dependent. They
   # are not guaranteed to be future-compatible, and may be ignored if the
@@ -258,7 +264,7 @@ module GC
 end
 
 # <!-- rdoc-file=gc.c -->
-# internal constants
+# Internal constants in the garbage collector.
 #
 GC::INTERNAL_CONSTANTS: Hash[Symbol, Integer]
 

data/core/hash.rbs

@@ -247,7 +247,7 @@
 #       alias eql? ==
 #
 #       def hash
-#         @author.hash ^ @title.hash # XOR
+#         [self.class, @author, @title].hash
 #       end
 #     end
 #
@@ -345,6 +345,10 @@
 # Note that setting the default proc will clear the default value and vice
 # versa.
 #
+# Be aware that a default proc that modifies the hash is not thread-safe in the
+# sense that multiple threads can call into the default proc concurrently for
+# the same key.
+#
 # ### What's Here
 #
 # First, what's elsewhere. Class Hash:
@@ -412,7 +416,7 @@
 # *   #<=: Returns whether `self` is a subset of a given object.
 # *   #==: Returns whether a given object is equal to `self`.
 # *   #>: Returns whether `self` is a proper superset of a given object
-# *   #>=: Returns whether `self` is a proper superset of a given object.
+# *   #>=: Returns whether `self` is a superset of a given object.
 #
 #
 # #### Methods for Fetching
@@ -499,6 +503,12 @@
 class Hash[unchecked out K, unchecked out V] < Object
   include Enumerable[[ K, V ]]
 
+  interface _Key
+    def hash: () -> Integer
+
+    def eql?: (untyped rhs) -> boolish
+  end
+
   # <!--
   #   rdoc-file=hash.c
   #   - Hash[] -> new_empty_hash
@@ -646,8 +656,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash[key] = value -> value
   #   - hash.store(key, value)
   # -->
-  # Hash#store is an alias for Hash#[]=.
-  #
   # Associates the given `value` with the given `key`; returns `value`.
   #
   # If the given `key` exists, replaces its value with the given `value`; the
@@ -674,6 +682,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   # -->
   # Returns `true` if any element satisfies a given criterion; `false` otherwise.
   #
+  # If `self` has no element, returns `false` and argument or block are not used.
+  #
   # With no argument and no block, returns `true` if `self` is non-empty; `false`
   # if empty.
   #
@@ -690,6 +700,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h.any? {|key, value| value < 3 } # => true
   #     h.any? {|key, value| value > 3 } # => false
   #
+  # Related: Enumerable#any?
+  #
   def any?: () -> bool
           | (untyped pattern) -> bool
           | () { (K, V) -> boolish } -> bool
@@ -922,8 +934,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   def dig: (K, *untyped) -> untyped
 
   # <!-- rdoc-file=hash.c -->
-  # Hash#each is an alias for Hash#each_pair.
-  #
   # Calls the given block with each key-value pair; returns `self`:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h.each_pair {|key, value| puts "#{key}: #{value}"} # => {:foo=>0, :bar=>1, :baz=>2}
@@ -982,8 +992,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.each -> new_enumerator
   #   - hash.each_pair -> new_enumerator
   # -->
-  # Hash#each is an alias for Hash#each_pair.
-  #
   # Calls the given block with each key-value pair; returns `self`:
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h.each_pair {|key, value| puts "#{key}: #{value}"} # => {:foo=>0, :bar=>1, :baz=>2}
@@ -1127,8 +1135,6 @@ class Hash[unchecked out K, unchecked out V] < Object
                   | [X] (*K) { (K) -> X } -> ::Array[V | X]
 
   # <!-- rdoc-file=hash.c -->
-  # Hash#filter is an alias for Hash#select.
-  #
   # Returns a new Hash object whose entries are those for which the block returns
   # a truthy value:
   #     h = {foo: 0, bar: 1, baz: 2}
@@ -1143,8 +1149,6 @@ class Hash[unchecked out K, unchecked out V] < Object
             | () -> ::Enumerator[[ K, V ], ::Hash[K, V]]
 
   # <!-- rdoc-file=hash.c -->
-  # Hash#filter! is an alias for Hash#select!.
-  #
   # Returns `self`, whose entries are those for which the block returns a truthy
   # value:
   #     h = {foo: 0, bar: 1, baz: 2}
@@ -1195,8 +1199,6 @@ class Hash[unchecked out K, unchecked out V] < Object
              | (Integer level) -> Array[untyped]
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   def has_key?: (K arg0) -> bool
@@ -1206,8 +1208,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.has_value?(value) -> true or false
   #   - hash.value?(value) -> true or false
   # -->
-  # Method #value? is an alias for #has_value?.
-  #
   # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   def has_value?: (V arg0) -> bool
@@ -1219,7 +1219,7 @@ class Hash[unchecked out K, unchecked out V] < Object
   # Returns the Integer hash-code for the hash.
   #
   # Two Hash objects have the same hash-code if their content is the same
-  # (regardless or order):
+  # (regardless of order):
   #     h1 = {foo: 0, bar: 1, baz: 2}
   #     h2 = {baz: 2, bar: 1, foo: 0}
   #     h2.hash == h1.hash # => true
@@ -1234,8 +1234,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.key?(key) -> true or false
   #   - hash.member?(key) -> true or false
   # -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias include? has_key?
@@ -1245,11 +1243,10 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.inspect -> new_string
   # -->
   # Returns a new String containing the hash entries:
+  #
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
   #
-  # Hash#to_s is an alias for Hash#inspect.
-  #
   def inspect: () -> String
 
   # <!--
@@ -1296,13 +1293,11 @@ class Hash[unchecked out K, unchecked out V] < Object
   #     h.key(0) # => :foo
   #     h.key(2) # => :bar
   #
-  # Returns `nil` if so such value is found.
+  # Returns `nil` if no such value is found.
   #
   def key: (V) -> K?
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias key? has_key?
@@ -1319,15 +1314,12 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!-- rdoc-file=hash.c -->
   # Returns the count of entries in `self`:
-  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
-  # Hash#length is an alias for Hash#size.
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   def length: () -> Integer
 
   # <!-- rdoc-file=hash.c -->
-  # Methods #has_key?, #key?, and #member? are aliases for #include?.
-  #
   # Returns `true` if `key` is a key in `self`, otherwise `false`.
   #
   alias member? has_key?
@@ -1394,8 +1386,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #
   # Each argument in `other_hashes` must be a Hash.
   #
-  # Method #update is an alias for #merge!.
-  #
   # With arguments and no block:
   # *   Returns `self`, after the given hashes are merged into it.
   # *   The given hashes are merged left to right.
@@ -1520,8 +1510,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.select {|key, value| ... } -> new_hash
   #   - hash.select -> new_enumerator
   # -->
-  # Hash#filter is an alias for Hash#select.
-  #
   # Returns a new Hash object whose entries are those for which the block returns
   # a truthy value:
   #     h = {foo: 0, bar: 1, baz: 2}
@@ -1539,8 +1527,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.select! {|key, value| ... } -> self or nil
   #   - hash.select! -> new_enumerator
   # -->
-  # Hash#filter! is an alias for Hash#select!.
-  #
   # Returns `self`, whose entries are those for which the block returns a truthy
   # value:
   #     h = {foo: 0, bar: 1, baz: 2}
@@ -1575,9 +1561,8 @@ class Hash[unchecked out K, unchecked out V] < Object
   #   - hash.size -> integer
   # -->
   # Returns the count of entries in `self`:
-  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
-  # Hash#length is an alias for Hash#size.
+  #     {foo: 0, bar: 1, baz: 2}.length # => 3
   #
   alias size length
 
@@ -1594,8 +1579,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   def slice: (*K) -> ::Hash[K, V]
 
   # <!-- rdoc-file=hash.c -->
-  # Hash#store is an alias for Hash#[]=.
-  #
   # Associates the given `value` with the given `key`; returns `value`.
   #
   # If the given `key` exists, replaces its value with the given `value`; the
@@ -1668,11 +1651,10 @@ class Hash[unchecked out K, unchecked out V] < Object
 
   # <!-- rdoc-file=hash.c -->
   # Returns a new String containing the hash entries:
+  #
   #     h = {foo: 0, bar: 1, baz: 2}
   #     h.inspect # => "{:foo=>0, :bar=>1, :baz=>2}"
   #
-  # Hash#to_s is an alias for Hash#inspect.
-  #
   alias to_s inspect
 
   # <!--
@@ -1782,8 +1764,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   #
   # Each argument in `other_hashes` must be a Hash.
   #
-  # Method #update is an alias for #merge!.
-  #
   # With arguments and no block:
   # *   Returns `self`, after the given hashes are merged into it.
   # *   The given hashes are merged left to right.
@@ -1828,8 +1808,6 @@ class Hash[unchecked out K, unchecked out V] < Object
   alias update merge!
 
   # <!-- rdoc-file=hash.c -->
-  # Method #value? is an alias for #has_value?.
-  #
   # Returns `true` if `value` is a value in `self`, otherwise `false`.
   #
   alias value? has_value?