rbs 3.9.5 → 4.0.0

data/core/integer.rbs

@@ -88,7 +88,7 @@
 # *   #downto: Calls the given block with each integer value from `self` down to
 #     the given value.
 # *   #times: Calls the given block `self` times with each integer in
-#     `(0..self-1)`.
+#     <code>(0..self-1)</code>.
 # *   #upto: Calls the given block with each integer value from `self` up to the
 #     given value.
 #
@@ -114,9 +114,9 @@ class Integer < Numeric
   #     Integer.sqrt(4.0)            # => 2
   #     Integer.sqrt(3.14159)        # => 1
   #
-  # This method is equivalent to `Math.sqrt(numeric).floor`, except that the
-  # result of the latter code may differ from the true value due to the limited
-  # precision of floating point arithmetic.
+  # This method is equivalent to <code>Math.sqrt(numeric).floor</code>, except
+  # that the result of the latter code may differ from the true value due to the
+  # limited precision of floating point arithmetic.
   #
   #     Integer.sqrt(10**46)    # => 100000000000000000000000
   #     Math.sqrt(10**46).floor # => 99999999999999991611392
@@ -132,23 +132,24 @@ class Integer < Numeric
   # If `object` is an Integer object, returns `object`.
   #     Integer.try_convert(1) # => 1
   #
-  # Otherwise if `object` responds to `:to_int`, calls `object.to_int` and returns
-  # the result.
+  # Otherwise if `object` responds to <code>:to_int</code>, calls
+  # <code>object.to_int</code> and returns the result.
   #     Integer.try_convert(1.25) # => 1
   #
-  # Returns `nil` if `object` does not respond to `:to_int`
+  # Returns `nil` if `object` does not respond to <code>:to_int</code>
   #     Integer.try_convert([]) # => nil
   #
-  # Raises an exception unless `object.to_int` returns an Integer object.
+  # Raises an exception unless <code>object.to_int</code> returns an Integer
+  # object.
   #
   def self.try_convert: (int) -> Integer
                       | (untyped) -> Integer?
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self % other -> real_number
+  #   - self % other -> real_numeric
   # -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # For integer `n` and real number `r`, these expressions are equivalent:
   #
@@ -193,13 +194,13 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self * numeric -> numeric_result
+  #   - self * other -> numeric
   # -->
-  # Performs multiplication:
+  # Returns the numeric product of `self` and `other`:
   #
   #     4 * 2              # => 8
-  #     4 * -2             # => -8
   #     -4 * 2             # => -8
+  #     4 * -2             # => -8
   #     4 * 2.0            # => 8.0
   #     4 * Rational(1, 3) # => (4/3)
   #     4 * Complex(2, 0)  # => (8+0i)
@@ -211,17 +212,47 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self ** numeric -> numeric_result
+  #   - self ** exponent -> numeric
   # -->
-  # Raises `self` to the power of `numeric`:
-  #
-  #     2 ** 3              # => 8
-  #     2 ** -3             # => (1/8)
-  #     -2 ** 3             # => -8
-  #     -2 ** -3            # => (-1/8)
-  #     2 ** 3.3            # => 9.849155306759329
-  #     2 ** Rational(3, 1) # => (8/1)
-  #     2 ** Complex(3, 0)  # => (8+0i)
+  # Returns `self` raised to the power `exponent`:
+  #
+  #     # Result for non-negative Integer exponent is Integer.
+  #     2 ** 0   # => 1
+  #     2 ** 1   # => 2
+  #     2 ** 2   # => 4
+  #     2 ** 3   # => 8
+  #     -2 ** 3  # => -8
+  #     # Result for negative Integer exponent is Rational, not Float.
+  #     2 ** -3  # => (1/8)
+  #     -2 ** -3 # => (-1/8)
+  #
+  #     # Result for Float exponent is Float.
+  #     2 ** 0.0   # => 1.0
+  #     2 ** 1.0   # => 2.0
+  #     2 ** 2.0   # => 4.0
+  #     2 ** 3.0   # => 8.0
+  #     -2 ** 3.0  # => -8.0
+  #     2 ** -3.0  # => 0.125
+  #     -2 ** -3.0 # => -0.125
+  #
+  #     # Result for non-negative Complex exponent is Complex with Integer parts.
+  #     2 ** Complex(0, 0)   # => (1+0i)
+  #     2 ** Complex(1, 0)   # => (2+0i)
+  #     2 ** Complex(2, 0)   # => (4+0i)
+  #     2 ** Complex(3, 0)   # => (8+0i)
+  #     -2 ** Complex(3, 0) # => (-8+0i)
+  #     # Result for negative Complex exponent is Complex with Rational parts.
+  #     2 ** Complex(-3, 0)  # => ((1/8)+(0/1)*i)
+  #     -2 ** Complex(-3, 0) # => ((-1/8)+(0/1)*i)
+  #
+  #     # Result for Rational exponent is Rational.
+  #     2 ** Rational(0, 1)   # => (1/1)
+  #     2 ** Rational(1, 1)   # => (2/1)
+  #     2 ** Rational(2, 1)   # => (4/1)
+  #     2 ** Rational(3, 1)   # => (8/1)
+  #     -2 ** Rational(3, 1)  # => (-8/1)
+  #     2 ** Rational(-3, 1)  # => (1/8)
+  #     -2 ** Rational(-3, 1) # => (-1/8)
   #
   def **: (Integer) -> Numeric
         | (Float) -> Numeric
