rbs 2.0.0 → 2.1.0

data/core/marshal.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=marshal.c -->
 # The marshaling library converts collections of Ruby objects into a byte
 # stream, allowing them to be stored outside the currently active script. This
 # data may subsequently be read and the original objects reconstituted.
@@ -107,6 +108,10 @@
 # which is Marshal.loaded in _load for complex objects.
 #
 module Marshal
+  # <!--
+  #   rdoc-file=marshal.c
+  #   - dump( obj [, anIO] , limit=-1 ) -> anIO
+  # -->
   # Serializes obj and all descendant objects. If anIO is specified, the
   # serialized data will be written to it, otherwise the data will be returned as
   # a String. If limit is specified, the traversal of subobjects will be limited
@@ -139,6 +144,11 @@ module Marshal
   def self.dump: (untyped obj, untyped port, ?Integer limit) -> untyped
                | (untyped obj, ?Integer limit) -> String
 
+  # <!--
+  #   rdoc-file=marshal.rb
+  #   - load(source, proc = nil, freeze: false) -> obj
+  #   - restore(source, proc = nil, freeze: false) -> obj
+  # -->
   # Returns the result of converting the serialized data in source into a Ruby
   # object (possibly with associated subordinate objects). source may be either an
   # instance of IO or an object that responds to to_str. If proc is specified,
@@ -147,16 +157,41 @@ module Marshal
   # Never pass untrusted data (including user supplied input) to this method.
   # Please see the overview for further details.
   #
-  def self.load: (String | untyped port) -> untyped
-               | [A] (String | untyped port, ^(untyped) -> A) -> A
+  # If the `freeze: true` argument is passed, deserialized object would be deeply
+  # frozen. Note that it may lead to more efficient memory usage due to frozen
+  # strings deduplication:
+  #
+  #     serialized = Marshal.dump(['value1', 'value2', 'value1', 'value2'])
+  #
+  #     deserialized = Marshal.load(serialized)
+  #     deserialized.map(&:frozen?)
+  #     # => [false, false, false, false]
+  #     deserialized.map(&:object_id)
+  #     # => [1023900, 1023920, 1023940, 1023960] -- 4 different objects
+  #
+  #     deserialized = Marshal.load(serialized, freeze: true)
+  #     deserialized.map(&:frozen?)
+  #     # => [true, true, true, true]
+  #     deserialized.map(&:object_id)
+  #     # => [1039360, 1039380, 1039360, 1039380] -- only 2 different objects, object_ids repeating
+  #
+  def self.load: (String | untyped port, ?freeze: boolish) -> untyped
+               | [A] (String | untyped port, ^(untyped) -> A, ?freeze: boolish) -> A
 
+  # <!--
+  #   rdoc-file=marshal.rb
+  #   - restore(source, proc = nil, freeze: false)
+  # -->
+  #
   alias self.restore self.load
 end
 
+# <!-- rdoc-file=marshal.c -->
 # major version
 #
 Marshal::MAJOR_VERSION: Integer
 
+# <!-- rdoc-file=marshal.c -->
 # minor version
 #
 Marshal::MINOR_VERSION: Integer

data/core/match_data.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=re.c -->
 # MatchData encapsulates the result of matching a Regexp against string. It is
 # returned by Regexp#match and String#match, and also stored in a global
 # variable returned by Regexp.last_match.
@@ -34,11 +35,11 @@
 # global variables:
 #
 # *   `$~` is Regexp.last_match;
-# *   `$&` is [Regexp.last_match](0);
-# *   `$1`, `$2`, and so on are [Regexp.last_match](i) (captures by number);
+# *   `$&` is Regexp.last_match`[ 0 ]`;
+# *   `$1`, `$2`, and so on are Regexp.last_match`[ i ]` (captures by number);
 # *   `$`` is Regexp.last_match`.pre_match`;
 # *   `$'` is Regexp.last_match`.post_match`;
