From a3ecd5c83d57fb1556a40113f1b0c69c87261e33 Mon Sep 17 00:00:00 2001 From: dave Date: Tue, 23 Dec 2003 16:21:17 +0000 Subject: RDoc comments for Fixnum, Float, and Hash. Add heuristic to RDoc to handle yaml/stringio git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5265 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- numeric.c | 588 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 588 insertions(+) (limited to 'numeric.c') diff --git a/numeric.c b/numeric.c index 50781446e8..3ee1aef466 100644 --- a/numeric.c +++ b/numeric.c @@ -291,6 +291,15 @@ num_to_int(num) return rb_funcall(num, id_to_i, 0, 0); } + +/******************************************************************** + * + * Document-class: Float + * + * Float objects represent real numbers using the native + * architecture's double-precision floating point representation. + */ + VALUE rb_float_new(d) double d; @@ -302,6 +311,16 @@ rb_float_new(d) return (VALUE)flt; } +/* + * call-seq: + * flt.to_s => string + * + * Returns a string containing a representation of self. As well as a + * fixed or exponential form of the number, the call may return + * ``NaN'', ``Infinity'', and + * ``-Infinity''. + */ + static VALUE flo_to_s(flt) VALUE flt; @@ -341,6 +360,10 @@ flo_to_s(flt) return rb_str_new2(buf); } +/* + * MISSING: documentation + */ + static VALUE flo_coerce(x, y) VALUE x, y; @@ -348,6 +371,13 @@ flo_coerce(x, y) return rb_assoc_new(rb_Float(y), x); } +/* + * call-seq: + * -float => float + * + * Returns float, negated. + */ + static VALUE flo_uminus(flt) VALUE flt; @@ -355,6 +385,14 @@ flo_uminus(flt) return rb_float_new(-RFLOAT(flt)->value); } +/* + * call-seq: + * float + other => float + * + * Returns a new float which is the sum of float + * and other. + */ + static VALUE flo_plus(x, y) VALUE x, y; @@ -371,6 +409,14 @@ flo_plus(x, y) } } +/* + * call-seq: + * float + other => float + * + * Returns a new float which is the difference of float + * and other. + */ + static VALUE flo_minus(x, y) VALUE x, y; @@ -387,6 +433,14 @@ flo_minus(x, y) } } +/* + * call-seq: + * float * other => float + * + * Returns a new float with is the product of float + * and other. + */ + static VALUE flo_mul(x, y) VALUE x, y; @@ -403,6 +457,14 @@ flo_mul(x, y) } } +/* + * call-seq: + * float / other => float + * + * Returns a new float which is the result of dividing + * float by other. + */ + static VALUE flo_div(x, y) VALUE x, y; @@ -424,6 +486,7 @@ flo_div(x, y) } } + static void flodivmod(x, y, divp, modp) double x, y; @@ -450,6 +513,18 @@ flodivmod(x, y, divp, modp) if (divp) *divp = div; } + +/* + * call-seq: + * flt % other => float + * flt.modulo(other) => float + * + * Return the modulo after dividion of flt by other. + * + * 6543.21.modulo(137) #=> 104.21 + * 6543.21.modulo(137.24) #=> 92.9299999999996 + */ + static VALUE flo_mod(x, y) VALUE x, y; @@ -473,6 +548,13 @@ flo_mod(x, y) return rb_float_new(mod); } +/* + * call-seq: + * flt.divmod(numeric) => array + * + * See Numeric#divmod. + */ + static VALUE flo_divmod(x, y) VALUE x, y; @@ -496,6 +578,14 @@ flo_divmod(x, y) return rb_assoc_new(rb_float_new(div), rb_float_new(mod)); } +/* + * call-seq: + * + * flt ** other => float + * + * Raises float the other power. + */ + static VALUE flo_pow(x, y) VALUE x, y; @@ -537,6 +627,18 @@ num_equal(x, y) return rb_funcall(y, id_eq, 1, x); } +/* + * call-seq: + * flt == obj => true or false + * + * Returns true only if obj has the same value + * as flt. Contrast this with Float#eql?, which + * requires obj to be a Float. + * + * 1.0 == 1 #=> true + * + */ + static VALUE flo_eq(x, y) VALUE x, y; @@ -561,6 +663,13 @@ flo_eq(x, y) return (a == b)?Qtrue:Qfalse; } +/* + * call-seq: + * flt.hash => integer + * + * Returns a hash code for this float. + */ + static VALUE flo_hash(num) VALUE num; @@ -590,6 +699,15 @@ rb_dbl_cmp(a, b) return Qnil; } +/* + * call-seq: + * flt <=> numeric => -1, 0, +1 + * + * Returns -1, 0, or +1 depending on whether flt is less than, + * equal to, or greater than numeric. This is the basis for the + * tests in Comparable. + */ + static VALUE flo_cmp(x, y) VALUE x, y; @@ -616,6 +734,13 @@ flo_cmp(x, y) return rb_dbl_cmp(a, b); } +/* + * call-seq: + * flt > other => true or false + * + * true if flt is greater than other. + */ + static VALUE flo_gt(x, y) VALUE x, y; @@ -643,6 +768,14 @@ flo_gt(x, y) return (a > b)?Qtrue:Qfalse; } +/* + * call-seq: + * flt >= other => true or false + * + * true if flt is greater than + * or equal to other. + */ + static VALUE flo_ge(x, y) VALUE x, y; @@ -670,6 +803,13 @@ flo_ge(x, y) return (a >= b)?Qtrue:Qfalse; } +/* + * call-seq: + * flt < other => true or false + * + * true if flt is less than other. + */ + static VALUE flo_lt(x, y) VALUE x, y; @@ -697,6 +837,14 @@ flo_lt(x, y) return (a < b)?Qtrue:Qfalse; } +/* + * call-seq: + * flt <= other => true or false + * + * true if flt is less than + * or equal to other. + */ + static VALUE flo_le(x, y) VALUE x, y; @@ -724,6 +872,17 @@ flo_le(x, y) return (a <= b)?Qtrue:Qfalse; } +/* + * call-seq: + * flt.eql?(obj) => true or false + * + * Returns true only if obj is a + * Float with the same value as flt. Contrast this + * with Float#==, which performs type conversions. + * + * 1.0.eql?(1) #=> false + */ + static VALUE flo_eql(x, y) VALUE x, y; @@ -738,6 +897,13 @@ flo_eql(x, y) return Qfalse; } +/* + * call-seq: + * flt.to_f => flt + * + * As flt is already a float, returns self. + */ + static VALUE flo_to_f(num) VALUE num; @@ -745,6 +911,17 @@ flo_to_f(num) return num; } +/* + * call-seq: + * flt.abs => float + * + * Returns the absolute value of flt. + * + * (-34.56).abs #=> 34.56 + * -34.56.abs #=> 34.56 + * + */ + static VALUE flo_abs(flt) VALUE flt; @@ -753,6 +930,14 @@ flo_abs(flt) return rb_float_new(val); } +/* + * call-seq: + * flt.zero? -> true or false + * + * Returns true if flt is 0.0. + * + */ + static VALUE flo_zero_p(num) VALUE num; @@ -763,6 +948,19 @@ flo_zero_p(num) return Qfalse; } +/* + * call-seq: + * flt.nan? -> true or false + * + * Returns true if flt is an invalid IEEE floating + * point number. + * + * a = -1.0 #=> -1.0 + * a.nan? #=> false + * a = 0.0/0.0 #=> NaN + * a.nan? #=> true + */ + static VALUE flo_is_nan_p(num) VALUE num; @@ -772,6 +970,18 @@ flo_is_nan_p(num) return isnan(value) ? Qtrue : Qfalse; } +/* + * call-seq: + * flt.infinite? -> nil, -1, +1 + * + * Returns nil, -1, or +1 depending on whether flt + * is finite, -infinity, or +infinity. + * + * (0.0).infinite? #=> nil + * (-1.0/0.0).infinite? #=> -1 + * (+1.0/0.0).infinite? #=> 1 + */ + static VALUE flo_is_infinite_p(num) VALUE num; @@ -785,6 +995,16 @@ flo_is_infinite_p(num) return Qnil; } +/* + * call-seq: + * flt.finite? -> true or false + * + * Returns true if flt is a valid IEEE floating + * point number (it is not infinite, and nan? is + * false). + * + */ + static VALUE flo_is_finite_p(num) VALUE num; @@ -802,6 +1022,18 @@ flo_is_finite_p(num) return Qtrue; } +/* + * call-seq: + * flt.floor => integer + * + * Returns the largest integer less than or equal to flt. + * + * 1.2.floor #=> 1 + * 2.0.floor #=> 2 + * (-1.2).floor #=> -2 + * (-2.0).floor #=> -2 + */ + static VALUE flo_floor(num) VALUE num; @@ -816,6 +1048,19 @@ flo_floor(num) return LONG2FIX(val); } +/* + * call-seq: + * flt.ceil => integer + * + * Returns the smallest Integer greater than or equal to + * flt. + * + * 1.2.ceil #=> 2 + * 2.0.ceil #=> 2 + * (-1.2).ceil #=> -1 + * (-2.0).ceil #=> -2 + */ + static VALUE flo_ceil(num) VALUE num; @@ -830,6 +1075,23 @@ flo_ceil(num) return LONG2FIX(val); } +/* + * call-seq: + * flt.round => integer + * + * Rounds flt to the nearest integer. Equivalent to: + * + * def round + * return floor(self+0.5) if self > 0.0 + * return ceil(self-0.5) if self < 0.0 + * return 0.0 + * end + * + * 1.5.round #=> 2 + * (-1.5).round #=> -2 + * + */ + static VALUE flo_round(num) VALUE num; @@ -847,6 +1109,15 @@ flo_round(num) return LONG2FIX(val); } +/* + * call-seq: + * flt.to_i => integer + * flt.to_int => integer + * flt.truncate => integer + * + * Returns flt truncated to an Integer. + */ + static VALUE flo_truncate(num) VALUE num; @@ -1218,6 +1489,33 @@ int_chr(num) return rb_str_new(&c, 1); } +/******************************************************************** + * + * Document-class: Fixnum + * + * A Fixnum holds Integer values that can be + * represented in a native machine word (minus 1 bit). If any operation + * on a Fixnum exceeds this range, the value is + * automatically converted to a Bignum. + * + * Fixnum objects have immediate value. This means that + * when they are assigned or passed as parameters, the actual object is + * passed, rather than a reference to that object. Assignment does not + * alias Fixnum objects. There is effectively only one + * Fixnum object instance for any given integer value, so, + * for example, you cannot add a singleton method to a + * Fixnum. + */ + + +/* + * call-seq: + * Fixnum.induced_from(obj) => fixnum + * + * Convert obj to a Fixnum. Works with numeric parameters. + * Also works with Symbols, but this is deprecated. + */ + static VALUE rb_fix_induced_from(klass, x) VALUE klass, x; @@ -1225,6 +1523,13 @@ rb_fix_induced_from(klass, x) return rb_num2fix(x); } +/* + * call-seq: + * Integer.induced_from(obj) => fixnum, bignum + * + * Convert obj to an Integer. + */ + static VALUE rb_int_induced_from(klass, x) VALUE klass, x; @@ -1241,6 +1546,13 @@ rb_int_induced_from(klass, x) } } +/* + * call-seq: + * Float.induced_from(obj) => float + * + * Convert obj to a float. + */ + static VALUE rb_flo_induced_from(klass, x) VALUE klass, x; @@ -1257,6 +1569,13 @@ rb_flo_induced_from(klass, x) } } +/* + * call-seq: + * -fix => integer + * + * Negates fix (which might return a Bignum). + */ + static VALUE fix_uminus(num) VALUE num; @@ -1295,6 +1614,21 @@ rb_fix2str(x, base) return rb_str_new2(b); } +/* + * call-seq: + * fix.to_s( base=10 ) -> aString + * + * Returns a string containing the representation of fix radix + * base (between 2 and 36). + * + * 12345.to_s #=> "12345" + * 12345.to_s(2) #=> "11000000111001" + * 12345.to_s(8) #=> "30071" + * 12345.to_s(10) #=> "12345" + * 12345.to_s(16) #=> "3039" + * 12345.to_s(36) #=> "9ix" + * + */ static VALUE fix_to_s(argc, argv, x) int argc; @@ -1315,6 +1649,15 @@ fix_to_s(argc, argv, x) return rb_fix2str(x, base); } +/* + * call-seq: + * fix + numeric => numeric_result + * + * Performs addition: the class of the resulting object depends on + * the class of numeric and on the magnitude of the + * result. + */ + static VALUE fix_plus(x, y) VALUE x, y; @@ -1339,6 +1682,15 @@ fix_plus(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix - numeric => numeric_result + * + * Performs subtraction: the class of the resulting object depends on + * the class of numeric and on the magnitude of the + * result. + */ + static VALUE fix_minus(x, y) VALUE x, y; @@ -1363,6 +1715,15 @@ fix_minus(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix * numeric => numeric_result + * + * Performs multiplication: the class of the resulting object depends on + * the class of numeric and on the magnitude of the + * result. + */ + static VALUE fix_mul(x, y) VALUE x, y; @@ -1418,6 +1779,18 @@ fixdivmod(x, y, divp, modp) if (modp) *modp = mod; } +/* + * call-seq: + * fix.quo(numeric) => float + * + * Returns the floating point result of dividing fix by + * numeric. + * + * 654321.quo(13731) #=> 47.6528293642124 + * 654321.quo(13731.24) #=> 47.6519964693647 + * + */ + static VALUE fix_quo(x, y) VALUE x, y; @@ -1428,6 +1801,16 @@ fix_quo(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix / numeric => numeric_result + * fix.div(numeric) => numeric_result + * + * Performs division: the class of the resulting object depends on + * the class of numeric and on the magnitude of the + * result. + */ + static VALUE fix_div(x, y) VALUE x, y; @@ -1441,6 +1824,15 @@ fix_div(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix % other => Numeric + * fix.modulo(other) => Numeric + * + * Returns fix modulo other. + * See Numeric.divmod for more information. + */ + static VALUE fix_mod(x, y) VALUE x, y; @@ -1454,6 +1846,12 @@ fix_mod(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix.divmod(numeric) => array + * + * See Numeric#divmod. + */ static VALUE fix_divmod(x, y) VALUE x, y; @@ -1468,6 +1866,18 @@ fix_divmod(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix ** other => Numeric + * + * Raises fix to the other power, which may + * be negative or fractional. + * + * 2 ** 3 #=> 8 + * 2 ** -1 #=> 0.5 + * 2 ** 0.5 #=> 1.4142135623731 + */ + static VALUE fix_pow(x, y) VALUE x, y; @@ -1487,6 +1897,17 @@ fix_pow(x, y) return rb_num_coerce_bin(x, y); } +/* + * call-seq: + * fix == other + * + * Return true if fix equals other + * numerically. + * + * 1 == 2 #=> false + * 1 == 1.0 #=> true + */ + static VALUE fix_equal(x, y) VALUE x, y; @@ -1499,6 +1920,15 @@ fix_equal(x, y) } } +/* + * call-seq: + * fix <=> numeric => -1, 0, +1 + * + * Comparison---Returns -1, 0, or +1 depending on whether fix is + * less than, equal to, or greater than numeric. This is the + * basis for the tests in Comparable. + */ + static VALUE fix_cmp(x, y) VALUE x, y; @@ -1515,6 +1945,14 @@ fix_cmp(x, y) } } +/* + * call-seq: + * fix > other => true or false + * + * Returns true if the value of fix is + * greater than that of other. + */ + static VALUE fix_gt(x, y) VALUE x, y; @@ -1530,6 +1968,14 @@ fix_gt(x, y) } } +/* + * call-seq: + * fix >= other => true or false + * + * Returns true if the value of fix is + * greater than or equal to that of other. + */ + static VALUE fix_ge(x, y) VALUE x, y; @@ -1545,6 +1991,14 @@ fix_ge(x, y) } } +/* + * call-seq: + * fix < other => true or false + * + * Returns true if the value of fix is + * less than that of other. + */ + static VALUE fix_lt(x, y) VALUE x, y; @@ -1560,6 +2014,14 @@ fix_lt(x, y) } } +/* + * call-seq: + * fix <= other => true or false + * + * Returns true if the value of fix is + * less thanor equal to that of other. + */ + static VALUE fix_le(x, y) VALUE x, y; @@ -1575,6 +2037,13 @@ fix_le(x, y) } } +/* + * call-seq: + * ~fix => integer + * + * One's complement: returns a number where each bit is flipped. + */ + static VALUE fix_rev(num) VALUE num; @@ -1585,6 +2054,13 @@ fix_rev(num) return LONG2NUM(val); } +/* + * call-seq: + * fix & other => integer + * + * Bitwise AND. + */ + static VALUE fix_and(x, y) VALUE x, y; @@ -1598,6 +2074,13 @@ fix_and(x, y) return LONG2NUM(val); } +/* + * call-seq: + * fix | other => integer + * + * Bitwise OR. + */ + static VALUE fix_or(x, y) VALUE x, y; @@ -1611,6 +2094,13 @@ fix_or(x, y) return LONG2NUM(val); } +/* + * call-seq: + * fix ^ other => integer + * + * Bitwise EXCLUSIVE OR. + */ + static VALUE fix_xor(x, y) VALUE x, y; @@ -1626,6 +2116,13 @@ fix_xor(x, y) static VALUE fix_rshift _((VALUE, VALUE)); +/* + * call-seq: + * fix << count => integer + * + * Shifts _fix_ left _count_ positions (right if _count_ is negative). + */ + static VALUE fix_lshift(x, y) VALUE x, y; @@ -1644,6 +2141,13 @@ fix_lshift(x, y) return LONG2NUM(val); } +/* + * call-seq: + * fix >> count => integer + * + * Shifts _fix_ left _count_ positions (right if _count_ is negative). + */ + static VALUE fix_rshift(x, y) VALUE x, y; @@ -1663,6 +2167,22 @@ fix_rshift(x, y) return LONG2FIX(val); } +/* + * call-seq: + * fix[n] => 0, 1 + * + * Bit Reference---Returns the nth bit in the binary + * representation of fix, where fix[0] is the least + * significant bit. + * + * a = 0b11001100101010 + * 30.downto(0) do |n| print a[n] end + * + * produces: + * + * 0000000000000000011001100101010 + */ + static VALUE fix_aref(fix, idx) VALUE fix, idx; @@ -1690,6 +2210,14 @@ fix_aref(fix, idx) return INT2FIX(0); } +/* + * call-seq: + * fix.to_f -> float + * + * Converts fix to a Float. + * + */ + static VALUE fix_to_f(num) VALUE num; @@ -1701,6 +2229,17 @@ fix_to_f(num) return rb_float_new(val); } +/* + * call-seq: + * fix.abs -> aFixnum + * + * Returns the absolute value of fix. + * + * -12345.abs #=> 12345 + * 12345.abs #=> 12345 + * + */ + static VALUE fix_abs(fix) VALUE fix; @@ -1712,6 +2251,21 @@ fix_abs(fix) return LONG2NUM(i); } +/* + * call-seq: + * fix.id2name -> string or nil + * + * Returns the name of the object whose symbol id is fix. If + * there is no symbol in the symbol table with this value, returns + * nil. id2name has nothing to do with the + * Object.id method. See also Fixnum#to_sym, + * String#intern, and class Symbol. + * + * symbol = :@inst_var #=> :@inst_var + * id = symbol.to_i #=> 9818 + * id.id2name #=> "@inst_var" + */ + static VALUE fix_id2name(fix) VALUE fix; @@ -1721,6 +2275,19 @@ fix_id2name(fix) return Qnil; } + +/* + * call-seq: + * fix.to_sym -> aSymbol + * + * Returns the symbol whose integer value is fix. See also + * Fixnum#id2name. + * + * fred = :fred.to_i + * fred.id2name #=> "fred" + * fred.to_sym #=> :fred + */ + static VALUE fix_to_sym(fix) VALUE fix; @@ -1733,6 +2300,19 @@ fix_to_sym(fix) return Qnil; } + +/* + * call-seq: + * fix.size -> fixnum + * + * Returns the number of bytes in the machine representation + * of a Fixnum. + * + * 1.size #=> 4 + * -1.size #=> 4 + * 2147483647.size #=> 4 + */ + static VALUE fix_size(fix) VALUE fix; @@ -1812,6 +2392,14 @@ int_dotimes(num) return num; } +/* + * call-seq: + * fix.zero? => true or false + * + * Returns true if fix is zero. + * + */ + static VALUE fix_zero_p(num) VALUE num; -- cgit v1.2.3