@@ -230,29 +261,31 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self + numeric -> numeric_result
+  #   - self + other -> numeric
   # -->
-  # Performs addition:
+  # Returns the sum of `self` and `other`:
+  #
+  #     1 + 1               # => 2
+  #     1 + -1             # => 0
+  #     1 + 0              # => 1
+  #     1 + -2             # => -1
+  #     1 + Complex(1, 0)  # => (2+0i)
+  #     1 + Rational(1, 1) # => (2/1)
+  #
+  # For a computation involving Floats, the result may be inexact (see Float#+):
   #
-  #     2 + 2              # => 4
-  #     -2 + 2             # => 0
-  #     -2 + -2            # => -4
-  #     2 + 2.0            # => 4.0
-  #     2 + Rational(2, 1) # => (4/1)
-  #     2 + Complex(2, 0)  # => (4+0i)
+  #     1 + 3.14           # => 4.140000000000001
   #
   def +: (Integer) -> Integer
        | (Float) -> Float
        | (Rational) -> Rational
        | (Complex) -> Complex
 
-  def +@: () -> Integer
-
   # <!--
   #   rdoc-file=numeric.c
-  #   - self - numeric -> numeric_result
+  #   - self - other -> numeric
   # -->
-  # Performs subtraction:
+  # Returns the difference of `self` and `other`:
   #
   #     4 - 2              # => 2
   #     -4 - 2             # => -6
@@ -268,28 +301,34 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -int -> integer
+  #   - -self -> integer
   # -->
-  # Returns `self`, negated.
+  # Returns `self`, negated:
+  #
+  #     -1    # => -1
+  #     -(-1) # => 1
+  #     -0    # => 0
   #
   def -@: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self / numeric -> numeric_result
+  #   - self / other -> numeric
   # -->
-  # Performs division; for integer `numeric`, truncates the result to an integer:
+  # Returns the quotient of `self` and `other`.
+  #
+  # For integer `other`, truncates the result to an integer:
   #
-  #      4 / 3              # => 1
-  #      4 / -3             # => -2
-  #      -4 / 3             # => -2
-  #      -4 / -3            # => 1
+  #     4 / 3              # => 1
+  #     4 / -3             # => -2
+  #     -4 / 3             # => -2
+  #     -4 / -3            # => 1
   #
-  #     For other +numeric+, returns non-integer result:
+  # For non-integer `other`, returns a non-integer result:
   #
-  #      4 / 3.0            # => 1.3333333333333333
-  #      4 / Rational(3, 1) # => (4/3)
-  #      4 / Complex(3, 0)  # => ((4/3)+0i)
+  #     4 / 3.0            # => 1.3333333333333333
+  #     4 / Rational(3, 1) # => (4/3)
+  #     4 / Complex(3, 0)  # => ((4/3)+0i)
   #
   def /: (Integer) -> Integer
        | (Float) -> Float
@@ -300,15 +339,14 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - self < other -> true or false
   # -->
-  # Returns `true` if the value of `self` is less than that of `other`:
+  # Returns whether the value of `self` is less than the value of `other`; `other`
+  # must be numeric, but may not be Complex:
   #
