rbs 2.8.4 → 3.8.1

data/core/float.rbs

@@ -6,138 +6,75 @@
 # 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
 #
-#
 # You can create a Float object explicitly with:
 #
-# *   A [floating-point
-#     literal](doc/syntax/literals_rdoc.html#label-Float+Literals).
-#
+# *   A [floating-point literal](rdoc-ref:syntax/literals.rdoc@Float+Literals).
 #
 # You can convert certain objects to Floats with:
 #
-# *   Method [Float](Kernel.html#method-i-Float).
-#
+# *   Method #Float.
 #
 # ## What's Here
 #
 # First, what's elsewhere. Class Float:
 #
-# *   Inherits from [class
-#     Numeric](Numeric.html#class-Numeric-label-What-27s+Here).
-#
+# *   Inherits from [class Numeric](rdoc-ref:Numeric@What-27s+Here) and [class
+#     Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
 # Here, class Float provides methods for:
 #
-# *   [Querying](#class-Float-label-Querying)
-# *   [Comparing](#class-Float-label-Comparing)
-# *   [Converting](#class-Float-label-Converting)
-#
+# *   [Querying](rdoc-ref:Float@Querying)
+# *   [Comparing](rdoc-ref:Float@Comparing)
+# *   [Converting](rdoc-ref:Float@Converting)
 #
 # ### Querying
 #
-#     #finite?
-# :       Returns whether `self` is finite.
-#
-#     #hash
-# :       Returns the integer hash code for `self`.
-#
-#     #infinite?
-# :       Returns whether `self` is infinite.
-#
-#     #nan?
-# :       Returns whether `self` is a NaN (not-a-number).
-#
-#
+# *   #finite?: Returns whether `self` is finite.
+# *   #hash: Returns the integer hash code for `self`.
+# *   #infinite?: Returns whether `self` is infinite.
+# *   #nan?: Returns whether `self` is a NaN (not-a-number).
 #
 # ### Comparing
 #
-#     [<](#method-i-3C)
-# :       Returns whether `self` is less than the given value.
-#
-#     [<=](#method-i-3C-3D)
-# :       Returns whether `self` is less than or equal to the given value.
-#
-#     [<=>](#method-i-3C-3D-3E)
-# :       Returns a number indicating whether `self` is less than, equal to, or
-#         greater than the given value.
-#
-#     [==](#method-i-3D-3D) (aliased as #=== and #eql>)
-# :       Returns whether `self` is equal to the given value.
-#
-#     [>](#method-i-3E)
-# :       Returns whether `self` is greater than the given value.
-#
-#     [>=](#method-i-3E-3D)
-# :       Returns whether `self` is greater than or equal to the given value.
-#
-#
+# *   #<: Returns whether `self` is less than the given value.
+# *   #<=: Returns whether `self` is less than or equal to the given value.
+# *   #<=>: Returns a number indicating whether `self` is less than, equal to,
+#     or greater than the given value.
+# *   #== (aliased as #=== and #eql?): Returns whether `self` is equal to the
+#     given value.
+# *   #>: Returns whether `self` is greater than the given value.
+# *   #>=: Returns whether `self` is greater than or equal to the given value.
 #
 # ### Converting
 #
-#     #% (aliased as #modulo)
-# :       Returns `self` modulo the given value.
-#
-#     #*
-# :       Returns the product of `self` and the given value.
-#
-#     [**](#method-i-2A-2A)
-# :       Returns the value of `self` raised to the power of the given value.
-#
-#     #+
-# :       Returns the sum of `self` and the given value.
-#
-#     #-
-# :       Returns the difference of `self` and the given value.
-#
-#     [/](#method-i-2F)
-# :       Returns the quotient of `self` and the given value.
-#
-#     #ceil
-# :       Returns the smallest number greater than or equal to `self`.
-#
-#     #coerce
-# :       Returns a 2-element array containing the given value converted to a
-#         Float and `self`
-#
-#     #divmod
-# :       Returns a 2-element array containing the quotient and remainder
-#         results of dividing `self` by the given value.
-#
-#     #fdiv
-# :       Returns the Float result of dividing `self` by the given value.
-#
-#     #floor
-# :       Returns the greatest number smaller than or equal to `self`.
-#
-#     #next_float
-# :       Returns the next-larger representable Float.
-#
-#     #prev_float
-# :       Returns the next-smaller representable Float.
-#
-#     #quo
-# :       Returns the quotient from dividing `self` by the given value.
-#
-#     #round
-# :       Returns `self` rounded to the nearest value, to a given precision.
-#
-#     #to_i (aliased as #to_int)
-# :       Returns `self` truncated to an Integer.
-#
-#     #to_s (aliased as #inspect)
-# :       Returns a string containing the place-value representation of `self`
-#         in the given radix.
-#
-#     #truncate
-# :       Returns `self` truncated to a given precision.
+# *   #% (aliased as #modulo): Returns `self` modulo the given value.
+# *   #*: Returns the product of `self` and the given value.
+# *   #**: Returns the value of `self` raised to the power of the given value.
+# *   #+: Returns the sum of `self` and the given value.
+# *   #-: Returns the difference of `self` and the given value.
+# *   #/: Returns the quotient of `self` and the given value.
+# *   #ceil: Returns the smallest number greater than or equal to `self`.
+# *   #coerce: Returns a 2-element array containing the given value converted to
+#     a Float and `self`
+# *   #divmod: Returns a 2-element array containing the quotient and remainder
+#     results of dividing `self` by the given value.
+# *   #fdiv: Returns the Float result of dividing `self` by the given value.
+# *   #floor: Returns the greatest number smaller than or equal to `self`.
+# *   #next_float: Returns the next-larger representable Float.
+# *   #prev_float: Returns the next-smaller representable Float.
+# *   #quo: Returns the quotient from dividing `self` by the given value.
+# *   #round: Returns `self` rounded to the nearest value, to a given precision.
+# *   #to_i (aliased as #to_int): Returns `self` truncated to an Integer.
+# *   #to_s (aliased as #inspect): Returns a string containing the place-value
+#     representation of `self` in the given radix.
+# *   #truncate: Returns `self` truncated to a given precision.
 #
 class Float < Numeric
