ruby-changes:70493
From: Burdette <ko1@a...>
Date: Fri, 24 Dec 2021 02:30:31 +0900 (JST)
Subject: [ruby-changes:70493] 0262f34905 (master): [ruby/bigdecimal] Enhanced RDoc for BigDecimal (https://github.com/ruby/bigdecimal/pull/209)
https://git.ruby-lang.org/ruby.git/commit/?id=0262f34905 From 0262f34905848c2d5ca4ff680094b8a669775b80 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 21 Dec 2021 02:17:16 -0600 Subject: [ruby/bigdecimal] Enhanced RDoc for BigDecimal (https://github.com/ruby/bigdecimal/pull/209) * Enhanced RDoc for BigDecimal * Update ext/bigdecimal/bigdecimal.c Remove the instance number of `Float::DIG`. * Update ext/bigdecimal/bigdecimal.c Add BigDecimal call-seq without ndigits. * Update ext/bigdecimal/bigdecimal.c Replace the word sum with value or result in the description of BigDecimal(). * Update ext/bigdecimal/bigdecimal.c Remove the instance value of Float::DIG. * Update ext/bigdecimal/bigdecimal.c Fix mis-description of precision * Update ext/bigdecimal/bigdecimal.c Fix the description of precision determination * Update ext/bigdecimal/bigdecimal.c Add the description of the precision in the Rational case. https://github.com/ruby/bigdecimal/commit/acabb132a4 Co-authored-by: Kenta Murata <3959+mrkn@u...> --- ext/bigdecimal/bigdecimal.c | 265 +++++++++++++++++++++++++++----------------- 1 file changed, 163 insertions(+), 102 deletions(-) diff --git a/ext/bigdecimal/bigdecimal.c b/ext/bigdecimal/bigdecimal.c index 3be0ffec6df..5af6c7c5bae 100644 --- a/ext/bigdecimal/bigdecimal.c +++ b/ext/bigdecimal/bigdecimal.c @@ -256,7 +256,7 @@ GetVpValue(VALUE v, int must) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L256 } /* call-seq: - * BigDecimal.double_fig + * BigDecimal.double_fig -> integer * * Returns the number of digits a Float object is allowed to have; * the result is system-dependent: @@ -524,7 +524,7 @@ BigDecimal_n_significant_digits(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L524 /* * call-seq: - * hash -> integer + * hash -> integer * * Returns the integer hash value for +self+. * @@ -555,7 +555,7 @@ BigDecimal_hash(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L555 /* * call-seq: - * _dump + * _dump -> string * * Returns a string representing the marshalling of +self+. * See module Marshal. @@ -1236,12 +1236,17 @@ BigDecimal_uplus(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1236 /* * call-seq: - * self + value -> new_bigdecimal + * self + value -> bigdecimal * - * Returns the sum of +self+ and +value+: + * Returns the \BigDecimal sum of +self+ and +value+: * * b = BigDecimal('111111.111') # => 0.111111111e6 - * b + 1 # => 0.111112111e6 + * b + 2 # => 0.111113111e6 + * b + 2.0 # => 0.111113111e6 + * b + Rational(2, 1) # => 0.111113111e6 + * b + Complex(2, 0) # => (0.111113111e6+0i) + * + * See the {Note About Precision}[BigDecimal.html#class-BigDecimal-label-A+Note+About+Precision]. * */ @@ -1286,21 +1291,18 @@ BigDecimal_add(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1291 return VpCheckGetValue(c); } - /* call-seq: - * a - b -> bigdecimal - * - * Subtract the specified value. - * - * e.g. - * c = a - b + /* call-seq: + * self - value -> bigdecimal * - * The precision of the result value depends on the type of +b+. + * Returns the \BigDecimal difference of +self+ and +value+: * - * If +b+ is a Float, the precision of the result is Float::DIG+1. + * b = BigDecimal('333333.333') # => 0.333333333e6 + * b - 2 # => 0.333331333e6 + * b - 2.0 # => 0.333331333e6 + * b - Rational(2, 1) # => 0.333331333e6 + * b - Complex(2, 0) # => (0.333331333e6+0i) * - * If +b+ is a BigDecimal, the precision of the result is +b+'s precision of - * internal representation from platform. So, it's return value is platform - * dependent. + * See the {Note About Precision}[BigDecimal.html#class-BigDecimal-label-A+Note+About+Precision]. * */ static VALUE @@ -1479,12 +1481,19 @@ BigDecimal_eq(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1481 return BigDecimalCmp(self, r, '='); } -/* call-seq: - * a < b +/* call-seq: + * self < other -> true or false + * + * Returns +true+ if +self+ is less than +other+, +false+ otherwise: + * + * b = BigDecimal('1.5') # => 0.15e1 + * b < 2 # => true + * b < 2.0 # => true + * b < Rational(2, 1) # => true + * b < 1.5 # => false * - * Returns true if a is less than b. + * Raises an exception if the comparison cannot be made. * - * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_lt(VALUE self, VALUE r) @@ -1492,12 +1501,20 @@ BigDecimal_lt(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1501 return BigDecimalCmp(self, r, '<'); } -/* call-seq: - * a <= b +/* call-seq: + * self <= other -> true or false + * + * Returns +true+ if +self+ is less or equal to than +other+, +false+ otherwise: + * + * b = BigDecimal('1.5') # => 0.15e1 + * b <= 2 # => true + * b <= 2.0 # => true + * b <= Rational(2, 1) # => true + * b <= 1.5 # => true + * b < 1 # => false * - * Returns true if a is less than or equal to b. + * Raises an exception if the comparison cannot be made. * - * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_le(VALUE self, VALUE r) @@ -1505,12 +1522,19 @@ BigDecimal_le(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1522 return BigDecimalCmp(self, r, 'L'); } -/* call-seq: - * a > b +/* call-seq: + * self > other -> true or false + * + * Returns +true+ if +self+ is greater than +other+, +false+ otherwise: * - * Returns true if a is greater than b. + * b = BigDecimal('1.5') + * b > 1 # => true + * b > 1.0 # => true + * b > Rational(1, 1) # => true + * b > 2 # => false + * + * Raises an exception if the comparison cannot be made. * - * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_gt(VALUE self, VALUE r) @@ -1518,12 +1542,20 @@ BigDecimal_gt(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1542 return BigDecimalCmp(self, r, '>'); } -/* call-seq: - * a >= b +/* call-seq: + * self >= other -> true or false + * + * Returns +true+ if +self+ is greater than or equal to +other+, +false+ otherwise: * - * Returns true if a is greater than or equal to b. + * b = BigDecimal('1.5') + * b >= 1 # => true + * b >= 1.0 # => true + * b >= Rational(1, 1) # => true + * b >= 1.5 # => true + * b > 2 # => false + * + * Raises an exception if the comparison cannot be made. * - * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce) */ static VALUE BigDecimal_ge(VALUE self, VALUE r) @@ -1533,11 +1565,14 @@ BigDecimal_ge(VALUE self, VALUE r) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1565 /* * call-seq: - * -big_decimal -> big_decimal + * -self -> bigdecimal + * + * Returns the \BigDecimal negation of self: * - * Return the negation of self. + * b0 = BigDecimal('1.5') + * b1 = -b0 # => -0.15e1 + * b2 = -b1 # => 0.15e1 * - * -BigDecimal('5') #=> -0.5e1 */ static VALUE @@ -1551,21 +1586,6 @@ BigDecimal_neg(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L1586 return VpCheckGetValue(c); } - /* - * Document-method: BigDecimal#mult - * - * call-seq: mult(value, digits) - * - * Multiply by the specified value. - * - * e.g. - * c = a.mult(b,n) - * c = a * b - * - * digits:: If specified and less than the number of significant digits of the - * result, the result is rounded to that number of digits, according - * to BigDecimal.mode. - */ static VALUE BigDecimal_mult(VALUE self, VALUE r) { @@ -2032,7 +2052,7 @@ BigDecimal_div3(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L2052 * call-seq: * add(value, ndigits) -> new_bigdecimal * - * Returns the sum of +self+ and +value+ + * Returns the \BigDecimal sum of +self+ and +value+ * with a precision of +ndigits+ decimal digits. * * When +ndigits+ is less than the number of significant digits @@ -2043,15 +2063,13 @@ BigDecimal_div3(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/bigdecimal/bigdecimal.c#L2063 * * # Set the rounding mode. * BigDecimal.mode(BigDecimal::ROUND_MODE, :half_up) - * BigDecimal('111111.111').add(1, 0) # => 0.111112111e6 - * BigDecimal('111111.111').add(1, 2) # => 0.11e6 - * BigDecimal('111111.111').add(1, 3) # => 0.111e6 - * BigDecimal('111111.111').add(1, 4) # => 0.1111e6 - * BigDecimal('111111.111').add(1, 5) # => 0.11111e6 - * BigDecimal('111111.111').add(1, 6) # => 0.111112e6 - * BigDecimal('111111.111').add(1, 7) # => 0.1111121e6 - * BigDecimal('111111.111').add(1, 8) # => 0.11111211e6 - * BigDecimal('111111.111').add(1, 9) # => 0.111112111e6 + * b = BigDecimal('111111.111') + * b.add(1, 0) # => 0.111112111e6 + * b.add(1, 3) # => 0.111e6 + * b.add(1, 6) # => 0.111112e6 + * b.add(1, 15) # => 0.111112111e6 + * b.add(1.0, 15) # => 0.111112111e6 + * b.add(Rational(1, 1), 15) # => 0.111112111e6 * */ @@ -2102,6 +2120,31 @@ BigDecimal_sub2(VALUE self, VALUE b, (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/