rbs 2.8.4 → 3.8.1

data/stdlib/bigdecimal/0/big_decimal.rbs

@@ -1,139 +1,3 @@
-# <!-- rdoc-file=ext/bigdecimal/bigdecimal.c -->
-# BigDecimal provides arbitrary-precision floating point decimal arithmetic.
-#
-# ## Introduction
-#
-# Ruby provides built-in support for arbitrary precision integer arithmetic.
-#
-# For example:
-#
-#     42**13  #=>   1265437718438866624512
-#
-# BigDecimal provides similar support for very large or very accurate floating
-# point numbers.
-#
-# Decimal arithmetic is also useful for general calculation, because it provides
-# the correct answers people expect--whereas normal binary floating point
-# arithmetic often introduces subtle errors because of the conversion between
-# base 10 and base 2.
-#
-# For example, try:
-#
-#     sum = 0
-#     10_000.times do
-#       sum = sum + 0.0001
-#     end
-#     print sum #=> 0.9999999999999062
-#
-# and contrast with the output from:
-#
-#     require 'bigdecimal'
-#
-#     sum = BigDecimal("0")
-#     10_000.times do
-#       sum = sum + BigDecimal("0.0001")
-#     end
-#     print sum #=> 0.1E1
-#
-# Similarly:
-#
-#     (BigDecimal("1.2") - BigDecimal("1.0")) == BigDecimal("0.2") #=> true
-#
-#     (1.2 - 1.0) == 0.2 #=> false
-#
-# ## A Note About Precision
-#
-# For a calculation using a BigDecimal and another `value`, the precision of the
-# result depends on the type of `value`:
-#
-# *   If `value` is a Float, the precision is Float::DIG + 1.
-# *   If `value` is a Rational, the precision is larger than Float::DIG + 1.
-# *   If `value` is a BigDecimal, the precision is `value`'s precision in the
-#     internal representation, which is platform-dependent.
-# *   If `value` is other object, the precision is determined by the result of
-#     +BigDecimal(value)+.
-#
-#
-# ## Special features of accurate decimal arithmetic
-#
-# Because BigDecimal is more accurate than normal binary floating point
-# arithmetic, it requires some special values.
-#
-# ### Infinity
-#
-# BigDecimal sometimes needs to return infinity, for example if you divide a
-# value by zero.
-#
-#     BigDecimal("1.0") / BigDecimal("0.0")  #=> Infinity
-#     BigDecimal("-1.0") / BigDecimal("0.0")  #=> -Infinity
-#
-# You can represent infinite numbers to BigDecimal using the strings
-# `'Infinity'`, `'+Infinity'` and `'-Infinity'` (case-sensitive)
-#
-# ### Not a Number
-#
-# When a computation results in an undefined value, the special value `NaN` (for
-# 'not a number') is returned.
-#
-# Example:
-#
-#     BigDecimal("0.0") / BigDecimal("0.0") #=> NaN
-#
-# You can also create undefined values.
-#
-# NaN is never considered to be the same as any other value, even NaN itself:
-#
-#     n = BigDecimal('NaN')
-#     n == 0.0 #=> false
-#     n == n #=> false
-#
-# ### Positive and negative zero
-#
-# If a computation results in a value which is too small to be represented as a
-# BigDecimal within the currently specified limits of precision, zero must be
-# returned.
-#
-# If the value which is too small to be represented is negative, a BigDecimal
-# value of negative zero is returned.
-#
-#     BigDecimal("1.0") / BigDecimal("-Infinity") #=> -0.0
-#
-# If the value is positive, a value of positive zero is returned.
-#
-#     BigDecimal("1.0") / BigDecimal("Infinity") #=> 0.0
-#
-# (See BigDecimal.mode for how to specify limits of precision.)
-#
-# Note that `-0.0` and `0.0` are considered to be the same for the purposes of
-# comparison.
-#
-# Note also that in mathematics, there is no particular concept of negative or
-# positive zero; true mathematical zero has no sign.
-#
-# ## bigdecimal/util
-#
-# When you require `bigdecimal/util`, the #to_d method will be available on
-# BigDecimal and the native Integer, Float, Rational, and String classes:
-#
-#     require 'bigdecimal/util'
-#
-#     42.to_d         # => 0.42e2
-#     0.5.to_d        # => 0.5e0
-#     (2/3r).to_d(3)  # => 0.667e0
-#     "0.5".to_d      # => 0.5e0
-#
-# ## License
-#
-# Copyright (C) 2002 by Shigeo Kobayashi <shigeo@tinyforest.gr.jp>.
-#
-# BigDecimal is released under the Ruby and 2-clause BSD licenses. See
-# LICENSE.txt for details.
-#
-# Maintained by mrkn <mrkn@mrkn.jp> and ruby-core members.
-#
-# Documented by zzak <zachary@zacharyscott.net>, mathew <meta@pobox.com>, and
-# many other contributors.
-#
 class BigDecimal < Numeric
   # <!--
   #   rdoc-file=ext/bigdecimal/bigdecimal.c