-  public
-
   # <!--
   #   rdoc-file=numeric.c
   #   - self % other -> float
@@ -165,8 +102,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
@@ -237,9 +172,9 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -float  ->  float
+  #   - -float -> float
   # -->
-  # Returns `float`, negated.
+  # Returns `self`, negated.
   #
   def -@: () -> Float
 
@@ -301,7 +236,6 @@ class Float < Numeric
   # *   1, if `self` is greater than `other`.
   # *   `nil`, if the two values are incommensurate.
   #
-  #
   # Examples:
   #
   #     2.0 <=> 2              # => 0
@@ -382,33 +316,28 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - float.abs        ->  float
-  #   - float.magnitude  ->  float
+  #   - float.abs ->  float
   # -->
-  # Returns the absolute value of `float`.
+  # Returns the absolute value of `self`:
   #
-  #     (-34.56).abs   #=> 34.56
-  #     -34.56.abs     #=> 34.56
-  #     34.56.abs      #=> 34.56
-  #
-  # 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
 
   def abs2: () -> Float
 
   # <!-- rdoc-file=complex.c -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns 0 if `self` is positive, Math::PI otherwise.
   #
   def angle: () -> (Integer | Float)
 
   # <!--
   #   rdoc-file=complex.c
-  #   - flo.arg    ->  0 or float
-  #   - flo.angle  ->  0 or float
-  #   - flo.phase  ->  0 or float
+  #   - arg -> 0 or Math::PI
   # -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns 0 if `self` is positive, Math::PI otherwise.
   #
   alias arg angle
 
@@ -416,33 +345,58 @@ class Float < Numeric
   #   rdoc-file=numeric.c
   #   - ceil(ndigits = 0) -> float or integer
   # -->
-  # Returns the smallest number greater than or equal to `self` with a precision
-  # of `ndigits` decimal digits.
-  #
-  # When `ndigits` is positive, returns a float with `ndigits` digits after the
-  # decimal point (as available):
-  #
+  # Returns a numeric that is a "ceiling" value for `self`,
+  # as specified by the given `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # When `ndigits` is positive, returns a Float with `ndigits`
+  # decimal digits after the decimal point
+  # (as available, but no fewer than 1):
   #     f = 12345.6789