-# *   `$+` is [Regexp.last_match](-1) (the last capture).
+# *   `$+` is Regexp.last_match`[ -1 ]` (the last capture).
 #
 #
 # See also "Special global variables" section in Regexp documentation.
@@ -46,11 +47,19 @@
 class MatchData
   public
 
+  # <!-- rdoc-file=re.c -->
   # Equality---Two matchdata are equal if their target strings, patterns, and
   # matched positions are identical.
   #
   def ==: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch[i]               -> str or nil
+  #   - mtch[start, length]   -> array
+  #   - mtch[range]           -> array
+  #   - mtch[name]            -> str or nil
+  # -->
   # Match Reference -- MatchData acts as an array, and may be accessed using the
   # normal array indexing techniques.  `mtch[0]` is equivalent to the special
   # variable `$&`, and returns the entire matched string.  `mtch[1]`, `mtch[2]`,
@@ -74,6 +83,10 @@ class MatchData
         | (::Range[Integer] range) -> ::Array[String?]
         | (String | Symbol name) -> String?
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.begin(n)   -> integer
+  # -->
   # Returns the offset of the start of the *n*th element of the match array in the
   # string. *n* can be a string or symbol to reference a named capture.
   #
@@ -87,6 +100,10 @@ class MatchData
   #
   def begin: (Integer | String | Symbol n_or_name) -> Integer?
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.captures   -> array
+  # -->
   # Returns the array of captures; equivalent to `mtch.to_a[1..-1]`.
   #
   #     f1,f2,f3,f4 = /(.)(.)(\d+)(\d)/.match("THX1138.").captures
@@ -97,6 +114,10 @@ class MatchData
   #
   def captures: () -> ::Array[String?]
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.end(n)   -> integer
+  # -->
   # Returns the offset of the character immediately following the end of the *n*th
   # element of the match array in the string. *n* can be a string or symbol to
   # reference a named capture.
@@ -109,13 +130,22 @@ class MatchData
   #     p m.end(:foo)    #=> 1
   #     p m.end(:bar)    #=> 3
   #
-  def `end`: (Integer | String | Symbol n_or_name) -> Integer?
+  def end: (Integer | String | Symbol n_or_name) -> Integer?
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch == mtch2   -> true or false
+  #   - mtch.eql?(mtch2)   -> true or false
+  # -->
   # Equality---Two matchdata are equal if their target strings, patterns, and
   # matched positions are identical.
   #
   def eql?: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.hash   -> integer
+  # -->
   # Produce a hash based on the target string, regexp and matched positions of
   # this matchdata.
   #
@@ -123,6 +153,10 @@ class MatchData
   #
   def hash: () -> Integer
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.inspect   -> str
+  # -->
   # Returns a printable version of *mtch*.
   #
   #     puts /.$/.match("foo").inspect
@@ -139,6 +173,7 @@ class MatchData
   #
   def inspect: () -> String
 
+  # <!-- rdoc-file=re.c -->
   # Returns the number of elements in the match array.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
@@ -147,6 +182,10 @@ class MatchData
   #
   def length: () -> Integer
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.named_captures -> hash
+  # -->
   # Returns a Hash using named capture.
   #
   # A key of the hash is a name of the named captures. A value of the hash is a
@@ -166,8 +205,12 @@ class MatchData
   #
   def named_captures: () -> ::Hash[String, String?]
 
-  # Returns a list of names of captures as an array of strings. It is same as
-  # mtch.regexp.names.
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.names   -> [name1, name2, ...]
+  # -->
+  # Returns a list of names of captures as an array of strings. This is the same
+  # as mtch.regexp.names.
   #
   #     /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").names
   #     #=> ["foo", "bar", "baz"]
