diff options
author | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-23 16:21:17 +0000 |
---|---|---|
committer | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-23 16:21:17 +0000 |
commit | a3ecd5c83d57fb1556a40113f1b0c69c87261e33 (patch) | |
tree | d7899acd6ca4985d4eacf92bc2e93601ba2d8b5f /numeric.c | |
parent | fd4a3ee4ac45995639ae361bf7ccb61a59ec124d (diff) |
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
Diffstat (limited to 'numeric.c')
-rw-r--r-- | numeric.c | 588 |
1 files changed, 588 insertions, 0 deletions
@@ -291,6 +291,15 @@ num_to_int(num) return rb_funcall(num, id_to_i, 0, 0); } + +/******************************************************************** + * + * Document-class: Float + * + * <code>Float</code> 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 + * ``<code>NaN</code>'', ``<code>Infinity</code>'', and + * ``<code>-Infinity</code>''. + */ + 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 <code>float</code> + * and <code>other</code>. + */ + 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 <code>float</code> + * and <code>other</code>. + */ + 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 <code>float</code> + * and <code>other</code>. + */ + 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 + * <code>float</code> by <code>other</code>. + */ + 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 <code>flt</code> by <code>other</code>. + * + * 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 <code>Numeric#divmod</code>. + */ + 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 <code>float</code> the <code>other</code> 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 <code>true</code> only if <i>obj</i> has the same value + * as <i>flt</i>. Contrast this with <code>Float#eql?</code>, which + * requires <i>obj</i> to be a <code>Float</code>. + * + * 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 <i>flt</i> is less than, + * equal to, or greater than <i>numeric</i>. This is the basis for the + * tests in <code>Comparable</code>. + */ + 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 + * + * <code>true</code> if <code>flt</code> is greater than <code>other</code>. + */ + 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 + * + * <code>true</code> if <code>flt</code> is greater than + * or equal to <code>other</code>. + */ + 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 + * + * <code>true</code> if <code>flt</code> is less than <code>other</code>. + */ + 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 + * + * <code>true</code> if <code>flt</code> is less than + * or equal to <code>other</code>. + */ + 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 <code>true</code> only if <i>obj</i> is a + * <code>Float</code> with the same value as <i>flt</i>. Contrast this + * with <code>Float#==</code>, 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 <code>flt</code> is already a float, returns <i>self</i>. + */ + 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 <i>flt</i>. + * + * (-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 <code>true</code> if <i>flt</i> 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 <code>true</code> if <i>flt</i> 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 <code>nil</code>, -1, or +1 depending on whether <i>flt</i> + * 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 <code>true</code> if <i>flt</i> is a valid IEEE floating + * point number (it is not infinite, and <code>nan?</code> is + * <code>false</code>). + * + */ + 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 <i>flt</i>. + * + * 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 <code>Integer</code> greater than or equal to + * <i>flt</i>. + * + * 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 <i>flt</i> 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 <i>flt</i> truncated to an <code>Integer</code>. + */ + static VALUE flo_truncate(num) VALUE num; @@ -1218,6 +1489,33 @@ int_chr(num) return rb_str_new(&c, 1); } +/******************************************************************** + * + * Document-class: Fixnum + * + * A <code>Fixnum</code> holds <code>Integer</code> values that can be + * represented in a native machine word (minus 1 bit). If any operation + * on a <code>Fixnum</code> exceeds this range, the value is + * automatically converted to a <code>Bignum</code>. + * + * <code>Fixnum</code> 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 <code>Fixnum</code> objects. There is effectively only one + * <code>Fixnum</code> object instance for any given integer value, so, + * for example, you cannot add a singleton method to a + * <code>Fixnum</code>. + */ + + +/* + * call-seq: + * Fixnum.induced_from(obj) => fixnum + * + * Convert <code>obj</code> 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 <code>obj</code> 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 <code>obj</code> 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 <code>fix</code> (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 <i>fix</i> radix + * <i>base</i> (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 <code>numeric</code> 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 <code>numeric</code> 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 <code>numeric</code> 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 <i>fix</i> by + * <i>numeric</i>. + * + * 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 <code>numeric</code> 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 <code>fix</code> modulo <code>other</code>. + * See <code>Numeric.divmod</code> 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 <code>Numeric#divmod</code>. + */ 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 <code>fix</code> to the <code>other</code> 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 <code>true</code> if <code>fix</code> equals <code>other</code> + * 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 <i>fix</i> is + * less than, equal to, or greater than <i>numeric</i>. This is the + * basis for the tests in <code>Comparable</code>. + */ + 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 <code>true</code> if the value of <code>fix</code> is + * greater than that of <code>other</code>. + */ + 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 <code>true</code> if the value of <code>fix</code> is + * greater than or equal to that of <code>other</code>. + */ + 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 <code>true</code> if the value of <code>fix</code> is + * less than that of <code>other</code>. + */ + 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 <code>true</code> if the value of <code>fix</code> is + * less thanor equal to that of <code>other</code>. + */ + 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 <em>n</em>th bit in the binary + * representation of <i>fix</i>, where <i>fix</i>[0] is the least + * significant bit. + * + * a = 0b11001100101010 + * 30.downto(0) do |n| print a[n] end + * + * <em>produces:</em> + * + * 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 <i>fix</i> to a <code>Float</code>. + * + */ + 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 <i>fix</i>. + * + * -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 <i>fix</i>. If + * there is no symbol in the symbol table with this value, returns + * <code>nil</code>. <code>id2name</code> has nothing to do with the + * <code>Object.id</code> method. See also <code>Fixnum#to_sym</code>, + * <code>String#intern</code>, and class <code>Symbol</code>. + * + * 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 <i>fix</i>. See also + * <code>Fixnum#id2name</code>. + * + * 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 <em>bytes</em> in the machine representation + * of a <code>Fixnum</code>. + * + * 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 <code>true</code> if <i>fix</i> is zero. + * + */ + static VALUE fix_zero_p(num) VALUE num; |