From 791f868395deea76a253c55101beb8c82d0ef868 Mon Sep 17 00:00:00 2001 From: dave Date: Sat, 27 Dec 2003 05:46:46 +0000 Subject: Add RDoc comments git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5315 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 + numeric.c | 356 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 360 insertions(+) diff --git a/ChangeLog b/ChangeLog index 9d01c0018d..0df45093ed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Sat Dec 27 14:39:53 2003 Dave Thomas + + * numeric.c (Init_Numeric): Add RDoc comments. + Sat Dec 27 00:44:00 2003 Yukihiro Matsumoto * io.c (next_argv): warn always for stdin on inplace edit mode. diff --git a/numeric.c b/numeric.c index 3ee1aef466..8557ec1d7f 100644 --- a/numeric.c +++ b/numeric.c @@ -78,6 +78,23 @@ rb_num_zerodiv() rb_raise(rb_eZeroDivError, "divided by 0"); } + +/* + * call-seq: + * num.coerce(numeric) => array + * + * If aNumeric is the same type as num, returns an array + * containing aNumeric and num. Otherwise, returns an + * array with both aNumeric 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 operands of the operator. + * + * 1.coerce(2.5) #=> [2.5, 1.0] + * 1.2.coerce(3) #=> [3.0, 1.2] + * 1.coerce(2) #=> [2, 1] + */ + static VALUE num_coerce(x, y) VALUE x, y; @@ -162,6 +179,11 @@ rb_num_coerce_relop(x, y) return c; } +/* + * Trap attempts to add methods to Numeric objects. Always + * raises a TypeError + */ + static VALUE num_sadded(x, name) VALUE x, name; @@ -184,6 +206,13 @@ num_init_copy(x, y) return Qnil; /* not reached */ } +/* + * call-seq: + * +num => num + * + * Unary Plus---Returns the receiver's value. + */ + static VALUE num_uplus(num) VALUE num; @@ -191,6 +220,13 @@ num_uplus(num) return num; } +/* + * call-seq: + * --num => numeric + * + * Unary Minus---Returns the receiver's value, negated. + */ + static VALUE num_uminus(num) VALUE num; @@ -203,6 +239,13 @@ num_uminus(num) return rb_funcall(zero, '-', 1, num); } +/* + * call-seq: + * num.quo(numeric) => result + * + * Equivalent to Numeric#/, but overridden in subclasses. + */ + static VALUE num_quo(x, y) VALUE x, y; @@ -210,6 +253,16 @@ num_quo(x, y) return rb_funcall(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. + */ + static VALUE num_div(x, y) VALUE x, y; @@ -217,6 +270,48 @@ num_div(x, y) return rb_Integer(rb_funcall(x, '/', 1, y)); } + + +/* + * call-seq: + * num.divmod( aNumeric ) -> anArray + * + * Returns an array containing the quotient and modulus obtained by + * dividing num by aNumeric. If q, r = + * x.divmod(y), then + * + * q = floor(float(x)/float(y)) + * x = q*y + r + * + * The quotient is rounded toward -infinity, as shown in the following table: + * + * a | b | a.divmod(b) | a/b | a.modulo(b) | a.remainder(b) + * ------+-----+---------------+---------+-------------+--------------- + * 13 | 4 | 3, 1 | 3 | 1 | 1 + * ------+-----+---------------+---------+-------------+--------------- + * 13 | -4 | -4, -3 | -3 | -3 | 1 + * ------+-----+---------------+---------+-------------+--------------- + * -13 | 4 | -4, 3 | -4 | 3 | -1 + * ------+-----+---------------+---------+-------------+--------------- + * -13 | -4 | 3, -1 | 3 | -1 | -1 + * ------+-----+---------------+---------+-------------+--------------- + * 11.5 | 4 | 2.0, 3.5 | 2.875 | 3.5 | 3.5 + * ------+-----+---------------+---------+-------------+--------------- + * 11.5 | -4 | -3.0, -0.5 | -2.875 | -0.5 | 3.5 + * ------+-----+---------------+---------+-------------+--------------- + * -11.5 | 4 | -3.0 0.5 | -2.875 | 0.5 | -3.5 + * ------+-----+---------------+---------+-------------+--------------- + * -11.5 | -4 | 2.0 -3.5 | 2.875 | -3.5 | -3.5 + * + * + * Examples + * 11.divmod(3) #=> [3, 2] + * 11.divmod(-3) #=> [-4, -1] + * 11.divmod(3.5) #=> [3.0, 0.5] + * (-11).divmod(3.5) #=> [-4.0, 3.0] + * (11.5).divmod(3.5) #=> [3.0, 1.0] + */ + static VALUE num_divmod(x, y) VALUE x, y; @@ -224,6 +319,14 @@ num_divmod(x, y) return rb_assoc_new(num_div(x, y), rb_funcall(x, '%', 1, y)); } +/* + * call-seq: + * num.modulo(numeric) => result + * + * Equivalent to + * num.divmod(aNumeric)[1]. + */ + static VALUE num_modulo(x, y) VALUE x, y; @@ -231,6 +334,18 @@ num_modulo(x, y) return rb_funcall(x, '%', 1, y); } +/* + * call-seq: + * num.remainder(numeric) => result + * + * If num and numeric have different signs, returns + * mod-numeric; otherwise, returns mod. In + * both cases mod is the value + * num.modulo(numeric). The + * differences between remainder and modulo + * (%) are shown in the table under Numeric#divmod. + */ + static VALUE num_remainder(x, y) VALUE x, y; @@ -247,6 +362,14 @@ num_remainder(x, y) return z; } +/* + * call-seq: + * num.integer? -> true or false + * + * Returns true if num is an Integer + * (including Fixnum and Bignum). + */ + static VALUE num_int_p(num) VALUE num; @@ -254,6 +377,17 @@ num_int_p(num) return Qfalse; } +/* + * call-seq: + * num.abs => num or numeric + * + * Returns the absolute value of num. + * + * 12.abs #=> 12 + * (-34.56).abs #=> 34.56 + * -34.56.abs #=> 34.56 + */ + static VALUE num_abs(num) VALUE num; @@ -264,6 +398,14 @@ num_abs(num) return num; } + +/* + * call-seq: + * num.zero? => true or false + * + * Returns true if num has a zero value. + */ + static VALUE num_zero_p(num) VALUE num; @@ -274,6 +416,19 @@ num_zero_p(num) return Qfalse; } + +/* + * call-seq: + * num.nonzero? => num or nil + * + * Returns num if num is not zero, nil + * otherwise. This behavior is useful when chaining comparisons: + * + * a = %w( z Bb bB bb BB a aA Aa AA A ) + * b = a.sort {|a,b| (a.downcase <=> b.downcase).nonzero? || a <=> b } + * b #=> ["A", "a", "AA", "Aa", "aA", "BB", "Bb", "bB", "bb", "z"] + */ + static VALUE num_nonzero_p(num) VALUE num; @@ -284,6 +439,14 @@ num_nonzero_p(num) return num; } +/* + * call-seq: + * num.to_int => integer + * + * Invokes the child class's to_i method to convert + * num to an integer. + */ + static VALUE num_to_int(num) VALUE num; @@ -602,6 +765,18 @@ flo_pow(x, y) } } +/* + * call-seq: + * num.eql?(numeric) => true or false + * + * Returns true if num and numeric are the + * same type and have equal values. + * + * 1 == 1.0 #=> true + * 1.eql?(1.0) #=> false + * (1.0).eql?(1.0) #=> true + */ + static VALUE num_eql(x, y) VALUE x, y; @@ -611,6 +786,14 @@ num_eql(x, y) return rb_equal(x, y); } +/* + * call-seq: + * num <=> other -> 0 or nil + * + * Returns zero if num equals other, nil + * otherwise. + */ + static VALUE num_cmp(x, y) VALUE x, y; @@ -1135,6 +1318,19 @@ flo_truncate(num) return LONG2FIX(val); } + +/* + * call-seq: + * num.floor => integer + * + * Returns the largest integer less than or equal to num. + * Numeric implements this by converting anInteger + * to a Float and invoking Float#floor. + * + * 1.floor #=> 1 + * (-1).floor #=> -1 + */ + static VALUE num_floor(num) VALUE num; @@ -1142,6 +1338,22 @@ num_floor(num) return flo_floor(rb_Float(num)); } + +/* + * call-seq: + * num.ceil => integer + * + * Returns the smallest Integer greater than or equal to + * num. Class Numeric achieves this by converting + * itself to a Float then invoking + * Float#ceil. + * + * 1.ceil #=> 1 + * 1.2.ceil #=> 2 + * (-1.2).ceil #=> -1 + * (-1.0).ceil #=> -1 + */ + static VALUE num_ceil(num) VALUE num; @@ -1149,6 +1361,15 @@ num_ceil(num) return flo_ceil(rb_Float(num)); } +/* + * call-seq: + * num.round => integer + * + * Rounds num to the nearest integer. Numeric + * implements this by converting itself to a + * Float and invoking Float#round. + */ + static VALUE num_round(num) VALUE num; @@ -1156,6 +1377,15 @@ num_round(num) return flo_round(rb_Float(num)); } +/* + * call-seq: + * num.truncate => integer + * + * Returns num truncated to an integer. Numeric + * implements this by converting its value to a float and invoking + * Float#truncate. + */ + static VALUE num_truncate(num) VALUE num; @@ -1163,6 +1393,34 @@ num_truncate(num) return flo_truncate(rb_Float(num)); } + +/* + * call-seq: + * num.step(limit, step ) {|i| block } => num + * + * Invokes block with the sequence of numbers starting at + * num, incremented by step on each call. 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). 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 floor(n + n*epsilon)+ 1 times, + * where n = (limit - num)/step. Otherwise, the loop + * starts at num, uses either the < or + * > operator to compare the counter against + * limit, and increments itself using the + + * operator. + * + * 1.step(10, 2) { |i| print i, " " } + * Math::E.step(Math::PI, 0.2) { |f| print f, " " } + * + * produces: + * + * 1 3 5 7 9 + * 2.71828182845905 2.91828182845905 3.11828182845905 + */ + static VALUE num_step(argc, argv, from) int argc; @@ -1451,6 +1709,29 @@ rb_num2ull(val) #endif /* HAVE_LONG_LONG */ + +/* + * Document-class: Integer + * + * Integer is the basis for the two concrete classes that + * hold whole numbers, Bignum and Fixnum. + * + */ + + +/* + * call-seq: + * int.to_i => int + * int.to_int => int + * int.floor => int + * int.ceil => int + * int.round => int + * int.truncate => int + * + * As int is already an Integer, all these + * methods simply return the receiver. + */ + static VALUE int_to_i(num) VALUE num; @@ -1458,6 +1739,13 @@ int_to_i(num) return num; } +/* + * call-seq: + * int.integer? -> true + * + * Always returns true. + */ + static VALUE int_int_p(num) VALUE num; @@ -1465,6 +1753,17 @@ int_int_p(num) return Qtrue; } +/* + * call-seq: + * int.next => integer + * int.succ => integer + * + * Returns the Integer equal to int + 1. + * + * 1.next #=> 2 + * (-1).next #=> 0 + */ + static VALUE int_succ(num) VALUE num; @@ -1476,6 +1775,18 @@ int_succ(num) return rb_funcall(num, '+', 1, INT2FIX(1)); } +/* + * call-seq: + * int.chr => string + * + * Returns a string containing the ASCII character represented by the + * receiver's value. + * + * 65.chr #=> "A" + * ?a.chr #=> "a" + * 230.chr #=> "\346" + */ + static VALUE int_chr(num) VALUE num; @@ -2320,6 +2631,20 @@ fix_size(fix) return INT2FIX(sizeof(long)); } +/* + * call-seq: + * int.upto(limit) {|i| block } => int + * + * Iterates block, passing in integer values from int + * up to and including limit. + * + * 5.upto(10) { |i| print i, " " } + * + * produces: + * + * 5 6 7 8 9 10 + */ + static VALUE int_upto(from, to) VALUE from, to; @@ -2344,6 +2669,21 @@ int_upto(from, to) return from; } +/* + * call-seq: + * int.downto(limit) {|i| block } => int + * + * Iterates block, passing decreasing values from int + * down to and including limit. + * + * 5.downto(1) { |n| print n, ".. " } + * print " Liftoff!\n" + * + * produces: + * + * 5.. 4.. 3.. 2.. 1.. Liftoff! + */ + static VALUE int_downto(from, to) VALUE from, to; @@ -2368,6 +2708,22 @@ int_downto(from, to) return from; } +/* + * call-seq: + * int.times {|i| block } => int + * + * Iterates block int times, passing in values from zero to + * int - 1. + * + * 5.times do |i| + * print i, " " + * end + * + * produces: + * + * 0 1 2 3 4 + */ + static VALUE int_dotimes(num) VALUE num; -- cgit v1.2.3