ruby-changes:25523
From: zzak <ko1@a...>
Date: Fri, 9 Nov 2012 16:03:27 +0900 (JST)
Subject: [ruby-changes:25523] zzak:r37580 (trunk): * ext/bigdecimal/bigdecimal.c:
zzak 2012-11-09 16:03:13 +0900 (Fri, 09 Nov 2012) New Revision: 37580 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=37580 Log: * ext/bigdecimal/bigdecimal.c: Documentation for BigDecimal Based on a patch from Vincent Batts [ruby-core:49047] [Bug #7305] Modified files: trunk/ChangeLog trunk/ext/bigdecimal/bigdecimal.c Index: ChangeLog =================================================================== --- ChangeLog (revision 37579) +++ ChangeLog (revision 37580) @@ -1,3 +1,10 @@ +Fri Nov 9 16:00:00 2012 Zachary Scott <zzak@z...> + + * ext/bigdecimal/bigdecimal.c: + Documentation for BigDecimal + Based on a patch from Vincent Batts + [ruby-core:49047] [Bug #7305] + Fri Nov 9 15:25:42 2012 Akinori MUSHA <knu@i...> * lib/shellwords.rb (Shellwords#shellescape): Add back my original Index: ext/bigdecimal/bigdecimal.c =================================================================== --- ext/bigdecimal/bigdecimal.c (revision 37579) +++ ext/bigdecimal/bigdecimal.c (revision 37580) @@ -109,9 +109,6 @@ /* * Returns the BigDecimal version number. - * - * Ruby 1.8.0 returns 1.0.0. - * Ruby 1.8.1 thru 1.8.3 return 1.0.1. */ static VALUE BigDecimal_version(VALUE self) @@ -315,7 +312,9 @@ /* * call-seq: hash * - * Creates a hash for this BigDecimal. Two BigDecimals with equal sign, + * Creates a hash for this BigDecimal. + * + * Two BigDecimals with equal sign, * fractional part and exponent have the same hash. */ static VALUE @@ -335,6 +334,18 @@ return INT2FIX(hash); } +/* + * call-seq: _dump + * + * Method used to provide marshalling support. + * + * inf = BigDecimal.new('Infinity') + * => #<BigDecimal:1e16fa8,'Infinity',9(9)> + * BigDecimal._load(inf._dump) + * => #<BigDecimal:1df8dc8,'Infinity',9(9)> + * + * See the Marshal module. + */ static VALUE BigDecimal_dump(int argc, VALUE *argv, VALUE self) { @@ -804,7 +815,11 @@ return self; } - /* call-seq: + /* + * Document-method: BigDecimal#add + * Document-method: BigDecimal#+ + * + * call-seq: * add(value, digits) * * Add the specified value. @@ -813,7 +828,9 @@ * c = a.add(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. + * 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_add(VALUE self, VALUE r) @@ -865,7 +882,9 @@ * c = a.sub(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. + * 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_sub(VALUE self, VALUE r) @@ -1035,8 +1054,9 @@ /* call-seq: * a < b * - * Returns true if a is less than b. Values may be coerced to perform the - * comparison (see ==, coerce). + * Returns true if a is less than b. + * + * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_lt(VALUE self, VALUE r) @@ -1047,8 +1067,9 @@ /* call-seq: * a <= b * - * Returns true if a is less than or equal to b. Values may be coerced to - * perform the comparison (see ==, coerce). + * Returns true if a is less than or equal to b. + * + * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_le(VALUE self, VALUE r) @@ -1059,8 +1080,9 @@ /* call-seq: * a > b * - * Returns true if a is greater than b. Values may be coerced to - * perform the comparison (see ==, coerce). + * Returns true if a is greater than b. + * + * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce). */ static VALUE BigDecimal_gt(VALUE self, VALUE r) @@ -1071,8 +1093,9 @@ /* call-seq: * a >= b * - * Returns true if a is greater than or equal to b. Values may be coerced to - * perform the comparison (see ==, coerce) + * Returns true if a is greater than or equal to b. + * + * Values may be coerced to perform the comparison (see ==, BigDecimal#coerce) */ static VALUE BigDecimal_ge(VALUE self, VALUE r) @@ -1086,7 +1109,8 @@ * Return the negation of self. * * e.g. - * b = -a # b == a * -1 + * b = -a + * b == a * -1 */ static VALUE BigDecimal_neg(VALUE self) @@ -1099,16 +1123,20 @@ return ToValue(c); } - /* call-seq: - * mult(value, digits) + /* + * 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. + * 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) @@ -1159,13 +1187,15 @@ * e.g. * c = a.div(b,n) * - * 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. + * 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. * * If digits is 0, the result is the same as the / operator. If not, the * result is an integer BigDecimal, by analogy with Float#div. * - * The alias quo is provided since div(value, 0) is the same as computing - * the quotient; see divmod. + * The alias quo is provided since <code>div(value, 0)</code> is the same as + * computing the quotient; see BigDecimal#divmod. */ static VALUE BigDecimal_div(VALUE self, VALUE r) @@ -1266,7 +1296,9 @@ * a % b * a.modulo(b) * - * Returns the modulus from dividing by b. See divmod. + * Returns the modulus from dividing by b. + * + * See BigDecimal#divmod. */ static VALUE BigDecimal_mod(VALUE self, VALUE r) /* %: a%b = a - (a.to_f/b).floor * b */ @@ -1364,6 +1396,9 @@ return DoSomeOne(self,r,rb_intern("divmod")); } +/* + * See BigDecimal#quo + */ static VALUE BigDecimal_div2(int argc, VALUE *argv, VALUE self) { @@ -1517,20 +1552,18 @@ * * Round to the nearest 1 (by default), returning the result as a BigDecimal. * - * BigDecimal('3.14159').round -> 3 + * BigDecimal('3.14159').round #=> 3 + * BigDecimal('8.7').round #=> 9 * - * BigDecimal('8.7').round -> 9 - * * If n is specified and positive, the fractional part of the result has no * more than that many digits. * * If n is specified and negative, at least that many digits to the left of the * decimal point will be 0 in the result. * - * BigDecimal('3.14159').round(3) -> 3.142 + * BigDecimal('3.14159').round(3) #=> 3.142 + * BigDecimal('13345.234').round(-2) #=> 13300.0 * - * BigDecimal('13345.234').round(-2) -> 13300.0 - * * The value of the optional mode argument can be used to determine how * rounding is performed; see BigDecimal.mode. */ @@ -1578,19 +1611,17 @@ * * Truncate to the nearest 1, returning the result as a BigDecimal. * - * BigDecimal('3.14159').truncate -> 3 + * BigDecimal('3.14159').truncate #=> 3 + * BigDecimal('8.7').truncate #=> 8 * - * BigDecimal('8.7').truncate -> 8 - * * If n is specified and positive, the fractional part of the result has no * more than that many digits. * * If n is specified and negative, at least that many digits to the left of the * decimal point will be 0 in the result. * - * BigDecimal('3.14159').truncate(3) -> 3.141 - * - * BigDecimal('13345.234').truncate(-2) -> 13300.0 + * BigDecimal('3.14159').truncate(3) #=> 3.141 + * BigDecimal('13345.234').truncate(-2) #=> 13300.0 */ static VALUE BigDecimal_truncate(int argc, VALUE *argv, VALUE self) @@ -1640,19 +1671,17 @@ * * Return the largest integer less than or equal to the value, as a BigDecimal. * - * BigDecimal('3.14159').floor -> 3 + * BigDecimal('3.14159').floor #=> 3 + * BigDecimal('-9.1').floor #=> -10 * - * BigDecimal('-9.1').floor -> -10 - * * If n is specified and positive, the fractional part of the result has no * more than that many digits. * * If n is specified and negative, at least that * many digits to the left of the decimal point will be 0 in the result. * - * BigDecimal('3.14159').floor(3) -> 3.141 - * - * BigDecimal('13345.234').floor(-2) -> 13300.0 + * BigDecimal('3.14159').floor(3) #=> 3.141 + * BigDecimal('13345.234').floor(-2) #=> 13300.0 */ static VALUE BigDecimal_floor(int argc, VALUE *argv, VALUE self) @@ -1689,19 +1718,17 @@ * * Return the smallest integer greater than or equal to the value, as a BigDecimal. * - * BigDecimal('3.14159').ceil -> 4 + * BigDecimal('3.14159').ceil #=> 4 + * BigDecimal('-9.1').ceil #=> -9 * - * BigDecimal('-9.1').ceil -> -9 - * * If n is specified and positive, the fractional part of the result has no * more than that many digits. * * If n is specified and negative, at least that * many digits to the left of the decimal point will be 0 in the result. * - * BigDecimal('3.14159').ceil(3) -> 3.142 - * - * BigDecimal('13345.234').ceil(-2) -> 13400.0 + * BigDecimal('3.14159').ceil(3) #=> 3.142 + * BigDecimal('13345.234').ceil(-2) #=> 13400.0 */ static VALUE BigDecimal_ceil(int argc, VALUE *argv, VALUE self) @@ -1754,11 +1781,14 @@ * * Examples: * - * BigDecimal.new('-123.45678901234567890').to_s('5F') -> '-123.45678 90123 45678 9' + * BigDecimal.new('-123.45678901234567890').to_s('5F') + * #=> '-123.45678 90123 45678 9' * - * BigDecimal.new('123.45678901234567890').to_s('+8F') -> '+123.45678901 23456789' + * BigDecimal.new('123.45678901234567890').to_s('+8F') + * #=> '+123.45678901 23456789' * - * BigDecimal.new('123.45678901234567890').to_s(' F') -> ' 123.4567890123456789' + * BigDecimal.new('123.45678901234567890').to_s(' F') + * #=> ' 123.4567890123456789' */ static VALUE BigDecimal_to_s(int argc, VALUE *argv, VALUE self) @@ -2032,8 +2062,10 @@ * power(n) * power(n, prec) * - * Returns the value raised to the power of n. Note that n must be an Integer. + * Returns the value raised to the power of n. * + * Note that n must be an Integer. + * * Also available as the operator ** */ static VALUE @@ -2260,7 +2292,7 @@ /* call-seq: * big_decimal ** exp -> big_decimal * - * It is a synonym of big_decimal.power(exp). + * It is a synonym of BigDecimal#power(exp). */ static VALUE BigDecimal_power_op(VALUE self, VALUE exp) @@ -2283,6 +2315,7 @@ * * initial:: The initial value, as an Integer, a Float, a Rational, * a BigDecimal, or a String. + * * If it is a String, spaces are ignored and unrecognized characters * terminate the value. * @@ -2311,6 +2344,10 @@ return self; } +/* :nodoc: + * + * private method to dup and clone the provided BigDecimal +other+ + */ static VALUE BigDecimal_initialize_copy(VALUE self, VALUE other) { @@ -2433,8 +2470,23 @@ return INT2FIX(s); } -/* call-seq: - * BigDecimal.save_exception_mode { ... } +/* + * call-seq: BigDecimal.save_exception_mode { ... } + * + * Excecute the provided block, but preserve the exception mode + * + * BigDecimal.save_exception_mode do + * BigDecimal.mode(BigDecimal::EXCEPTION_OVERFLOW, false) + * BigDecimal.mode(BigDecimal::EXCEPTION_NaN, false) + * + * BigDecimal.new(BigDecimal('Infinity')) + * BigDecimal.new(BigDecimal('-Infinity')) + * BigDecimal(BigDecimal.new('NaN')) + * end + * + * For use with the BigDecimal::EXCEPTION_* + * + * See BigDecimal.mode */ static VALUE BigDecimal_save_exception_mode(VALUE self) @@ -2447,8 +2499,19 @@ return ret; } -/* call-seq: - * BigDecimal.save_rounding_mode { ... } +/* + * call-seq: BigDecimal.save_rounding_mode { ... } + * + * Excecute the provided block, but preserve the rounding mode + * + * BigDecimal.save_exception_mode do + * BigDecimal.mode(BigDecimal::ROUND_MODE, :up) + * puts BigDecimal.mode(BigDecimal::ROUND_MODE) + * end + * + * For use with the BigDecimal::ROUND_* + * + * See BigDecimal.mode */ static VALUE BigDecimal_save_rounding_mode(VALUE self) @@ -2461,8 +2524,19 @@ return ret; } -/* call-seq: - * BigDecimal.save_limit { ... } +/* + * call-seq: BigDecimal.save_limit { ... } + * + * Excecute the provided block, but preserve the precision limit + * + * BigDecimal.limit(100) + * puts BigDecimal.limit + * BigDecimal.save_limit do + * BigDecimal.limit(200) + * puts BigDecimal.limit + * end + * puts BigDecimal.limit + * */ static VALUE BigDecimal_save_limit(VALUE self) @@ -2481,7 +2555,7 @@ * Computes the value of e (the base of natural logarithms) raised to the * power of x, to the specified number of digits of precision. * - * If x is infinite, returns Infinity. + * If x is infinity, returns Infinity. * * If x is NaN, returns NaN. */ @@ -2613,7 +2687,7 @@ * * If x is zero or negative, raises Math::DomainError. * - * If x is positive infinite, returns Infinity. + * If x is positive infinity, returns Infinity. * * If x is NaN, returns NaN. */ @@ -2771,6 +2845,7 @@ * BigDecimal provides arbitrary-precision floating point decimal arithmetic. * * Copyright (C) 2002 by Shigeo Kobayashi <shigeo@t...>. + * * You may distribute under the terms of either the GNU General Public * License or the Artistic License, as specified in the README file * of the BigDecimal distribution. @@ -2780,9 +2855,10 @@ * = Introduction * * Ruby provides built-in support for arbitrary precision integer arithmetic. + * * For example: * - * 42**13 -> 1265437718438866624512 + * 42**13 #=> 1265437718438866624512 * * BigDecimal provides similar support for very large or very accurate floating * point numbers. @@ -2790,13 +2866,15 @@ * 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: + * between base 10 and base 2. * + * For example, try: + * * sum = 0 * for i in (1..10000) * sum = sum + 0.0001 * end - * print sum + * print sum #=> 0.9999999999999062 * * and contrast with the output from: * @@ -2806,13 +2884,13 @@ * for i in (1..10000) * sum = sum + BigDecimal.new("0.0001") * end - * print sum + * print sum #=> 0.1E1 * * Similarly: * - * (BigDecimal.new("1.2") - BigDecimal("1.0")) == BigDecimal("0.2") -> true + * (BigDecimal.new("1.2") - BigDecimal("1.0")) == BigDecimal("0.2") #=> true * - * (1.2 - 1.0) == 0.2 -> false + * (1.2 - 1.0) == 0.2 #=> false * * = Special features of accurate decimal arithmetic * @@ -2824,31 +2902,30 @@ * BigDecimal sometimes needs to return infinity, for example if you divide * a value by zero. * - * BigDecimal.new("1.0") / BigDecimal.new("0.0") -> infinity + * BigDecimal.new("1.0") / BigDecimal.new("0.0") #=> infinity + * BigDecimal.new("-1.0") / BigDecimal.new("0.0") #=> -infinity * - * BigDecimal.new("-1.0") / BigDecimal.new("0.0") -> -infinity - * * You can represent infinite numbers to BigDecimal using the strings - * 'Infinity', '+Infinity' and '-Infinity' (case-sensitive) + * <code>'Infinity'</code>, <code>'+Infinity'</code> and + * <code>'-Infinity'</code> (case-sensitive) * * == Not a Number * - * When a computation results in an undefined value, the special value NaN + * When a computation results in an undefined value, the special value +NaN+ * (for 'not a number') is returned. * * Example: * - * BigDecimal.new("0.0") / BigDecimal.new("0.0") -> NaN + * BigDecimal.new("0.0") / BigDecimal.new("0.0") #=> NaN * - * You can also create undefined values. NaN is never considered to be the - * same as any other value, even NaN itself: + * You can also create undefined values. * - * n = BigDecimal.new('NaN') + * NaN is never considered to be the same as any other value, even NaN itself: * - * n == 0.0 -> nil + * n = BigDecimal.new('NaN') + * n == 0.0 #=> nil + * n == n #=> nil * - * n == n -> nil - * * == Positive and negative zero * * If a computation results in a value which is too small to be represented as @@ -2856,16 +2933,17 @@ * be returned. * * If the value which is too small to be represented is negative, a BigDecimal - * value of negative zero is returned. If the value is positive, a value of - * positive zero is returned. + * value of negative zero is returned. * - * BigDecimal.new("1.0") / BigDecimal.new("-Infinity") -> -0.0 + * BigDecimal.new("1.0") / BigDecimal.new("-Infinity") #=> -0.0 * - * BigDecimal.new("1.0") / BigDecimal.new("Infinity") -> 0.0 + * If the value is positive, a value of positive zero is returned. * + * BigDecimal.new("1.0") / BigDecimal.new("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 + * 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 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/