-  #       1 < 0              # => false
-  #       1 < 1              # => false
-  #       1 < 2              # => true
-  #       1 < 0.5            # => false
-  #       1 < Rational(1, 2) # => false
-  #
-  #     Raises an exception if the comparison cannot be made.
+  #     1 < 0              # => false
+  #     1 < 1              # => false
+  #     1 < 2              # => true
+  #     1 < 0.5            # => false
+  #     1 < Rational(1, 2) # => false
   #
   def <: (Numeric) -> bool
 
@@ -331,44 +369,46 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self <= real -> true or false
+  #   - self <= other -> true or false
   # -->
-  # Returns `true` if the value of `self` is less than or equal to that of
-  # `other`:
+  # Returns whether the value of `self` is less than or equal to the value of
+  # `other`; `other` must be numeric, but may not be Complex:
   #
-  #     1 <= 0              # => false
-  #     1 <= 1              # => true
-  #     1 <= 2              # => true
-  #     1 <= 0.5            # => false
-  #     1 <= Rational(1, 2) # => false
+  #       1 <= 0              # => false
+  #       1 <= 1              # => true
+  #       1 <= 2              # => true
+  #       1 <= 0.5            # => false
+  #       1 <= Rational(1, 2) # => false
   #
-  # Raises an exception if the comparison cannot be made.
+  #     Raises an exception if the comparison cannot be made.
   #
   def <=: (Numeric) -> bool
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - self <=> other  ->  -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
+  # Compares `self` and `other`.
+  #
   # Returns:
   #
-  # *   -1, if `self` is less than `other`.
-  # *   0, if `self` is equal to `other`.
-  # *   1, if `self` is greater then `other`.
+  # *   <code>-1</code>, if `self` is less than `other`.
+  # *   `0`, if `self` is equal to `other`.
+  # *   `1`, if `self` is greater then `other`.
   # *   `nil`, if `self` and `other` are incomparable.
   #
   # Examples:
   #
   #     1 <=> 2              # => -1
   #     1 <=> 1              # => 0
-  #     1 <=> 0              # => 1
-  #     1 <=> 'foo'          # => nil
-  #
   #     1 <=> 1.0            # => 0
   #     1 <=> Rational(1, 1) # => 0
   #     1 <=> Complex(1, 0)  # => 0
+  #     1 <=> 0              # => 1
+  #     1 <=> 'foo'          # => nil
   #
-  # This method is the basis for comparisons in module Comparable.
+  # Class Integer includes module Comparable, each of whose methods uses
+  # Integer#<=> for comparison.
   #
   def <=>: (Integer | Rational) -> Integer
          | (untyped) -> Integer?
@@ -463,8 +503,8 @@ class Integer < Numeric
   #     n[2]     # => 0
   #     n[3]     # => 0
   #
-  # In principle, `n[i]` is equivalent to `(n >> i) & 1`. Thus, negative index
-  # always returns zero:
+  # In principle, <code>n[i]</code> is equivalent to <code>(n >> i) & 1</code>.
+  # Thus, negative index always returns zero:
   #
   #     255[-1] # => 0
   #
@@ -475,8 +515,9 @@ class Integer < Numeric
   #     "%010b" % n[0, 10] # => "0000111000"
   #     "%010b" % n[4, 10] # => "0000000011"
   #
-  # With argument `range`, returns `range.size` bits from `self`, beginning at
-  # `range.begin` and including bits of greater significance:
+  # With argument `range`, returns <code>range.size</code> bits from `self`,
+  # beginning at <code>range.begin</code> and including bits of greater
+  # significance:
   #
   #     n = 0b111000      # => 56
   #     "%010b" % n[0..9] # => "0000111000"
@@ -515,8 +556,6 @@ class Integer < Numeric
   #
   def abs: () -> Integer
 
-  def abs2: () -> Integer
-
   # <!--
   #   rdoc-file=numeric.c
   #   - allbits?(mask) -> true or false
@@ -540,8 +579,6 @@ class Integer < Numeric
   #
   def allbits?: (int mask) -> bool
 
-  def angle: () -> (Integer | Float)
-
   # <!--
   #   rdoc-file=numeric.c
   #   - anybits?(mask) -> true or false