-  #     f.ceil(1) # => 12345.7
-  #     f.ceil(3) # => 12345.679
-  #     f = -12345.6789
-  #     f.ceil(1) # => -12345.6
-  #     f.ceil(3) # => -12345.678
-  #
-  # When `ndigits` is non-positive, returns an integer with at least `ndigits.abs`
-  # trailing zeros:
-  #
-  #     f = 12345.6789
-  #     f.ceil(0)  # => 12346
-  #     f.ceil(-3) # => 13000
-  #     f = -12345.6789
-  #     f.ceil(0)  # => -12345
-  #     f.ceil(-3) # => -12000
-  #
-  # Note that the limited precision of floating-point arithmetic may lead to
-  # surprising results:
-  #
-  #     (2.1 / 0.7).ceil  #=> 4 (!)
+  # f.ceil(1) # => 12345.7
+  # f.ceil(3) # => 12345.679
+  # f.ceil(30) # => 12345.6789
+  # f = -12345.6789
+  # f.ceil(1) # => -12345.6
+  # f.ceil(3) # => -12345.678
+  # f.ceil(30) # => -12345.6789
+  # f = 0.0
+  # f.ceil(1)   # => 0.0
+  # f.ceil(100) # => 0.0
+  #
+  # When `ndigits` is non-positive,
+  # returns an Integer based on a computed granularity:
+  # *   The granularity is `10 ** ndigits.abs`.
+  # *   The returned value is the largest multiple of the granularity
+  #      that is less than or equal to `self`.
+  # Examples with positive `self`:
+  # ndigits|Granularity|12345.6789.ceil(ndigits)
+  # -------|-----------|------------------------
+  #       0|          1|                   12346
+  #      -1|         10|                   12350
+  #      -2|        100|                   12400
+  #      -3|       1000|                   13000
+  #      -4|      10000|                   20000
+  #      -5|     100000|                  100000
+  # Examples with negative `self`:
+  # ndigits|Granularity|-12345.6789.ceil(ndigits)
+  # -------|-----------|-------------------------
+  #       0|          1|                   -12345
+  #      -1|         10|                   -12340
+  #      -2|        100|                   -12300
+  #      -3|       1000|                   -12000
+  #      -4|      10000|                   -10000
+  #      -5|     100000|                        0
+  # When `self` is zero and `ndigits` is non-positive,
+  # returns Integer zero:
+  #     0.0.ceil(0)  # => 0
+  # 0.0.ceil(-1) # => 0
+  # 0.0.ceil(-2) # => 0
+  #
+  # Note that the limited precision of floating-point arithmetic
+  # may lead to surprising results:
+  #     (2.1 / 0.7).ceil  #=> 4 # Not 3 (because 2.1 / 0.7 # => 3.0000000000000004, not 3.0)
   #
   # Related: Float#floor.
   #
@@ -505,7 +459,8 @@ class Float < Numeric
   #     13.0.divmod(4.0)            # => [3, 1.0]
   #     13.0.divmod(Rational(4, 1)) # => [3, 1.0]
   #
-  def divmod: (Numeric) -> [ Numeric, Numeric ]
+  def divmod: (Integer | Float | Rational) -> [ Integer, Float ]
+            | (Numeric) -> [ Numeric, Numeric ]
 
   def dup: () -> self
 
@@ -537,8 +492,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
 
@@ -546,7 +499,7 @@ class Float < Numeric
   #   rdoc-file=numeric.c
   #   - finite? -> true or false
   # -->
-  # Returns `true` if `self` is not `Infinity`, `-Infinity`, or `Nan`, `false`
+  # Returns `true` if `self` is not `Infinity`, `-Infinity`, or `NaN`, `false`
   # otherwise:
   #
   #     f = 2.0      # => 2.0
@@ -564,33 +517,59 @@ class Float < Numeric
   #   rdoc-file=numeric.c
   #   - floor(ndigits = 0) -> float or integer
   # -->
-  # Returns the largest number less than or equal to `self` with a precision of
-  # `ndigits` decimal digits.
-  #
-  # When `ndigits` is positive, returns a float with `ndigits` digits after the
-  # decimal point (as available):
-  #
-  #     f = 12345.6789
-  #     f.floor(1) # => 12345.6
-  #     f.floor(3) # => 12345.678
-  #     f = -12345.6789
-  #     f.floor(1) # => -12345.7
-  #     f.floor(3) # => -12345.679
-  #
-  # When `ndigits` is non-positive, returns an integer with at least `ndigits.abs`
-  # trailing zeros:
-  #
+  # Returns a float or integer that is a "floor" value for `self`,
+  # as specified by `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # When `self` is zero,
+  # returns a zero value:
+  # a float if `ndigits` is positive,
+  # an integer otherwise:
+  #     f = 0.0      # => 0.0
+  # f.floor(20)  # => 0.0
+  # f.floor(0)   # => 0
+  # f.floor(-20) # => 0
+  #
+  # When `self` is non-zero and `ndigits` is positive, returns a float with
+  # `ndigits`
+  # digits after the decimal point (as available):
   #     f = 12345.6789
