ruby-changes:46464
From: stomar <ko1@a...>
Date: Sat, 6 May 2017 16:17:47 +0900 (JST)
Subject: [ruby-changes:46464] stomar:r58580 (trunk): numeric.c: revise docs
stomar 2017-05-06 16:17:41 +0900 (Sat, 06 May 2017) New Revision: 58580 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=58580 Log: numeric.c: revise docs * numeric.c: [DOC] revise docs for Numeric, Integer, Float: * nodoc Numeric#singleton_method_added * mention that result for Integer#** might also be Complex * add / simplify / fix some examples * mention aliases * fix rdoc formatting, typos, grammar * clarifications and other improvements Modified files: trunk/numeric.c Index: numeric.c =================================================================== --- numeric.c (revision 58579) +++ numeric.c (revision 58580) @@ -409,9 +409,9 @@ num_funcall1(VALUE x, ID func, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L409 * call-seq: * num.coerce(numeric) -> array * - * If a +numeric+ is the same type as +num+, returns an array containing - * +numeric+ and +num+. Otherwise, returns an array with both a +numeric+ and - * +num+ represented as Float objects. + * If +numeric+ is the same type as +num+, returns an array + * <code>[numeric, num]</code>. Otherwise, returns an array with both + * +numeric+ and +num+ represented as Float objects. * * This coercion mechanism is used by Ruby to handle mixed-type numeric * operations: it is intended to find a compatible common type between the two @@ -497,6 +497,8 @@ rb_num_coerce_relop(VALUE x, VALUE y, ID https://github.com/ruby/ruby/blob/trunk/numeric.c#L497 } /* + * :nodoc: + * * Trap attempts to add methods to Numeric objects. Always raises a TypeError. * * Numerics should be values; singleton_methods should not be added to them. @@ -519,10 +521,9 @@ num_sadded(VALUE x, VALUE name) https://github.com/ruby/ruby/blob/trunk/numeric.c#L521 #if 0 /* * call-seq: - * num.clone(freeze: true) -> num + * num.clone(freeze: true) -> num * - * Returns the receiver. - * _freeze_ cannot be +false+. + * Returns the receiver. +freeze+ cannot be +false+. */ static VALUE num_clone(int argc, VALUE *argv, VALUE x) @@ -536,7 +537,7 @@ num_clone(int argc, VALUE *argv, VALUE x https://github.com/ruby/ruby/blob/trunk/numeric.c#L537 #if 0 /* * call-seq: - * num.dup -> num + * num.dup -> num * * Returns the receiver. */ @@ -553,7 +554,7 @@ num_dup(VALUE x) https://github.com/ruby/ruby/blob/trunk/numeric.c#L554 * call-seq: * +num -> num * - * Unary Plus---Returns the receiver's value. + * Unary Plus---Returns the receiver. */ static VALUE @@ -564,10 +565,13 @@ num_uplus(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L565 /* * call-seq: - * num.i -> Complex(0,num) + * num.i -> Complex(0, num) * * Returns the corresponding imaginary number. * Not available for complex numbers. + * + * -42.i #=> (0-42i) + * 2.0.i #=> (0+2.0i) */ static VALUE @@ -576,12 +580,11 @@ num_imaginary(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L580 return rb_complex_new(INT2FIX(0), num); } - /* * call-seq: * -num -> numeric * - * Unary Minus---Returns the receiver's value, negated. + * Unary Minus---Returns the receiver, negated. */ static VALUE @@ -608,13 +611,12 @@ num_fdiv(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L611 return rb_funcall(rb_Float(x), '/', 1, y); } - /* * call-seq: * num.div(numeric) -> integer * * Uses +/+ to perform division, then converts the result to an integer. - * +numeric+ does not define the +/+ operator; this is left to subclasses. + * Numeric does not define the +/+ operator; this is left to subclasses. * * Equivalent to <code>num.divmod(numeric)[0]</code>. * @@ -628,12 +630,11 @@ num_div(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L630 return rb_funcall(num_funcall1(x, '/', y), rb_intern("floor"), 0); } - /* * call-seq: * num.modulo(numeric) -> real * - * x.modulo(y) means x-y*(x/y).floor + * <code>x.modulo(y)</code> means <code>x-y*(x/y).floor</code>. * * Equivalent to <code>num.divmod(numeric)[1]</code>. * @@ -652,7 +653,7 @@ num_modulo(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L653 * call-seq: * num.remainder(numeric) -> real * - * x.remainder(y) means x-y*(x/y).truncate + * <code>x.remainder(y)</code> means <code>x-y*(x/y).truncate</code>. * * See Numeric#divmod. */ @@ -679,12 +680,13 @@ num_remainder(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L680 * Returns an array containing the quotient and modulus obtained by dividing * +num+ by +numeric+. * - * If <code>q, r = * x.divmod(y)</code>, then + * If <code>q, r = x.divmod(y)</code>, then * * q = floor(x/y) - * x = q*y+r + * x = q*y + r * - * The quotient is rounded toward -infinity, as shown in the following table: + * The quotient is rounded toward negative infinity, as shown in the + * following table: * * a | b | a.divmod(b) | a/b | a.modulo(b) | a.remainder(b) * ------+-----+---------------+---------+-------------+--------------- @@ -707,11 +709,11 @@ num_remainder(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L709 * * Examples * - * 11.divmod(3) #=> [3, 2] - * 11.divmod(-3) #=> [-4, -1] - * 11.divmod(3.5) #=> [3, 0.5] - * (-11).divmod(3.5) #=> [-4, 3.0] - * (11.5).divmod(3.5) #=> [3, 1.0] + * 11.divmod(3) #=> [3, 2] + * 11.divmod(-3) #=> [-4, -1] + * 11.divmod(3.5) #=> [3, 0.5] + * (-11).divmod(3.5) #=> [-4, 3.0] + * 11.5.divmod(3.5) #=> [3, 1.0] */ static VALUE @@ -724,7 +726,7 @@ num_divmod(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L726 * call-seq: * num.real? -> true or false * - * Returns +true+ if +num+ is a Real number. (i.e. not Complex). + * Returns +true+ if +num+ is a real number (i.e. not Complex). */ static VALUE @@ -739,8 +741,8 @@ num_real_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L741 * * Returns +true+ if +num+ is an Integer. * - * (1.0).integer? #=> false - * (1).integer? #=> true + * 1.0.integer? #=> false + * 1.integer? #=> true */ static VALUE @@ -760,7 +762,7 @@ num_int_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L762 * (-34.56).abs #=> 34.56 * -34.56.abs #=> 34.56 * - * Numeric#magnitude is an alias of Numeric#abs. + * Numeric#magnitude is an alias for Numeric#abs. */ static VALUE @@ -772,7 +774,6 @@ num_abs(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L774 return num; } - /* * call-seq: * num.zero? -> true or false @@ -800,7 +801,6 @@ num_zero_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L801 return Qfalse; } - /* * call-seq: * num.nonzero? -> self or nil @@ -827,7 +827,7 @@ num_nonzero_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L827 * call-seq: * num.finite? -> true or false * - * Return true if +num+ is finite number, oterwise returns false. + * Returns +true+ if +num+ is a finite number, otherwise returns +false+. */ static VALUE num_finite_p(VALUE num) @@ -837,13 +837,10 @@ num_finite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L837 /* * call-seq: - * num.infinite? -> nil or 1 or -1 - * - * Returns values corresponding to the value of +num+'s magnitude: + * num.infinite? -> -1, 1, or nil * - * +finite+:: +nil+ - * +-Infinity+:: +-1+ - * ++Infinity+:: ++1+ + * Returns +nil+, -1, or 1 depending on whether the value is + * finite, <code>-Infinity</code>, or <code>+Infinity</code>. */ static VALUE num_infinite_p(VALUE num) @@ -857,9 +854,9 @@ num_infinite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L854 * * Invokes the child class's +to_i+ method to convert +num+ to an integer. * - * 1.0.class => Float - * 1.0.to_int.class => Integer - * 1.0.to_i.class => Integer + * 1.0.class #=> Float + * 1.0.to_int.class #=> Integer + * 1.0.to_i.class #=> Integer */ static VALUE @@ -870,7 +867,7 @@ num_to_int(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L867 /* * call-seq: - * num.positive? -> true or false + * num.positive? -> true or false * * Returns +true+ if +num+ is greater than 0. */ @@ -893,7 +890,7 @@ num_positive_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L890 /* * call-seq: - * num.negative? -> true or false + * num.negative? -> true or false * * Returns +true+ if +num+ is less than 0. */ @@ -913,7 +910,7 @@ num_negative_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L910 * architecture's double-precision floating point representation. * * Floating point has a different arithmetic and is an inexact number. - * So you should know its esoteric system. see following: + * So you should know its esoteric system. See following: * * - http://docs.sun.com/source/806-3568/ncg_goldberg.html * - http://wiki.github.com/rdp/ruby_tutorials_core/ruby-talk-faq#wiki-floats_imprecise @@ -934,9 +931,9 @@ rb_float_new_in_heap(double d) https://github.com/ruby/ruby/blob/trunk/numeric.c#L931 * call-seq: * float.to_s -> string * - * Returns a string containing a representation of self. As well as a fixed or - * exponential form of the +float+, the call may return +NaN+, +Infinity+, and - * +-Infinity+. + * Returns a string containing a representation of +self+. + * As well as a fixed or exponential form of the +float+, + * the call may return +NaN+, +Infinity+, and +-Infinity+. */ static VALUE @@ -1014,10 +1011,10 @@ flo_to_s(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1011 * call-seq: * float.coerce(numeric) -> array * - * Returns an array with both a +numeric+ and a +float+ represented as Float + * Returns an array with both +numeric+ and +float+ represented as Float * objects. * - * This is achieved by converting a +numeric+ to a Float. + * This is achieved by converting +numeric+ to a Float. * * 1.2.coerce(3) #=> [3.0, 1.2] * 2.5.coerce(1.1) #=> [1.1, 2.5] @@ -1033,7 +1030,7 @@ flo_coerce(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1030 * call-seq: * -float -> float * - * Returns float, negated. + * Returns +float+, negated. */ VALUE @@ -1046,7 +1043,7 @@ rb_float_uminus(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1043 * call-seq: * float + other -> float * - * Returns a new float which is the sum of +float+ and +other+. + * Returns a new Float which is the sum of +float+ and +other+. */ static VALUE @@ -1070,7 +1067,7 @@ flo_plus(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1067 * call-seq: * float - other -> float * - * Returns a new float which is the difference of +float+ and +other+. + * Returns a new Float which is the difference of +float+ and +other+. */ static VALUE @@ -1094,7 +1091,7 @@ flo_minus(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1091 * call-seq: * float * other -> float * - * Returns a new float which is the product of +float+ and +other+. + * Returns a new Float which is the product of +float+ and +other+. */ static VALUE @@ -1118,7 +1115,7 @@ flo_mul(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1115 * call-seq: * float / other -> float * - * Returns a new float which is the result of dividing +float+ by +other+. + * Returns a new Float which is the result of dividing +float+ by +other+. */ static VALUE @@ -1146,7 +1143,7 @@ flo_div(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1143 /* * call-seq: * float.fdiv(numeric) -> float - * float.quo(numeric) -> float + * float.quo(numeric) -> float * * Returns <code>float / numeric</code>, same as Float#/. */ @@ -1208,16 +1205,15 @@ ruby_float_mod(double x, double y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1205 return mod; } - /* * call-seq: * float % other -> float * float.modulo(other) -> float * - * Return the modulo after division of +float+ by +other+. + * Returns the modulo after division of +float+ by +other+. * - * 6543.21.modulo(137) #=> 104.21 - * 6543.21.modulo(137.24) #=> 92.9299999999996 + * 6543.21.modulo(137) #=> 104.21000000000004 + * 6543.21.modulo(137.24) #=> 92.92999999999961 */ static VALUE @@ -1255,8 +1251,8 @@ dbl2ival(double d) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1251 * * See Numeric#divmod. * - * 42.0.divmod 6 #=> [7, 0.0] - * 42.0.divmod 5 #=> [8, 2.0] + * 42.0.divmod(6) #=> [7, 0.0] + * 42.0.divmod(5) #=> [8, 2.0] */ static VALUE @@ -1285,12 +1281,11 @@ flo_divmod(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1281 /* * call-seq: - * - * float ** other -> float + * float ** other -> float * * Raises +float+ to the power of +other+. * - * 2.0**3 #=> 8.0 + * 2.0**3 #=> 8.0 */ VALUE @@ -1322,13 +1317,11 @@ rb_float_pow(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1317 * num.eql?(numeric) -> true or false * * Returns +true+ if +num+ and +numeric+ are the same type and have equal - * values. Contrast this with <code>Numeric#==</code>, which performs - * type conversions. + * values. Contrast this with Numeric#==, which performs type conversions. * - * 1 == 1.0 #=> true - * 1.eql?(1.0) #=> false - * (1.0).eql?(1.0) #=> true - * 68719476736.eql?(68719476736.0) #=> false + * 1 == 1.0 #=> true + * 1.eql?(1.0) #=> false + * 1.0.eql?(1.0) #=> true */ static VALUE @@ -1347,8 +1340,7 @@ num_eql(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1340 * call-seq: * number <=> other -> 0 or nil * - * Returns zero if +number+ equals +other+, otherwise +nil+ is returned if the - * two values are incomparable. + * Returns zero if +number+ equals +other+, otherwise returns +nil+. */ static VALUE @@ -1372,14 +1364,13 @@ num_equal(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1364 * call-seq: * float == obj -> true or false * - * Returns +true+ only if +obj+ has the same value as +float+. Contrast this - * with Float#eql?, which requires obj to be a Float. - * - * The result of <code>NaN == NaN</code> is undefined, so the - * implementation-dependent value is returned. + * Returns +true+ only if +obj+ has the same value as +float+. + * Contrast this with Float#eql?, which requires +obj+ to be a Float. * * 1.0 == 1 #=> true * + * The result of <code>NaN == NaN</code> is undefined, + * so an implementation-dependent value is returned. */ VALUE @@ -1410,7 +1401,7 @@ rb_float_equal(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1401 /* * call-seq: - * float.hash -> integer + * float.hash -> integer * * Returns a hash code for this float. * @@ -1441,13 +1432,14 @@ rb_dbl_cmp(double a, double b) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1432 /* * call-seq: - * float <=> real -> -1, 0, +1 or nil + * float <=> real -> -1, 0, +1, or nil * - * Returns -1, 0, +1 or nil depending on whether +float+ is less than, equal - * to, or greater than +real+. This is the basis for the tests in Comparable. + * Returns -1, 0, or +1 depending on whether +float+ is + * less than, equal to, or greater than +real+. + * This is the basis for the tests in the Comparable module. * - * The result of <code>NaN <=> NaN</code> is undefined, so the - * implementation-dependent value is returned. + * The result of <code>NaN <=> NaN</code> is undefined, + * so an implementation-dependent value is returned. * * +nil+ is returned if the two values are incomparable. */ @@ -1496,8 +1488,8 @@ rb_float_cmp(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1488 * * Returns +true+ if +float+ is greater than +real+. * - * The result of <code>NaN > NaN</code> is undefined, so the - * implementation-dependent value is returned. + * The result of <code>NaN > NaN</code> is undefined, + * so an implementation-dependent value is returned. */ VALUE @@ -1533,8 +1525,8 @@ rb_float_gt(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1525 * * Returns +true+ if +float+ is greater than or equal to +real+. * - * The result of <code>NaN >= NaN</code> is undefined, so the - * implementation-dependent value is returned. + * The result of <code>NaN >= NaN</code> is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1570,8 +1562,8 @@ flo_ge(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1562 * * Returns +true+ if +float+ is less than +real+. * - * The result of <code>NaN < NaN</code> is undefined, so the - * implementation-dependent value is returned. + * The result of <code>NaN < NaN</code> is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1607,8 +1599,8 @@ flo_lt(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1599 * * Returns +true+ if +float+ is less than or equal to +real+. * - * The result of <code>NaN <= NaN</code> is undefined, so the - * implementation-dependent value is returned. + * The result of <code>NaN <= NaN</code> is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1645,10 +1637,10 @@ flo_le(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1637 * Returns +true+ only if +obj+ is a Float with the same value as +float+. * Contrast this with Float#==, which performs type conversions. * - * The result of <code>NaN.eql?(NaN)</code> is undefined, so the - * implementation-dependent value is returned. - * * 1.0.eql?(1) #=> false + * + * The result of <code>NaN.eql?(NaN)</code> is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1668,9 +1660,9 @@ flo_eql(VALUE x, VALUE y) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1660 /* * call-seq: - * float.to_f -> self + * float.to_f -> self * - * Since +float+ is already a float, returns +self+. + * Since +float+ is already a Float, returns +self+. */ static VALUE @@ -1688,7 +1680,9 @@ flo_to_f(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1680 * * (-34.56).abs #=> 34.56 * -34.56.abs #=> 34.56 + * 34.56.abs #=> 34.56 * + * Float#magnitude is an alias for Float#abs. */ VALUE @@ -1703,7 +1697,6 @@ rb_float_abs(VALUE flt) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1697 * float.zero? -> true or false * * Returns +true+ if +float+ is 0.0. - * */ static VALUE @@ -1737,15 +1730,10 @@ flo_is_nan_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1730 /* * call-seq: - * float.infinite? -> nil, -1, +1 - * - * Return values corresponding to the value of +float+: - * - * +finite+:: +nil+ - * +-Infinity+:: +-1+ - * ++Infinity+:: +1+ + * float.infinite? -> -1, 1, or nil * - * For example: + * Returns +nil+, -1, or 1 depending on whether the value is + * finite, <code>-Infinity</code>, or <code>+Infinity</code>. * * (0.0).infinite? #=> nil * (-1.0/0.0).infinite? #=> -1 @@ -1768,9 +1756,8 @@ flo_is_infinite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1756 * call-seq: * float.finite? -> true or false * - * Returns +true+ if +float+ is a valid IEEE floating point number (it is not - * infinite, and Float#nan? is +false+). - * + * Returns +true+ if +float+ is a valid IEEE floating point number, + * i.e. it is not infinite and Float#nan? is +false+. */ static VALUE @@ -1793,7 +1780,7 @@ flo_is_finite_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L1780 * call-seq: * float.next_float -> float * - * Returns the next representable fl (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/