@@ -192,14 +56,12 @@ class BigDecimal < Numeric
   # *   BigDecimal::EXCEPTION_ZERODIVIDE.
   # *   BigDecimal::EXCEPTION_ALL.
   #
-  #
   # Values for `setting` for exception handling:
   #
   # *   `true`: sets the given `mode` to `true`.
   # *   `false`: sets the given `mode` to `false`.
   # *   `nil`: does not modify the mode settings.
   #
-  #
   # You can use method BigDecimal.save_exception_mode to temporarily change, and
   # then automatically restore, exception modes.
   #
@@ -210,7 +72,6 @@ class BigDecimal < Numeric
   #
   # *   BigDecimal::ROUND_MODE
   #
-  #
   # You can use method BigDecimal.save_rounding_mode to temporarily change, and
   # then automatically restore, the rounding mode.
   #
@@ -224,7 +85,6 @@ class BigDecimal < Numeric
   # *   `false` (default): Returns `BigDecimal('NaN')`.
   # *   `true`: Raises FloatDomainError.
   #
-  #
   # Examples:
   #
   #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false) # => 0
@@ -241,7 +101,6 @@ class BigDecimal < Numeric
   #     `BigDecimal('-Infinity')`.
   # *   `true`: Raises FloatDomainError.
   #
-  #
   # Examples:
   #
   #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)     # => 0
@@ -259,7 +118,6 @@ class BigDecimal < Numeric
   # *   `false` (default): Returns `BigDecimal('0')` or `BigDecimal('-Infinity')`.
   # *   `true`: Raises FloatDomainError.
   #
-  #
   # Examples:
   #
   #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)      # => 0
@@ -280,7 +138,6 @@ class BigDecimal < Numeric
   #     `BigDecimal('-Infinity')`.
   # *   `true`: Raises FloatDomainError.
   #
-  #
   # Examples:
   #
   #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)     # => 0
@@ -301,7 +158,6 @@ class BigDecimal < Numeric
   #     `BigDecimal('-Infinity')`.
   # *   `true`: Raises FloatDomainError.
   #
-  #
   # Examples:
   #
   #     BigDecimal.mode(BigDecimal::EXCEPTION_ALL, false)       # => 0
@@ -392,8 +248,6 @@ class BigDecimal < Numeric
   #
   def self.save_rounding_mode: () { (?nil) -> void } -> void
 
-  public
-
   # <!--
   #   rdoc-file=ext/bigdecimal/bigdecimal.c
   #   - a % b
@@ -1007,23 +861,31 @@ class BigDecimal < Numeric
   # -->
   # Returns the sign of the value.
   #
-  # Returns a positive value if > 0, a negative value if < 0, and a zero if == 0.
+  # Returns a positive value if > 0, a negative value if < 0. It behaves the same
+  # with zeros - it returns a positive value for a positive zero (BigDecimal('0'))
+  # and a negative value for a negative zero (BigDecimal('-0')).
   #
   # The specific value returned indicates the type and sign of the BigDecimal, as
   # follows:
   #
   # BigDecimal::SIGN_NaN
   # :   value is Not a Number
+  #
   # BigDecimal::SIGN_POSITIVE_ZERO
   # :   value is +0
+  #
   # BigDecimal::SIGN_NEGATIVE_ZERO
   # :   value is -0
+  #
   # BigDecimal::SIGN_POSITIVE_INFINITE
   # :   value is +Infinity
+  #
   # BigDecimal::SIGN_NEGATIVE_INFINITE
   # :   value is -Infinity
+  #
   # BigDecimal::SIGN_POSITIVE_FINITE
   # :   value is positive
+  #
   # BigDecimal::SIGN_NEGATIVE_FINITE
   # :   value is negative
   #
@@ -1137,7 +999,7 @@ class BigDecimal < Numeric
   # A space at the start of s returns positive values with a leading space.
   #
   # If s contains a number, a space is inserted after each group of that many
-  # fractional digits.
+  # digits, starting from '.' and counting outwards.
   #
   # If s ends with an 'E', engineering notation (0.xxxxEnn) is used.
   #
@@ -1145,14 +1007,14 @@ class BigDecimal < Numeric
   #
   # Examples:
   #
-  #     BigDecimal('-123.45678901234567890').to_s('5F')
-  #       #=> '-123.45678 90123 45678 9'
+  #     BigDecimal('-1234567890123.45678901234567890').to_s('5F')
+  #       #=> '-123 45678 90123.45678 90123 45678 9'
   #
-  #     BigDecimal('123.45678901234567890').to_s('+8F')
-  #       #=> '+123.45678901 23456789'
+  #     BigDecimal('1234567890123.45678901234567890').to_s('+8F')
+  #       #=> '+12345 67890123.45678901 23456789'
   #