-  #     f.floor(0)  # => 12345
-  #     f.floor(-3) # => 12000
-  #     f = -12345.6789
-  #     f.floor(0)  # => -12346
-  #     f.floor(-3) # => -13000
-  #
-  # Note that the limited precision of floating-point arithmetic may lead to
-  # surprising results:
-  #
-  #     (0.3 / 0.1).floor  #=> 2 (!)
+  # f.floor(1)  # => 12345.6
+  # f.floor(3)  # => 12345.678
+  # f.floor(30) # => 12345.6789
+  # f = -12345.6789
+  # f.floor(1)  # => -12345.7
+  # f.floor(3)  # => -12345.679
+  # f.floor(30) # => -12345.6789
+  #
+  # When `self` is non-zero and `ndigits` is non-positive,
+  # returns an integer value based on a computed granularity:
+  # *   The granularity is `10 ** ndigits.abs`.
+  # *   The returned value is the largest multiple of the granularity
+  #      that is less than or equal to `self`.
+  # Examples with positive `self`:
+  # ndigits|Granularity|12345.6789.floor(ndigits)
+  # -------|-----------|-------------------------
+  #       0|          1|                    12345
+  #      -1|         10|                    12340
+  #      -2|        100|                    12300
+  #      -3|       1000|                    12000
+  #      -4|      10000|                    10000
+  #      -5|     100000|                        0
+  # Examples with negative `self`:
+  # ndigits|Granularity|-12345.6789.floor(ndigits)
+  # -------|-----------|--------------------------
+  #       0|          1|                    -12346
+  #      -1|         10|                    -12350
+  #      -2|        100|                    -12400
+  #      -3|       1000|                    -13000
+  #      -4|      10000|                    -20000
+  #      -5|     100000|                   -100000
+  #      -6|    1000000|                  -1000000
+  # Note that the limited precision of floating-point arithmetic
+  # may lead to surprising results:
+  #     (0.3 / 0.1).floor  # => 2 # Not 3, (because (0.3 / 0.1) # => 2.9999999999999996, not 3.0)
   #
   # Related: Float#ceil.
   #
@@ -623,7 +602,6 @@ class Float < Numeric
   # *   -1 if `self` is `-Infinity`.
   # *   `nil`, otherwise.
   #
-  #
   # Examples:
   #
   #     f = 1.0/0.0  # => Infinity
@@ -642,14 +620,19 @@ class Float < Numeric
   # of `self`, the string representation may contain:
   #
   # *   A fixed-point number.
+  #         3.14.to_s         # => "3.14"
+  #
   # *   A number in "scientific notation" (containing an exponent).
+  #         (10.1**50).to_s   # => "1.644631821843879e+50"
+  #
   # *   'Infinity'.
+  #         (10.1**500).to_s  # => "Infinity"
+  #
   # *   '-Infinity'.
-  # *   'NaN' (indicating not-a-number).
+  #         (-10.1**500).to_s # => "-Infinity"
   #
-  #     3.14.to_s         # => "3.14" (10.1**50).to_s   # =>
-  #     "1.644631821843879e+50" (10.1**500).to_s  # => "Infinity"
-  #     (-10.1**500).to_s # => "-Infinity" (0.0/0.0).to_s    # => "NaN"
+  # *   'NaN' (indicating not-a-number).
+  #         (0.0/0.0).to_s    # => "NaN"
   #
   alias inspect to_s
 
@@ -686,8 +669,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
 
   # <!--
@@ -705,9 +686,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
 
@@ -773,7 +754,7 @@ class Float < Numeric
   def numerator: () -> Integer
 
   # <!-- rdoc-file=complex.c -->
-  # Returns 0 if the value is positive, pi otherwise.
+  # Returns 0 if `self` is positive, Math::PI otherwise.
   #
   alias phase angle
 
@@ -781,9 +762,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
 
@@ -835,8 +816,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
 
@@ -868,7 +847,7 @@ class Float < Numeric
 
   # <!--
   #   rdoc-file=numeric.c
-  #   - round(ndigits = 0, half: :up]) -> integer or float
+  #   - round(ndigits = 0, half: :up) -> integer or float
   # -->
   # Returns `self` rounded to the nearest value with a precision of `ndigits`
   # decimal digits.
@@ -914,7 +893,6 @@ class Float < Numeric
   #         3.5.round(half: :even)    # => 4
   #         (-2.5).round(half: :even) # => -2
   #
-  #
   # Raises and exception if the value for `half` is invalid.
   #
   # Related: Float#truncate.
@@ -931,9 +909,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
 
@@ -951,8 +929,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 -->
@@ -966,8 +942,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
 
   # <!--
@@ -1000,14 +974,19 @@ class Float < Numeric
   # of `self`, the string representation may contain:
   #
   # *   A fixed-point number.
+  #         3.14.to_s         # => "3.14"
+  #
   # *   A number in "scientific notation" (containing an exponent).
+  #         (10.1**50).to_s   # => "1.644631821843879e+50"
+  #
   # *   'Infinity'.
+  #         (10.1**500).to_s  # => "Infinity"
+  #
   # *   '-Infinity'.
-  # *   'NaN' (indicating not-a-number).
+  #         (-10.1**500).to_s # => "-Infinity"
   #
-  #     3.14.to_s         # => "3.14" (10.1**50).to_s   # =>
-  #     "1.644631821843879e+50" (10.1**500).to_s  # => "Infinity"
-  #     (-10.1**500).to_s # => "-Infinity" (0.0/0.0).to_s    # => "NaN"
+  # *   'NaN' (indicating not-a-number).
+  #         (0.0/0.0).to_s    # => "NaN"
   #
   def to_s: () -> String
 
@@ -1050,9 +1029,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