@@ -576,7 +613,7 @@ class Integer < Numeric
   # significant bit has bit position 1). If there is no such bit (zero or minus
   # one), returns zero.
   #
-  # This method returns `ceil(log2(self < 0 ? -self : self + 1))`>.
+  # This method returns <code>ceil(log2(self < 0 ? -self : self + 1))</code>>.
   #
   #     (-2**1000-1).bit_length   # => 1001
   #     (-2**1000).bit_length     # => 1000
@@ -629,7 +666,7 @@ class Integer < Numeric
   #
   # *   When `self` is non-zero and `ndigits` is negative,
   #      returns a value based on a computed granularity:
-  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The granularity is <code>10 ** ndigits.abs</code>.
   #     *   The returned value is the smallest multiple of the granularity
   #          that is greater than or equal to `self`.
   #     Examples with positive `self`:
@@ -706,10 +743,6 @@ class Integer < Numeric
   #
   def coerce: (Numeric) -> [ Numeric, Numeric ]
 
-  def conj: () -> Integer
-
-  def conjugate: () -> Integer
-
   # <!--
   #   rdoc-file=numeric.rb
   #   - denominator -> 1
@@ -755,7 +788,7 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - divmod(other) -> array
   # -->
-  # Returns a 2-element array `[q, r]`, where
+  # Returns a 2-element array <code>[q, r]</code>, where
   #
   #     q = (self/other).floor    # Quotient
   #     r = self % other          # Remainder
@@ -801,10 +834,6 @@ class Integer < Numeric
   def downto: (Numeric limit) { (Integer) -> void } -> Integer
             | (Numeric limit) -> ::Enumerator[Integer, self]
 
-  def dup: () -> self
-
-  def eql?: (untyped) -> bool
-
   # <!--
   #   rdoc-file=numeric.rb
   #   - even? -> true or false
@@ -829,8 +858,6 @@ class Integer < Numeric
   #
   def fdiv: (Numeric) -> Float
 
-  def finite?: () -> bool
-
   # <!--
   #   rdoc-file=numeric.c
   #   - floor(ndigits = 0) -> integer
@@ -850,7 +877,7 @@ class Integer < Numeric
   #
   # *   When `self` is non-zero and `ndigits` is negative,
   #      returns a value based on a computed granularity:
-  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The granularity is <code>10 ** ndigits.abs</code>.
   #     *   The returned value is the largest multiple of the granularity
   #          that is less than or equal to `self`.
   #     Examples with positive `self`:
@@ -901,14 +928,6 @@ class Integer < Numeric
   #
   def gcdlcm: (Integer) -> [ Integer, Integer ]
 
-  def i: () -> Complex
-
-  def imag: () -> Integer
-
-  def imaginary: () -> Integer
-
-  def infinite?: () -> Integer?
-
   # <!-- rdoc-file=numeric.c -->
   # Returns a string containing the place-value representation of `self` in radix
   # `base` (in 2..36).
@@ -955,7 +974,7 @@ class Integer < Numeric
   def magnitude: () -> Integer
 
   # <!-- rdoc-file=numeric.c -->
-  # Returns `self` modulo `other` as a real number.
+  # Returns `self` modulo `other` as a real numeric (Integer, Float, or Rational).
   #
   # For integer `n` and real number `r`, these expressions are equivalent:
   #
@@ -983,7 +1002,7 @@ class Integer < Numeric
   def negative?: () -> bool
 
   # <!-- rdoc-file=numeric.c -->
-  # Returns the successor integer of `self` (equivalent to `self + 1`):
+  # Returns the successor integer of `self` (equivalent to <code>self + 1</code>):
   #
   #     1.succ  #=> 2
   #     -1.succ #=> 0
@@ -1015,8 +1034,6 @@ class Integer < Numeric
   #
   def nobits?: (int mask) -> bool
 
-  def nonzero?: () -> self?
-
   # <!--
   #   rdoc-file=numeric.rb
   #   - numerator -> self
@@ -1041,8 +1058,6 @@ class Integer < Numeric
   #
   def ord: () -> Integer
 
-  alias phase angle
-
   def polar: () -> [ Integer, Integer | Float ]
 
   def positive?: () -> bool
@@ -1067,7 +1082,7 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - pred -> next_integer
   # -->
