From f280556f739d7768e78e522a29f68288c703718b Mon Sep 17 00:00:00 2001 From: stomar Date: Sat, 6 May 2017 07:17:41 +0000 Subject: 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 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58580 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- numeric.c | 548 +++++++++++++++++++++++++++++--------------------------------- 1 file changed, 257 insertions(+), 291 deletions(-) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index 713a3e482e..77f956a9ea 100644 --- a/numeric.c +++ b/numeric.c @@ -409,9 +409,9 @@ num_funcall1(VALUE x, ID func, VALUE y) * 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 + * [numeric, num]. 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 func) } /* + * :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) #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) #if 0 /* * call-seq: - * num.dup -> num + * num.dup -> num * * Returns the receiver. */ @@ -553,7 +554,7 @@ num_dup(VALUE x) * 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) /* * 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) 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) 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 num.divmod(numeric)[0]. * @@ -628,12 +630,11 @@ num_div(VALUE x, VALUE y) 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 + * x.modulo(y) means x-y*(x/y).floor. * * Equivalent to num.divmod(numeric)[1]. * @@ -652,7 +653,7 @@ num_modulo(VALUE x, VALUE y) * call-seq: * num.remainder(numeric) -> real * - * x.remainder(y) means x-y*(x/y).truncate + * x.remainder(y) means x-y*(x/y).truncate. * * See Numeric#divmod. */ @@ -679,12 +680,13 @@ num_remainder(VALUE x, VALUE y) * Returns an array containing the quotient and modulus obtained by dividing * +num+ by +numeric+. * - * If q, r = * x.divmod(y), then + * If q, r = x.divmod(y), 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) * * 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) * 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) * * 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) * (-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) return num; } - /* * call-seq: * num.zero? -> true or false @@ -800,7 +801,6 @@ num_zero_p(VALUE num) return Qfalse; } - /* * call-seq: * num.nonzero? -> self or nil @@ -827,7 +827,7 @@ num_nonzero_p(VALUE num) * 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) /* * 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, -Infinity, or +Infinity. */ static VALUE num_infinite_p(VALUE num) @@ -857,9 +854,9 @@ num_infinite_p(VALUE num) * * 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) /* * 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) /* * 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) * 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) * 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) * 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) * call-seq: * -float -> float * - * Returns float, negated. + * Returns +float+, negated. */ VALUE @@ -1046,7 +1043,7 @@ rb_float_uminus(VALUE flt) * 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) * 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) * 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) * 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) /* * call-seq: * float.fdiv(numeric) -> float - * float.quo(numeric) -> float + * float.quo(numeric) -> float * * Returns float / numeric, same as Float#/. */ @@ -1208,16 +1205,15 @@ ruby_float_mod(double x, double y) 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) * * 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) /* * 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) * num.eql?(numeric) -> true or false * * Returns +true+ if +num+ and +numeric+ are the same type and have equal - * values. Contrast this with Numeric#==, 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) * 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) * 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 NaN == NaN 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 NaN == NaN is undefined, + * so an implementation-dependent value is returned. */ VALUE @@ -1410,7 +1401,7 @@ rb_float_equal(VALUE x, VALUE y) /* * 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) /* * 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 NaN <=> NaN is undefined, so the - * implementation-dependent value is returned. + * The result of NaN <=> NaN 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) * * Returns +true+ if +float+ is greater than +real+. * - * The result of NaN > NaN is undefined, so the - * implementation-dependent value is returned. + * The result of NaN > NaN is undefined, + * so an implementation-dependent value is returned. */ VALUE @@ -1533,8 +1525,8 @@ rb_float_gt(VALUE x, VALUE y) * * Returns +true+ if +float+ is greater than or equal to +real+. * - * The result of NaN >= NaN is undefined, so the - * implementation-dependent value is returned. + * The result of NaN >= NaN is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1570,8 +1562,8 @@ flo_ge(VALUE x, VALUE y) * * Returns +true+ if +float+ is less than +real+. * - * The result of NaN < NaN is undefined, so the - * implementation-dependent value is returned. + * The result of NaN < NaN is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1607,8 +1599,8 @@ flo_lt(VALUE x, VALUE y) * * Returns +true+ if +float+ is less than or equal to +real+. * - * The result of NaN <= NaN is undefined, so the - * implementation-dependent value is returned. + * The result of NaN <= NaN is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1645,10 +1637,10 @@ flo_le(VALUE x, VALUE y) * 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 NaN.eql?(NaN) is undefined, so the - * implementation-dependent value is returned. - * * 1.0.eql?(1) #=> false + * + * The result of NaN.eql?(NaN) is undefined, + * so an implementation-dependent value is returned. */ static VALUE @@ -1668,9 +1660,9 @@ flo_eql(VALUE x, VALUE y) /* * 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) * * (-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) * float.zero? -> true or false * * Returns +true+ if +float+ is 0.0. - * */ static VALUE @@ -1737,15 +1730,10 @@ flo_is_nan_p(VALUE num) /* * call-seq: - * float.infinite? -> nil, -1, +1 - * - * Return values corresponding to the value of +float+: + * float.infinite? -> -1, 1, or nil * - * +finite+:: +nil+ - * +-Infinity+:: +-1+ - * ++Infinity+:: +1+ - * - * For example: + * Returns +nil+, -1, or 1 depending on whether the value is + * finite, -Infinity, or +Infinity. * * (0.0).infinite? #=> nil * (-1.0/0.0).infinite? #=> -1 @@ -1768,9 +1756,8 @@ flo_is_infinite_p(VALUE num) * 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) * call-seq: * float.next_float -> float * - * Returns the next representable floating-point number. + * Returns the next representable floating point number. * * Float::MAX.next_float and Float::INFINITY.next_float is Float::INFINITY. * @@ -1801,13 +1788,13 @@ flo_is_finite_p(VALUE num) * * For example: * - * p 0.01.next_float #=> 0.010000000000000002 - * p 1.0.next_float #=> 1.0000000000000002 - * p 100.0.next_float #=> 100.00000000000001 + * 0.01.next_float #=> 0.010000000000000002 + * 1.0.next_float #=> 1.0000000000000002 + * 100.0.next_float #=> 100.00000000000001 * - * p 0.01.next_float - 0.01 #=> 1.734723475976807e-18 - * p 1.0.next_float - 1.0 #=> 2.220446049250313e-16 - * p 100.0.next_float - 100.0 #=> 1.4210854715202004e-14 + * 0.01.next_float - 0.01 #=> 1.734723475976807e-18 + * 1.0.next_float - 1.0 #=> 2.220446049250313e-16 + * 100.0.next_float - 100.0 #=> 1.4210854715202004e-14 * * f = 0.01; 20.times { printf "%-20a %s\n", f, f.to_s; f = f.next_float } * #=> 0x1.47ae147ae147bp-7 0.01 @@ -1833,13 +1820,13 @@ flo_is_finite_p(VALUE num) * * f = 0.0 * 100.times { f += 0.1 } - * p f #=> 9.99999999999998 # should be 10.0 in the ideal world. - * p 10-f #=> 1.9539925233402755e-14 # the floating-point error. - * p(10.0.next_float-10) #=> 1.7763568394002505e-15 # 1 ulp (units in the last place). - * p((10-f)/(10.0.next_float-10)) #=> 11.0 # the error is 11 ulp. - * p((10-f)/(10*Float::EPSILON)) #=> 8.8 # approximation of the above. - * p "%a" % f #=> "0x1.3fffffffffff5p+3" # the last hex digit is 5. 16 - 5 = 11 ulp. - * + * f #=> 9.99999999999998 # should be 10.0 in the ideal world. + * 10-f #=> 1.9539925233402755e-14 # the floating point error. + * 10.0.next_float-10 #=> 1.7763568394002505e-15 # 1 ulp (unit in the last place). + * (10-f)/(10.0.next_float-10) #=> 11.0 # the error is 11 ulp. + * (10-f)/(10*Float::EPSILON) #=> 8.8 # approximation of the above. + * "%a" % 10 #=> "0x1.4p+3" + * "%a" % f #=> "0x1.3fffffffffff5p+3" # the last hex digit is 5. 16 - 5 = 11 ulp. */ static VALUE flo_next_float(VALUE vx) @@ -1854,7 +1841,7 @@ flo_next_float(VALUE vx) * call-seq: * float.prev_float -> float * - * Returns the previous representable floating-point number. + * Returns the previous representable floating point number. * * (-Float::MAX).prev_float and (-Float::INFINITY).prev_float is -Float::INFINITY. * @@ -1862,13 +1849,13 @@ flo_next_float(VALUE vx) * * For example: * - * p 0.01.prev_float #=> 0.009999999999999998 - * p 1.0.prev_float #=> 0.9999999999999999 - * p 100.0.prev_float #=> 99.99999999999999 + * 0.01.prev_float #=> 0.009999999999999998 + * 1.0.prev_float #=> 0.9999999999999999 + * 100.0.prev_float #=> 99.99999999999999 * - * p 0.01 - 0.01.prev_float #=> 1.734723475976807e-18 - * p 1.0 - 1.0.prev_float #=> 1.1102230246251565e-16 - * p 100.0 - 100.0.prev_float #=> 1.4210854715202004e-14 + * 0.01 - 0.01.prev_float #=> 1.734723475976807e-18 + * 1.0 - 1.0.prev_float #=> 1.1102230246251565e-16 + * 100.0 - 100.0.prev_float #=> 1.4210854715202004e-14 * * f = 0.01; 20.times { printf "%-20a %s\n", f, f.to_s; f = f.prev_float } * #=> 0x1.47ae147ae147bp-7 0.01 @@ -1891,7 +1878,6 @@ flo_next_float(VALUE vx) * # 0x1.47ae147ae146ap-7 0.00999999999999997 * # 0x1.47ae147ae1469p-7 0.009999999999999969 * # 0x1.47ae147ae1468p-7 0.009999999999999967 - * */ static VALUE flo_prev_float(VALUE vx) @@ -2316,17 +2302,20 @@ float_invariant_round(double number, int ndigits, VALUE *num) /* * call-seq: - * float.to_i -> integer - * float.to_int -> integer + * float.to_i -> integer + * float.to_int -> integer * * Returns the +float+ truncated to an Integer. * - * Synonyms are #to_i and #to_int + * 1.2.to_i #=> 1 + * (-1.2).to_i #=> -1 * * Note that the limited precision of floating point arithmetic * might lead to surprising results: * * (0.3 / 0.1).to_i #=> 2 (!) + * + * #to_int is an alias for #to_i. */ static VALUE @@ -2379,7 +2368,7 @@ flo_truncate(int argc, VALUE *argv, VALUE num) /* * call-seq: - * float.positive? -> true or false + * float.positive? -> true or false * * Returns +true+ if +float+ is greater than 0. */ @@ -2393,7 +2382,7 @@ flo_positive_p(VALUE num) /* * call-seq: - * float.negative? -> true or false + * float.negative? -> true or false * * Returns +true+ if +float+ is less than 0. */ @@ -2422,7 +2411,6 @@ num_floor(int argc, VALUE *argv, VALUE num) return flo_floor(argc, argv, rb_Float(num)); } - /* * call-seq: * num.ceil([ndigits]) -> integer or float @@ -2654,6 +2642,7 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) return ruby_num_interval_step_size(from, to, step, FALSE); } + /* * call-seq: * num.step(by: step, to: limit) {|i| block } -> self @@ -2666,28 +2655,26 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) * * The loop finishes when the value to be passed to the block is greater than * +limit+ (if +step+ is positive) or less than +limit+ (if +step+ is - * negative), where limit is defaulted to infinity. + * negative), where +limit+ is defaulted to infinity. * * In the recommended keyword argument style, either or both of * +step+ and +limit+ (default infinity) can be omitted. In the * fixed position argument style, zero as a step - * (i.e. num.step(limit, 0)) is not allowed for historical + * (i.e. num.step(limit, 0)) is not allowed for historical * compatibility reasons. * * If all the arguments are integers, the loop operates using an integer * counter. * - * If any of the arguments are floating point numbers, all are converted to floats, and the loop is executed the following expression: - * - * floor(n + n*epsilon)+ 1 + * If any of the arguments are floating point numbers, all are converted + * to floats, and the loop is executed + * floor(n + n*Float::EPSILON) + 1 times, + * where n = (limit - num)/step. * - * Where the +n+ is the following: - * - * n = (limit - num)/step - * - * Otherwise, the loop starts at +num+, uses either the less-than (<) or - * greater-than (>) operator to compare the counter against +limit+, and - * increments itself using the + operator. + * Otherwise, the loop starts at +num+, uses either the + * less-than (<) or greater-than (>) operator + * to compare the counter against +limit+, + * and increments itself using the + operator. * * If no block is given, an Enumerator is returned instead. * @@ -2695,9 +2682,9 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) * * p 1.step.take(4) * p 10.step(by: -1).take(4) - * 3.step(to: 5) { |i| print i, " " } - * 1.step(10, 2) { |i| print i, " " } - * Math::E.step(to: Math::PI, by: 0.2) { |f| print f, " " } + * 3.step(to: 5) {|i| print i, " " } + * 1.step(10, 2) {|i| print i, " " } + * Math::E.step(to: Math::PI, by: 0.2) {|f| print f, " " } * * Will produce: * @@ -2705,7 +2692,7 @@ num_step_size(VALUE from, VALUE args, VALUE eobj) * [10, 9, 8, 7] * 3 4 5 * 1 3 5 7 9 - * 2.71828182845905 2.91828182845905 3.11828182845905 + * 2.718281828459045 2.9182818284590453 3.118281828459045 */ static VALUE @@ -3122,18 +3109,18 @@ rb_num2ull(VALUE val) * Document-class: Integer * * Holds Integer values. You cannot add a singleton method to an - * Integer. Any attempt to add a singleton method to an Integer object - * will raise a TypeError. + * Integer object, any attempt to do so will raise a TypeError. * */ /* * call-seq: - * int.to_i -> integer + * int.to_i -> integer + * int.to_int -> integer * - * As +int+ is already an Integer, all these methods simply return the receiver. + * Since +int+ is already an Integer, returns +self+. * - * Synonyms is #to_int + * #to_int is an alias for #to_i. */ static VALUE @@ -3210,7 +3197,8 @@ int_even_p(VALUE num) * int.next -> integer * int.succ -> integer * - * Returns the Integer equal to +int+ + 1. + * Returns the successor of +int+, + * i.e. the Integer equal to int+1. * * 1.next #=> 2 * (-1).next #=> 0 @@ -3237,7 +3225,8 @@ rb_int_succ(VALUE num) * call-seq: * int.pred -> integer * - * Returns the Integer equal to +int+ - 1. + * Returns the predecessor of +int+, + * i.e. the Integer equal to int-1. * * 1.pred #=> 0 * (-1).pred #=> -2 @@ -3267,8 +3256,8 @@ rb_int_pred(VALUE num) * according to +encoding+. * * 65.chr #=> "A" - * 230.chr #=> "\346" - * 255.chr(Encoding::UTF_8) #=> "\303\277" + * 230.chr #=> "\xE6" + * 255.chr(Encoding::UTF_8) #=> "\u00FF" */ VALUE @@ -3343,12 +3332,12 @@ int_chr(int argc, VALUE *argv, VALUE num) * * Returns the +int+ itself. * - * ?a.ord #=> 97 + * 97.ord #=> 97 * - * This method is intended for compatibility to character constant in Ruby - * 1.9. + * This method is intended for compatibility to character literals + * in Ruby 1.9. * - * For example, ?a.ord returns 97 both in 1.8 and 1.9. + * For example, ?a.ord returns 97 both in 1.8 and 1.9. */ static VALUE @@ -3365,10 +3354,9 @@ int_ord(VALUE num) /* * Document-method: Integer#-@ * call-seq: - * -int -> integer + * -int -> integer * - * Negates +int+. - * (returns an integer whose value is 0-int) + * Returns +int+, negated. */ static VALUE @@ -3394,8 +3382,8 @@ rb_int_uminus(VALUE num) * call-seq: * int.to_s(base=10) -> string * - * Returns a string containing the representation of +int+ radix +base+ - * (between 2 and 36). + * Returns a string containing the place-value representation of +int+ + * with radix +base+ (between 2 and 36). * * 12345.to_s #=> "12345" * 12345.to_s(2) #=> "11000000111001" @@ -3404,7 +3392,6 @@ rb_int_uminus(VALUE num) * 12345.to_s(16) #=> "3039" * 12345.to_s(36) #=> "9ix" * 78546939656932.to_s(36) #=> "rubyrules" - * */ VALUE @@ -3477,7 +3464,7 @@ rb_int2str(VALUE x, int base) /* * Document-method: Integer#+ * call-seq: - * int + numeric -> numeric_result + * int + numeric -> numeric_result * * Performs addition: the class of the resulting object depends on the class of * +numeric+ and on the magnitude of the result. It may return a Bignum. @@ -3524,7 +3511,7 @@ rb_int_plus(VALUE x, VALUE y) /* * Document-method: Integer#- * call-seq: - * int - numeric -> numeric_result + * int - numeric -> numeric_result * * Performs subtraction: the class of the resulting object depends on the class * of +numeric+ and on the magnitude of the result. It may return a Bignum. @@ -3568,7 +3555,7 @@ rb_int_minus(VALUE x, VALUE y) /* * Document-method: Integer#* * call-seq: - * int * numeric -> numeric_result + * int * numeric -> numeric_result * * Performs multiplication: the class of the resulting object depends on the * class of +numeric+ and on the magnitude of the result. It may return a @@ -3650,16 +3637,13 @@ rb_int_fdiv_double(VALUE x, VALUE y) /* * Document-method: Integer#fdiv * call-seq: - * integer.fdiv(numeric) -> float + * int.fdiv(numeric) -> float * - * Returns the floating point result of dividing +integer+ by +numeric+. - * - * 654321.fdiv(13731) #=> 47.6528293642124 - * 654321.fdiv(13731.24) #=> 47.6519964693647 - * - * -1234567890987654321.fdiv(13731) #=> -89910996357705.5 - * -1234567890987654321.fdiv(13731.24) #=> -89909424858035.7 + * Returns the floating point result of dividing +int+ by +numeric+. * + * 654321.fdiv(13731) #=> 47.652829364212366 + * 654321.fdiv(13731.24) #=> 47.65199646936475 + * -654321.fdiv(13731) #=> -47.652829364212366 */ VALUE @@ -3674,7 +3658,7 @@ rb_int_fdiv(VALUE x, VALUE y) /* * Document-method: Integer#/ * call-seq: - * int / numeric -> numeric_result + * int / numeric -> numeric_result * * Performs division: the class of the resulting object depends on the class of * +numeric+ and on the magnitude of the result. It may return a Bignum. @@ -3735,10 +3719,10 @@ rb_int_div(VALUE x, VALUE y) /* * Document-method: Integer#div * call-seq: - * int.div(numeric) -> integer + * int.div(numeric) -> integer * - * Performs integer division: returns integer result of dividing +int+ by - * +numeric+. + * Performs integer division: returns the integer result of dividing +int+ + * by +numeric+. */ static VALUE @@ -3763,8 +3747,8 @@ rb_int_idiv(VALUE x, VALUE y) * Document-method: Integer#% * Document-method: Integer#modulo * call-seq: - * int % other -> real - * int.modulo(other) -> real + * int % other -> real + * int.modulo(other) -> real * * Returns +int+ modulo +other+. * @@ -3806,20 +3790,15 @@ rb_int_modulo(VALUE x, VALUE y) * call-seq: * int.remainder(numeric) -> real * + * Returns the remainder after dividing +int+ by +numeric+. * - * Returns the remainder after dividing big by numeric as: - * - * x.remainder(y) means x-y*(x/y).truncate - * - * Examples - * - * 5.remainder(3) #=> 2 - * -5.remainder(3) #=> -2 - * 5.remainder(-3) #=> 2 - * -5.remainder(-3) #=> -2 + * x.remainder(y) means x-y*(x/y).truncate. * - * -1234567890987654321.remainder(13731) #=> -6966 - * -1234567890987654321.remainder(13731.24) #=> -9906.22531493148 + * 5.remainder(3) #=> 2 + * -5.remainder(3) #=> -2 + * 5.remainder(-3) #=> 2 + * -5.remainder(-3) #=> -2 + * 5.remainder(1.5) #=> 0.5 * * See Numeric#divmod. */ @@ -3839,9 +3818,9 @@ int_remainder(VALUE x, VALUE y) /* * Document-method: Integer#divmod * call-seq: - * integer.divmod(numeric) -> array + * int.divmod(numeric) -> array * - * See Numeric#divmod. + * See Numeric#divmod. */ static VALUE fix_divmod(VALUE x, VALUE y) @@ -3887,20 +3866,20 @@ rb_int_divmod(VALUE x, VALUE y) /* * Document-method: Integer#** * call-seq: - * integer ** numeric -> numeric_result + * int ** numeric -> numeric_result * - * Raises +integer+ to the power of +numeric+, which may be negative or + * Raises +int+ to the power of +numeric+, which may be negative or * fractional. - * The result may be an Integer, or a Float - * - * 2 ** 3 #=> 8 - * 2 ** -1 #=> (1/2) - * 2 ** 0.5 #=> 1.4142135623731 + * The result may be an Integer, a Float, a Rational, or a complex number. * - * 123456789 ** 2 #=> 15241578750190521 - * 123456789 ** 1.2 #=> 5126464716.09932 - * 123456789 ** -2 #=> (1/15241578750190521) + * 2 ** 3 #=> 8 + * 2 ** -1 #=> (1/2) + * 2 ** 0.5 #=> 1.4142135623730951 + * (-1) ** 0.5 #=> (0.0+1.0i) * + * 123456789 ** 2 #=> 15241578750190521 + * 123456789 ** 1.2 #=> 5126464716.0993185 + * 123456789 ** -2 #=> (1/15241578750190521) */ static VALUE @@ -4017,15 +3996,15 @@ rb_int_pow(VALUE x, VALUE y) /* * Document-method: Integer#== + * Document-method: Integer#=== * call-seq: - * int == other -> true or false + * int == other -> true or false * - * Return +true+ if +int+ equals +other+ numerically. - * Contrast this with Integer#eql?, which - * requires other to be a Integer. + * Returns +true+ if +int+ equals +other+ numerically. + * Contrast this with Integer#eql?, which requires +other+ to be an Integer. * - * 1 == 2 #=> false - * 1 == 1.0 #=> true + * 1 == 2 #=> false + * 1 == 1.0 #=> true */ static VALUE @@ -4059,9 +4038,9 @@ rb_int_equal(VALUE x, VALUE y) /* * Document-method: Integer#<=> * call-seq: - * int <=> numeric -> -1, 0, +1 or nil + * int <=> numeric -> -1, 0, +1, or nil * - * Comparison---Returns +-1+, +0+, ++1+ or +nil+ depending on whether +int+ is + * Comparison---Returns -1, 0, or +1 depending on whether +int+ is * less than, equal to, or greater than +numeric+. * * This is the basis for the tests in the Comparable module. @@ -4111,7 +4090,7 @@ rb_int_cmp(VALUE x, VALUE y) /* * Document-method: Integer#> * call-seq: - * int > real -> true or false + * int > real -> true or false * * Returns +true+ if the value of +int+ is greater than that of +real+. */ @@ -4149,7 +4128,7 @@ rb_int_gt(VALUE x, VALUE y) /* * Document-method: Integer#>= * call-seq: - * int >= real -> true or false + * int >= real -> true or false * * Returns +true+ if the value of +int+ is greater than or equal to that of * +real+. @@ -4189,7 +4168,7 @@ rb_int_ge(VALUE x, VALUE y) /* * Document-method: Integer#< * call-seq: - * int < real -> true or false + * int < real -> true or false * * Returns +true+ if the value of +int+ is less than that of +real+. */ @@ -4227,7 +4206,7 @@ int_lt(VALUE x, VALUE y) /* * Document-method: Integer#<= * call-seq: - * int <= real -> true or false + * int <= real -> true or false * * Returns +true+ if the value of +int+ is less than or equal to that of * +real+. @@ -4267,17 +4246,16 @@ int_le(VALUE x, VALUE y) /* * Document-method: Integer#~ * call-seq: - * ~integer -> integer + * ~int -> integer * * One's complement: returns a number where each bit is flipped. * - * Inverts the bits in an integer. As Integers are conceptually infinite - * length, the result acts as if it had an infinite number of one - * bits to the left. In hex representations, this is displayed + * Inverts the bits in an Integer. As integers are conceptually of + * infinite length, the result acts as if it had an infinite number of + * one bits to the left. In hex representations, this is displayed * as two periods to the left of the digits. * * sprintf("%X", ~0x1122334455) #=> "..FEEDDCCBBAA" - * */ static VALUE @@ -4330,7 +4308,7 @@ rb_num_coerce_bit(VALUE x, VALUE y, ID func) /* * Document-method: Integer#& * call-seq: - * integer & integer -> integer_result + * int & other_int -> integer * * Bitwise AND. */ @@ -4365,7 +4343,7 @@ rb_int_and(VALUE x, VALUE y) /* * Document-method: Integer#| * call-seq: - * integer | integer -> integer_result + * int | other_int -> integer * * Bitwise OR. */ @@ -4400,7 +4378,7 @@ int_or(VALUE x, VALUE y) /* * Document-method: Integer#^ * call-seq: - * integer ^ integer -> integer_result + * int ^ other_int -> integer * * Bitwise EXCLUSIVE OR. */ @@ -4437,7 +4415,8 @@ int_xor(VALUE x, VALUE y) * call-seq: * int << count -> integer * - * Shifts +int+ left +count+ positions, or right if +count+ is negative. + * Returns +int+ shifted left +count+ positions, or right if +count+ + * is negative. */ static VALUE @@ -4482,7 +4461,8 @@ rb_int_lshift(VALUE x, VALUE y) * call-seq: * int >> count -> integer * - * Shifts +int+ right +count+ positions, or left if +count+ is negative. + * Returns +int+ shifted right +count+ positions, or left if +count+ + * is negative. */ static VALUE @@ -4528,19 +4508,16 @@ rb_int_rshift(VALUE x, VALUE y) * call-seq: * int[n] -> 0, 1 * - * Bit Reference---Returns the +n+th bit in the binary representation of - * +int+, where int[0] is the least significant bit. - * - * For example: + * Bit Reference---Returns the nth bit in the + * binary representation of +int+, where int[0] + * is the least significant bit. * * a = 0b11001100101010 - * 30.downto(0) do |n| print a[n] end + * 30.downto(0) {|n| print a[n] } * #=> 0000000000000000011001100101010 * * a = 9**15 - * 50.downto(0) do |n| - * print a[n] - * end + * 50.downto(0) {|n| print a[n] } * #=> 000101110110100000111000011110010100111100010111001 */ @@ -4588,9 +4565,8 @@ int_aref(VALUE num, VALUE idx) * call-seq: * int.to_f -> float * - * Converts +int+ to a +Float+. If +int+ doesn't fit in a +Float+, + * Converts +int+ to a Float. If +int+ doesn't fit in a Float, * the result is infinity. - * */ static VALUE @@ -4620,10 +4596,11 @@ int_to_f(VALUE num) * * Returns the absolute value of +int+. * - * -12345.abs #=> 12345 - * 12345.abs #=> 12345 - * -1234567890987654321.abs #=> 1234567890987654321 + * (-12345).abs #=> 12345 + * -12345.abs #=> 12345 + * 12345.abs #=> 12345 * + * Integer#magnitude is an alias for Integer#abs. */ static VALUE @@ -4653,12 +4630,13 @@ rb_int_abs(VALUE num) * call-seq: * int.size -> int * - * Returns the number of bytes in the machine representation of +int+. + * Returns the number of bytes in the machine representation of +int+ + * (machine dependent). * - * 1.size #=> 4 - * -1.size #=> 4 - * 2147483647.size #=> 4 - * (256**10 - 1).size #=> 12 + * 1.size #=> 8 + * -1.size #=> 8 + * 2147483647.size #=> 8 + * (256**10 - 1).size #=> 10 * (256**20 - 1).size #=> 20 * (256**40 - 1).size #=> 40 */ @@ -4684,20 +4662,17 @@ int_size(VALUE num) /* * Document-method: Integer#bit_length * call-seq: - * int.bit_length -> integer + * int.bit_length -> integer * - * Returns the number of bits of the value of int. + * Returns the number of bits of the value of +int+. * - * "the number of bits" means that - * the bit position of the highest bit which is different to the sign bit. - * (The bit position of the bit 2**n is n+1.) + * "Number of bits" means the bit position of the highest bit + * which is different from the sign bit + * (where the least significant bit has bit position 1). * If there is no such bit (zero or minus one), zero is returned. * - * I.e. This method returns ceil(log2(int < 0 ? -int : int+1)). + * I.e. this method returns ceil(log2(int < 0 ? -int : int+1)). * - * (-2**10000-1).bit_length #=> 10001 - * (-2**10000).bit_length #=> 10000 - * (-2**10000+1).bit_length #=> 10000 * (-2**1000-1).bit_length #=> 1001 * (-2**1000).bit_length #=> 1000 * (-2**1000+1).bit_length #=> 1000 @@ -4719,11 +4694,8 @@ int_size(VALUE num) * (2**1000-1).bit_length #=> 1000 * (2**1000).bit_length #=> 1001 * (2**1000+1).bit_length #=> 1001 - * (2**10000-1).bit_length #=> 10000 - * (2**10000).bit_length #=> 10001 - * (2**10000+1).bit_length #=> 10001 * - * This method can be used to detect overflow in Array#pack as follows. + * This method can be used to detect overflow in Array#pack as follows: * * if n.bit_length < 32 * [n].pack("l") # no overflow @@ -4756,13 +4728,15 @@ rb_int_bit_length(VALUE num) /* * Document-method: Integer#digits * call-seq: - * int.digits -> [int] - * int.digits(base) -> [int] + * int.digits -> array + * int.digits(base) -> array * - * Returns the array including the digits extracted by place-value notation - * with radix +base+ of +int+. + * Returns the digits of +int+'s place-value representation + * with radix +base+ (default: 10). + * The digits are returned as an array with the least significant digit + * as the first array element. * - * +base+ should be greater than or equal to 2. + * +base+ must be greater than or equal to 2. * * 12345.digits #=> [5, 4, 3, 2, 1] * 12345.digits(7) #=> [4, 6, 6, 0, 5] @@ -4871,10 +4845,7 @@ rb_int_digits(int argc, VALUE *argv, VALUE num) * * If no block is given, an Enumerator is returned instead. * - * For example: - * - * 5.upto(10) { |i| print i, " " } - * #=> 5 6 7 8 9 10 + * 5.upto(10) {|i| print i, " " } #=> 5 6 7 8 9 10 */ static VALUE @@ -4913,14 +4884,14 @@ int_upto(VALUE from, VALUE to) * int.downto(limit) {|i| block } -> self * int.downto(limit) -> an_enumerator * - * Iterates the given block, passing decreasing values from +int+ down to and - * including +limit+. + * Iterates the given block, passing in decreasing values from +int+ down to + * and including +limit+. * * If no block is given, an Enumerator is returned instead. * * 5.downto(1) { |n| print n, ".. " } - * print " Liftoff!\n" - * #=> "5.. 4.. 3.. 2.. 1.. Liftoff!" + * puts "Liftoff!" + * #=> "5.. 4.. 3.. 2.. 1.. Liftoff!" */ static VALUE @@ -4964,10 +4935,7 @@ int_downto(VALUE from, VALUE to) * * If no block is given, an Enumerator is returned instead. * - * 5.times do |i| - * print i, " " - * end - * #=> 0 1 2 3 4 + * 5.times {|i| print i, " " } #=> 0 1 2 3 4 */ static VALUE @@ -5273,24 +5241,22 @@ rb_int_s_isqrt(VALUE self, VALUE num) * * Raised when attempting to divide an integer by 0. * - * 42 / 0 - * #=> ZeroDivisionError: divided by 0 + * 42 / 0 #=> ZeroDivisionError: divided by 0 * * Note that only division by an exact 0 will raise the exception: * - * 42 / 0.0 #=> Float::INFINITY - * 42 / -0.0 #=> -Float::INFINITY - * 0 / 0.0 #=> NaN + * 42 / 0.0 #=> Float::INFINITY + * 42 / -0.0 #=> -Float::INFINITY + * 0 / 0.0 #=> NaN */ /* * Document-class: FloatDomainError * * Raised when attempting to convert special float values (in particular - * +infinite+ or +NaN+) to numerical classes which don't support them. + * +Infinity+ or +NaN+) to numerical classes which don't support them. * - * Float::INFINITY.to_r - * #=> FloatDomainError: Infinity + * Float::INFINITY.to_r #=> FloatDomainError: Infinity */ /* @@ -5303,7 +5269,7 @@ rb_int_s_isqrt(VALUE self, VALUE num) * object which is always passed by value. * * a = 1 - * puts 1.object_id == a.object_id #=> true + * 1.object_id == a.object_id #=> true * * There can only ever be one instance of the integer +1+, for example. Ruby ensures this * by preventing instantiation and duplication. @@ -5527,7 +5493,7 @@ Init_Numeric(void) */ rb_define_const(rb_cFloat, "DIG", INT2FIX(DBL_DIG)); /* - * The smallest posable exponent value in a double-precision floating + * The smallest possible exponent value in a double-precision floating * point. * * Usually defaults to -1021. -- cgit v1.2.3