-  #     BigDecimal('123.45678901234567890').to_s(' F')
-  #       #=> ' 123.4567890123456789'
+  #     BigDecimal('1234567890123.45678901234567890').to_s(' F')
+  #       #=> ' 1234567890123.4567890123456789'
   #
   def to_s: (?String | int s) -> String
 
@@ -1348,12 +1210,15 @@ module Kernel
   #   - BigDecimal(value, exception: true) -> bigdecimal
   #   - BigDecimal(value, ndigits, exception: true) -> bigdecimal
   # -->
-  # Returns the \BigDecimal converted from +value+
-  #     with a precision of +ndigits+ decimal digits.
+  # Returns the BigDecimal converted from `value` with a precision of `ndigits`
+  # decimal digits.
+  #
+  # When `ndigits` is less than the number of significant digits in the value, the
+  # result is rounded to that number of digits, according to the current rounding
+  # mode; see BigDecimal.mode.
   #
-  #     When +ndigits+ is less than the number of significant digits
-  #     in the value, the result is rounded to that number of digits,
-  #     according to the current rounding mode; see BigDecimal.mode.
+  # When `ndigits` is 0, the number of digits to correctly represent a float
+  # number is determined automatically.
   #
   # Returns `value` converted to a BigDecimal, depending on the type of `value`:
   #
@@ -1382,9 +1247,7 @@ module Kernel
   # *   Other type:
   #
   #     *   Raises an exception if keyword argument `exception` is `true`.
-  #     *   Returns `nil` if keyword argument `exception` is `true`.
-  #
-  #
+  #     *   Returns `nil` if keyword argument `exception` is `false`.
   #
   # Raises an exception if `value` evaluates to a Float and `digits` is larger
   # than Float::DIG + 1.
@@ -1405,7 +1268,7 @@ class Integer
   #
   #     42.to_d   # => 0.42e2
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: () -> BigDecimal
 
@@ -1486,16 +1349,18 @@ class Float
   #   - float.to_d(precision)  -> bigdecimal
   # -->
   # Returns the value of `float` as a BigDecimal. The `precision` parameter is
-  # used to determine the number of significant digits for the result (the default
-  # is Float::DIG).
+  # used to determine the number of significant digits for the result. When
+  # `precision` is set to `0`, the number of digits to represent the float being
+  # converted is determined automatically. The default `precision` is `0`.
   #
   #     require 'bigdecimal'
   #     require 'bigdecimal/util'
   #
   #     0.5.to_d         # => 0.5e0
+  #     1.234.to_d       # => 0.1234e1
   #     1.234.to_d(2)    # => 0.12e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (?Integer precision) -> BigDecimal
 
@@ -1576,7 +1441,7 @@ class String
   #     "123.45e1".to_d        # => 0.12345e4
   #     "45.67 degrees".to_d   # => 0.4567e2
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: () -> BigDecimal
 end
@@ -1597,7 +1462,7 @@ class Rational
   #
   #     Rational(22, 7).to_d(3)   # => 0.314e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (Integer precision) -> BigDecimal
 
@@ -1682,67 +1547,66 @@ class Complex
   #     Complex(0.1234567, 0).to_d(4)   # => 0.1235e0
   #     Complex(Rational(22, 7), 0).to_d(3)   # => 0.314e1
   #
-  # See also BigDecimal::new.
+  # See also Kernel.BigDecimal.
   #
   def to_d: (*untyped args) -> BigDecimal
 
   # <!--
   #   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.rect(2, 3)  / Complex.rect(2, 3)  # => (1+0i)
+  #     Complex.rect(900)   / Complex.rect(1)     # => (900+0i)
+  #     Complex.rect(-2, 9) / Complex.rect(-9, 2) # => ((36/85)-(77/85)*i)
+  #     Complex.rect(9, 8)  / 4                   # => ((9/4)+2i)
+  #     Complex.rect(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.rect(2, 3)  * Complex.rect(2, 3)  # => (-5+12i)
+  #     Complex.rect(900)   * Complex.rect(1)     # => (900+0i)
+  #     Complex.rect(-2, 9) * Complex.rect(-9, 2) # => (0-85i)
+  #     Complex.rect(9, 8)  * 4                   # => (36+32i)
+  #     Complex.rect(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.rect(2, 3)  + Complex.rect(2, 3)  # => (4+6i)
+  #     Complex.rect(900)   + Complex.rect(1)     # => (901+0i)
+  #     Complex.rect(-2, 9) + Complex.rect(-9, 2) # => (-11+11i)
+  #     Complex.rect(9, 8)  + 4                   # => (13+8i)
+  #     Complex.rect(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.rect(2, 3)  - Complex.rect(2, 3)  # => (0+0i)
+  #     Complex.rect(900)   - Complex.rect(1)     # => (899+0i)
+  #     Complex.rect(-2, 9) - Complex.rect(-9, 2) # => (7+7i)
+  #     Complex.rect(9, 8)  - 4                   # => (5+8i)
+  #     Complex.rect(20, 9) - 9.8                 # => (10.2+9i)
   #
   def -: (BigDecimal) -> Complex
     | ...