-  # Returns the predecessor of `self` (equivalent to `self - 1`):
+  # Returns the predecessor of `self` (equivalent to <code>self - 1</code>):
   #
   #     1.pred  #=> 0
   #     -1.pred #=> -2
@@ -1091,14 +1106,8 @@ class Integer < Numeric
   #
   def rationalize: (?Numeric eps) -> Rational
 
-  def real: () -> self
-
-  def real?: () -> true
-
   def rect: () -> [ Integer, Numeric ]
 
-  alias rectangular rect
-
   # <!--
   #   rdoc-file=numeric.c
   #   - remainder(other) -> real_number
@@ -1132,8 +1141,8 @@ class Integer < Numeric
   # Returns `self` rounded to the nearest value with a precision of `ndigits`
   # decimal digits.
   #
-  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
-  # trailing zeros:
+  # When `ndigits` is negative, the returned value has at least
+  # <code>ndigits.abs</code> trailing zeros:
   #
   #     555.round(-1)      # => 560
   #     555.round(-2)      # => 600
@@ -1150,17 +1159,18 @@ class Integer < Numeric
   # If keyword argument `half` is given, and `self` is equidistant from the two
   # candidate  values, the rounding is according to the given `half` value:
   #
-  # *   `:up` or `nil`: round away from zero:
+  # *   <code>:up</code> or `nil`: round away from zero:
   #
   #         25.round(-1, half: :up)      # => 30
   #         (-25).round(-1, half: :up)   # => -30
   #
-  # *   `:down`: round toward zero:
+  # *   <code>:down</code>: round toward zero:
   #
   #         25.round(-1, half: :down)    # => 20
   #         (-25).round(-1, half: :down) # => -20
   #
-  # *   `:even`: round toward the candidate whose last nonzero digit is even:
+  # *   <code>:even</code>: round toward the candidate whose last nonzero digit is
+  #     even:
   #
   #         25.round(-1, half: :even)    # => 20
   #         15.round(-1, half: :even)    # => 20
@@ -1189,22 +1199,11 @@ class Integer < Numeric
   #
   def size: () -> Integer
 
-  def step: () { (Integer) -> void } -> void
-          | (Numeric limit, ?Integer step) { (Integer) -> void } -> void
-          | (Numeric limit, ?Numeric step) { (Numeric) -> void } -> void
-          | (to: Numeric, ?by: Integer) { (Integer) -> void } -> void
-          | (by: Numeric, ?to: Numeric) { (Numeric) -> void } -> void
-          | () -> Enumerator[Integer, bot]
-          | (Numeric limit, ?Integer step) -> Enumerator[Integer]
-          | (Numeric limit, ?Numeric step) -> Enumerator[Numeric]
-          | (to: Numeric, ?by: Integer) -> Enumerator[Integer]
-          | (by: Numeric, ?to: Numeric) -> Enumerator[Numeric]
-
   # <!--
   #   rdoc-file=numeric.c
   #   - succ -> next_integer
   # -->
-  # Returns the successor integer of `self` (equivalent to `self + 1`):
+  # Returns the successor integer of `self` (equivalent to <code>self + 1</code>):
   #
   #     1.succ  #=> 2
   #     -1.succ #=> 0
@@ -1218,7 +1217,8 @@ class Integer < Numeric
   #   - times {|i| ... } -> self
   #   - times            -> enumerator
   # -->
-  # Calls the given block `self` times with each integer in `(0..self-1)`:
+  # Calls the given block `self` times with each integer in
+  # <code>(0..self-1)</code>:
   #
   #     a = []
   #     5.times {|i| a.push(i) } # => 5
@@ -1229,8 +1229,6 @@ class Integer < Numeric
   def times: () { (Integer) -> void } -> self
            | () -> ::Enumerator[Integer, self]
 
-  def to_c: () -> Complex
-
   # <!--
   #   rdoc-file=numeric.c
   #   - to_f -> float
@@ -1336,8 +1334,8 @@ class Integer < Numeric
   # Returns `self` truncated (toward zero) to a precision of `ndigits` decimal
   # digits.
   #
-  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
-  # trailing zeros:
+  # When `ndigits` is negative, the returned value has at least
+  # <code>ndigits.abs</code> trailing zeros:
   #
   #     555.truncate(-1)  # => 550
   #     555.truncate(-2)  # => 500