@@ -177,6 +220,46 @@ class MatchData
   #
   def names: () -> ::Array[String]
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.match(n)   -> string or nil
+  # -->
+  # Returns the captured substring corresponding to the argument. *n* can be a
+  # string or symbol to reference a named capture.
+  #
+  #     m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+  #     m.match(0)       #=> "HX1138"
+  #     m.match(4)       #=> "8"
+  #     m.match(5)       #=> nil
+  #
+  #     m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+  #     m.match(:foo)    #=> "h"
+  #     m.match(:bar)    #=> "ge"
+  #
+  def match: (int | String | Symbol) -> String?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.match_length(n)   -> array
+  # -->
+  # Returns the length of the captured substring corresponding to the argument.
+  # *n* can be a string or symbol to reference a named capture.
+  #
+  #     m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
+  #     m.match_length(0)       #=> 6
+  #     m.match_length(4)       #=> 1
+  #     m.match_length(5)       #=> nil
+  #
+  #     m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
+  #     m.match_length(:foo)    #=> 1
+  #     m.match_length(:bar)    #=> 2
+  #
+  def match_length: (int | String | Symbol) -> Integer?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.offset(n)   -> array
+  # -->
   # Returns a two-element array containing the beginning and ending offsets of the
   # *n*th match. *n* can be a string or symbol to reference a named capture.
   #
@@ -190,6 +273,10 @@ class MatchData
   #
   def offset: (Integer | Symbol | String n_or_name) -> ([ Integer, Integer ] | [ nil, nil ])
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.post_match   -> str
+  # -->
   # Returns the portion of the original string after the current match. Equivalent
   # to the special variable `$'`.
   #
@@ -198,6 +285,10 @@ class MatchData
   #
   def post_match: () -> String
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.pre_match   -> str
+  # -->
   # Returns the portion of the original string before the current match.
   # Equivalent to the special variable `$``.
   #
@@ -206,6 +297,10 @@ class MatchData
   #
   def pre_match: () -> String
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.regexp   -> regexp
+  # -->
   # Returns the regexp.
   #
   #     m = /a.*b/.match("abc")
@@ -213,6 +308,11 @@ class MatchData
   #
   def regexp: () -> Regexp
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.length   -> integer
+  #   - mtch.size     -> integer
+  # -->
   # Returns the number of elements in the match array.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
@@ -221,6 +321,10 @@ class MatchData
   #
   def size: () -> Integer
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.string   -> str
+  # -->
   # Returns a frozen copy of the string passed in to `match`.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
@@ -228,6 +332,10 @@ class MatchData
   #
   def string: () -> String
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.to_a   -> anArray
+  # -->
   # Returns the array of matches.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
@@ -245,6 +353,10 @@ class MatchData
   #
   def to_a: () -> ::Array[String?]
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.to_s   -> str
+  # -->
   # Returns the entire matched string.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
@@ -252,12 +364,17 @@ class MatchData
   #
   def to_s: () -> String
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - mtch.values_at(index, ...)   -> array
+  # -->
   # Uses each *index* to access the matching values, returning an array of the
   # corresponding matches.
   #
   #     m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
   #     m.to_a               #=> ["HX1138", "H", "X", "113", "8"]
   #     m.values_at(0, 2, -2)   #=> ["HX1138", "X", "113"]
+  #     m.values_at(1..2, -1)   #=> ["H", "X", "8"]
   #
   #     m = /(?<a>\d+) *(?<op>[+\-*\/]) *(?<b>\d+)/.match("1 + 2")
   #     m.to_a               #=> ["1 + 2", "1", "+", "2"]

data/core/math.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=math.c -->
 # The Math module contains module functions for basic trigonometric and
 # transcendental functions. See class Float for a list of constants that define
 # Ruby's floating point accuracy.
@@ -5,6 +6,10 @@
 # Domains and codomains are given only for real (not complex) numbers.
 #
 module Math
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.acos(x)    -> Float
+  # -->
   # Computes the arc cosine of `x`. Returns 0..PI.
   #
   # Domain: [-1, 1]
@@ -15,6 +20,10 @@ module Math
   #
   def self.acos: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.acosh(x)    -> Float
