[前][次][番号順一覧][スレッド一覧]

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/

[前][次][番号順一覧][スレッド一覧]