+  # -->
   # Computes the inverse hyperbolic cosine of `x`.
   #
   # Domain: [1, INFINITY)
@@ -25,6 +34,10 @@ module Math
   #
   def self.acosh: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.asin(x)    -> Float
+  # -->
   # Computes the arc sine of `x`. Returns -PI/2..PI/2.
   #
   # Domain: [-1, -1]
@@ -35,6 +48,10 @@ module Math
   #
   def self.asin: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.asinh(x)    -> Float
+  # -->
   # Computes the inverse hyperbolic sine of `x`.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -45,6 +62,10 @@ module Math
   #
   def self.asinh: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.atan(x)    -> Float
+  # -->
   # Computes the arc tangent of `x`. Returns -PI/2..PI/2.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -55,6 +76,10 @@ module Math
   #
   def self.atan: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.atan2(y, x)  -> Float
+  # -->
   # Computes the arc tangent given `y` and `x`. Returns a Float in the range
   # -PI..PI. Return value is a angle in radians between the positive x-axis of
   # cartesian plane and the point given by the coordinates (`x`, `y`) on it.
@@ -80,6 +105,10 @@ module Math
   #
   def self.atan2: (Numeric y, Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.atanh(x)    -> Float
+  # -->
   # Computes the inverse hyperbolic tangent of `x`.
   #
   # Domain: (-1, 1)
@@ -90,6 +119,10 @@ module Math
   #
   def self.atanh: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.cbrt(x)    -> Float
+  # -->
   # Returns the cube root of `x`.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -121,6 +154,10 @@ module Math
   #
   def self.cbrt: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.cos(x)    -> Float
+  # -->
   # Computes the cosine of `x` (expressed in radians). Returns a Float in the
   # range -1.0..1.0.
   #
@@ -132,6 +169,10 @@ module Math
   #
   def self.cos: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.cosh(x)    -> Float
+  # -->
   # Computes the hyperbolic cosine of `x` (expressed in radians).
   #
   # Domain: (-INFINITY, INFINITY)
@@ -142,6 +183,10 @@ module Math
   #
   def self.cosh: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.erf(x)  -> Float
+  # -->
   # Calculates the error function of `x`.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -152,6 +197,10 @@ module Math
   #
   def self.erf: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.erfc(x)  -> Float
+  # -->
   # Calculates the complementary error function of x.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -162,6 +211,10 @@ module Math
   #
   def self.erfc: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.exp(x)    -> Float
+  # -->
   # Returns e**x.
   #
   # Domain: (-INFINITY, INFINITY)
@@ -174,6 +227,10 @@ module Math
   #
   def self.exp: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.frexp(x)    -> [fraction, exponent]
+  # -->
   # Returns a two-element array containing the normalized fraction (a Float) and
   # exponent (an Integer) of `x`.
   #
@@ -182,10 +239,14 @@ module Math
   #
   def self.frexp: (Numeric x) -> [ Float, Integer ]
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.gamma(x)  -> Float
+  # -->
   # Calculates the gamma function of x.
   #
-  # Note that gamma(n) is same as fact(n-1) for integer n > 0. However gamma(n)
-  # returns float and can be an approximation.
+  # Note that gamma(n) is the same as fact(n-1) for integer n > 0. However
+  # gamma(n) returns float and can be an approximation.
   #
   #     def fact(n) (1..n).inject(1) {|r,i| r*i } end
   #     1.upto(26) {|i| p [i, Math.gamma(i), fact(i-1)] }
@@ -218,6 +279,10 @@ module Math
   #
   def self.gamma: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.hypot(x, y)    -> Float
+  # -->
   # Returns sqrt(x**2 + y**2), the hypotenuse of a right-angled triangle with
   # sides `x` and `y`.
   #
@@ -225,6 +290,10 @@ module Math
   #
   def self.hypot: (Numeric x, Numeric y) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.ldexp(fraction, exponent) -> float
+  # -->
   # Returns the value of `fraction`*(2**`exponent`).
   #
   #     fraction, exponent = Math.frexp(1234)
@@ -232,19 +301,45 @@ module Math
   #
   def self.ldexp: (Numeric fraction, Numeric exponent) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.lgamma(x)  -> [float, -1 or 1]
+  # -->
   # Calculates the logarithmic gamma of `x` and the sign of gamma of `x`.
   #
-  # Math.lgamma(x) is same as
+  # Math.lgamma(x) is the same as
   #     [Math.log(Math.gamma(x).abs), Math.gamma(x) < 0 ? -1 : 1]
   #
-  # but avoid overflow by Math.gamma(x) for large x.
+  # but avoids overflow by Math.gamma(x) for large x.
   #
   #     Math.lgamma(0) #=> [Infinity, 1]
   #
   def self.lgamma: (Numeric x) -> [ Float, Integer ]
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.log(x)          -> Float
+  #   - Math.log(x, base)    -> Float
+  # -->
+  # Returns the logarithm of `x`. If additional second argument is given, it will
+  # be the base of logarithm. Otherwise it is `e` (for the natural logarithm).
+  #
+  # Domain: (0, INFINITY)
+  #
+  # Codomain: (-INFINITY, INFINITY)
+  #
+  #     Math.log(0)          #=> -Infinity
+  #     Math.log(1)          #=> 0.0
+  #     Math.log(Math::E)    #=> 1.0
+  #     Math.log(Math::E**3) #=> 3.0
+  #     Math.log(12, 3)      #=> 2.2618595071429146
+  #
   def self.log: (Numeric x, ?Numeric base) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.log10(x)    -> Float
+  # -->
   # Returns the base 10 logarithm of `x`.
   #
   # Domain: (0, INFINITY)
@@ -257,6 +352,10 @@ module Math
   #
   def self.log10: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.log2(x)    -> Float
+  # -->
   # Returns the base 2 logarithm of `x`.
   #
   # Domain: (0, INFINITY)
@@ -270,6 +369,10 @@ module Math
   #
   def self.log2: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.sin(x)    -> Float
+  # -->
   # Computes the sine of `x` (expressed in radians). Returns a Float in the range
   # -1.0..1.0.
   #
@@ -281,6 +384,10 @@ module Math
   #
   def self.sin: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.sinh(x)    -> Float
+  # -->
   # Computes the hyperbolic sine of `x` (expressed in radians).
   #
   # Domain: (-INFINITY, INFINITY)
@@ -291,6 +398,10 @@ module Math
   #
   def self.sinh: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.sqrt(x)    -> Float
+  # -->
   # Returns the non-negative square root of `x`.
   #
   # Domain: [0, INFINITY)
@@ -321,6 +432,10 @@ module Math
   #
   def self.sqrt: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.tan(x)    -> Float
+  # -->
   # Computes the tangent of `x` (expressed in radians).
   #
   # Domain: (-INFINITY, INFINITY)
@@ -331,6 +446,10 @@ module Math
   #
   def self.tan: (Numeric x) -> Float
 
+  # <!--
+  #   rdoc-file=math.c
+  #   - Math.tanh(x)    -> Float
+  # -->
   # Computes the hyperbolic tangent of `x` (expressed in radians).
   #
   # Domain: (-INFINITY, INFINITY)
@@ -342,17 +461,18 @@ module Math
   def self.tanh: (Numeric x) -> Float
 end
 
+# <!-- rdoc-file=math.c -->
 # Definition of the mathematical constant E for Euler's number (e) as a Float
 # number.
 #
-#
 Math::E: Float
 
+# <!-- rdoc-file=math.c -->
 # Definition of the mathematical constant PI as a Float number.
 #
-#
 Math::PI: Float
 
+# <!-- rdoc-file=math.c -->
 # Raised when a mathematical function is evaluated outside of its domain of
 # definition.
 #