ruby-changes:12191
From: tadf <ko1@a...>
Date: Sat, 27 Jun 2009 16:47:13 +0900 (JST)
Subject: [ruby-changes:12191] Ruby:r23870 (trunk): * complex.c: revised rdoc.
tadf 2009-06-27 16:46:57 +0900 (Sat, 27 Jun 2009) New Revision: 23870 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=23870 Log: * complex.c: revised rdoc. * rational.c: ditto. * numeric.c: ditto. Modified files: trunk/ChangeLog trunk/complex.c trunk/numeric.c trunk/rational.c Index: complex.c =================================================================== --- complex.c (revision 23869) +++ complex.c (revision 23870) @@ -382,8 +382,8 @@ /* * call-seq: - * Complex.rect(real[, imag]) => complex - * Complex.rectangular(real[, imag]) => complex + * Complex.rect(real[, imag]) -> complex + * Complex.rectangular(real[, imag]) -> complex * * Returns a complex object which denotes the given rectangular form. */ @@ -420,6 +420,12 @@ return nucomp_s_canonicalize_internal(klass, x, y); } +/* + * call-seq: + * Complex(x[, y]) -> numeric + * + * Returns x+i*y; + */ static VALUE nucomp_f_complex(int argc, VALUE *argv, VALUE klass) { @@ -528,7 +534,7 @@ /* * call-seq: - * Complex.polar(abs, arg) => complex + * Complex.polar(abs, arg) -> complex * * Returns a complex object which denotes the given polar form. */ @@ -540,7 +546,7 @@ /* * call-seq: - * cmp.real => real + * cmp.real -> real * * Returns the real part. */ @@ -553,8 +559,8 @@ /* * call-seq: - * cmp.imag => real - * cmp.imaginary => real + * cmp.imag -> real + * cmp.imaginary -> real * * Returns the imaginary part. */ @@ -566,10 +572,10 @@ } /* - * call-seq: - * -cmp => complex + * call-seq: + * -cmp -> complex * - * Returns negation of the value. + * Returns negation of the value. */ static VALUE nucomp_negate(VALUE self) @@ -581,7 +587,7 @@ /* * call-seq: - * cmp + numeric => complex + * cmp + numeric -> complex * * Performs addition. */ @@ -609,7 +615,7 @@ /* * call-seq: - * cmp - numeric => complex + * cmp - numeric -> complex * * Performs subtraction. */ @@ -637,7 +643,7 @@ /* * call-seq: - * cmp * numeric => complex + * cmp * numeric -> complex * * Performs multiplication. */ @@ -697,15 +703,15 @@ /* * call-seq: - * cmp / numeric => complex - * cmp.quo(numeric) => complex + * cmp / numeric -> complex + * cmp.quo(numeric) -> complex * * Performs division. * * For example: * - * Complex(10.0) / 3 #=> (3.3333333333333335+(0/1)*i) - * Complex(10) / 3 #=> ((10/3)+(0/1)*i) # not (3+0i) + * Complex(10.0) / 3 #=> (3.3333333333333335+(0/1)*i) + * Complex(10) / 3 #=> ((10/3)+(0/1)*i) # not (3+0i) */ static VALUE nucomp_div(VALUE self, VALUE other) @@ -717,13 +723,13 @@ /* * call-seq: - * cmp.fdiv(numeric) => complex + * cmp.fdiv(numeric) -> complex * - * Performs division as each part is a float, never returns float. + * Performs division as each part is a float, never returns a float. * * For example: * - * Complex(11,22).fdiv(3) #=> (3.6666666666666665+7.333333333333333i) + * Complex(11,22).fdiv(3) #=> (3.6666666666666665+7.333333333333333i) */ static VALUE nucomp_fdiv(VALUE self, VALUE other) @@ -733,14 +739,14 @@ /* * call-seq: - * cmp ** numeric => complex + * cmp ** numeric -> complex * * Performs exponentiation. * * For example: * - * Complex('i')**2 #=> (-1+0i) - * Complex(-8)**Rational(1,3) #=> (1.0000000000000002+1.7320508075688772i) + * Complex('i') ** 2 #=> (-1+0i) + * Complex(-8) ** Rational(1,3) #=> (1.0000000000000002+1.7320508075688772i) */ static VALUE nucomp_expt(VALUE self, VALUE other) @@ -806,7 +812,7 @@ /* * call-seq: - * cmp == object => true or false + * cmp == object -> true or false * * Returns true if cmp equals object numerically. */ @@ -827,6 +833,7 @@ return f_equal_p(other, self); } +/* :nodoc: */ static VALUE nucomp_coerce(VALUE self, VALUE other) { @@ -842,8 +849,8 @@ /* * call-seq: - * cmp.abs => float - * cmp.magnitude => float + * cmp.abs -> real + * cmp.magnitude -> real * * Returns the absolute part of its polar form. */ @@ -856,7 +863,7 @@ /* * call-seq: - * cmp.abs2 => real + * cmp.abs2 -> real * * Returns square of the absolute value. */ @@ -870,9 +877,9 @@ /* * call-seq: - * cmp.arg => float - * cmp.angle => float - * cmp.phase => float + * cmp.arg -> float + * cmp.angle -> float + * cmp.phase -> float * * Returns the angle part of its polar form. */ @@ -885,10 +892,10 @@ /* * call-seq: - * cmp.rect => array - * cmp.rectangular => array + * cmp.rect -> array + * cmp.rectangular -> array * - * Returns an array [cmp.real, cmp.imag]. + * Returns an array; [cmp.real, cmp.imag]. */ static VALUE nucomp_rect(VALUE self) @@ -899,9 +906,9 @@ /* * call-seq: - * cmp.polar => array + * cmp.polar -> array * - * Returns an array [cmp.abs, cmp.arg]. + * Returns an array; [cmp.abs, cmp.arg]. */ static VALUE nucomp_polar(VALUE self) @@ -911,8 +918,8 @@ /* * call-seq: - * cmp.conj => complex - * cmp.conjucate => complex + * cmp.conj -> complex + * cmp.conjucate -> complex * * Returns the complex conjucate. */ @@ -924,6 +931,7 @@ } #if 0 +/* :nodoc: */ static VALUE nucomp_true(VALUE self) { @@ -933,7 +941,7 @@ /* * call-seq: - * cmp.real? => false + * cmp.real? -> false * * Returns false. */ @@ -944,6 +952,7 @@ } #if 0 +/* :nodoc: */ static VALUE nucomp_exact_p(VALUE self) { @@ -951,6 +960,7 @@ return f_boolcast(f_exact_p(dat->real) && f_exact_p(dat->imag)); } +/* :nodoc: */ static VALUE nucomp_inexact_p(VALUE self) { @@ -962,13 +972,11 @@ /* * call-seq: - * cmp.denominator => integer + * cmp.denominator -> integer * - * Returns the denominator. + * Returns the denominator (lcm of both denominator, real and imag). * - * This means cmp.real.denominator.lcm(cmp.denominator). - * - * See Complex#numerator. + * See numerator. */ static VALUE nucomp_denominator(VALUE self) @@ -979,19 +987,23 @@ /* * call-seq: - * cmp.numerator => numeric + * cmp.numerator -> numeric * * Returns the numerator. * * For example: * - * c = Complex('1/2+2/3i') #=> ((1/2)+(2/3)*i) - * n = c.numerator #=> (3+4i) - * d = c.denominator #=> 6 - * n/d #=> ((1/2)+(2/3)*i) - * Complex(Rational(n.real, d), Rational(n.imag, d)) + * 1 2 3+4i <- numerator + * - + -i -> ---- + * 2 3 6 <- denominator + * + * c = Complex('1/2+2/3i') #=> ((1/2)+(2/3)*i) + * n = c.numerator #=> (3+4i) + * d = c.denominator #=> 6 + * n / d #=> ((1/2)+(2/3)*i) + * Complex(Rational(n.real, d), Rational(n.imag, d)) * #=> ((1/2)+(2/3)*i) - * See Complex#denominator. + * See denominator. */ static VALUE nucomp_numerator(VALUE self) @@ -1008,6 +1020,7 @@ f_div(cd, f_denominator(dat->imag)))); } +/* :nodoc: */ static VALUE nucomp_hash(VALUE self) { @@ -1024,6 +1037,7 @@ return LONG2FIX(v); } +/* :nodoc: */ static VALUE nucomp_eql_p(VALUE self, VALUE other) { @@ -1093,7 +1107,7 @@ /* * call-seq: - * cmp.to_s => string + * cmp.to_s -> string * * Returns the value as a string. */ @@ -1105,7 +1119,7 @@ /* * call-seq: - * cmp.inspect => string + * cmp.inspect -> string * * Returns the value as a string for inspection. */ @@ -1121,6 +1135,7 @@ return s; } +/* :nodoc: */ static VALUE nucomp_marshal_dump(VALUE self) { @@ -1132,6 +1147,7 @@ return a; } +/* :nodoc: */ static VALUE nucomp_marshal_load(VALUE self, VALUE a) { @@ -1175,9 +1191,9 @@ /* * call-seq: - * cmp.to_i => integer + * cmp.to_i -> integer * - * Returns the value as an integer if can. + * Returns the value as an integer if possible. */ static VALUE nucomp_to_i(VALUE self) @@ -1194,9 +1210,9 @@ /* * call-seq: - * cmp.to_f => float + * cmp.to_f -> float * - * Returns the value as a float if can. + * Returns the value as a float if possible. */ static VALUE nucomp_to_f(VALUE self) @@ -1213,9 +1229,9 @@ /* * call-seq: - * cmp.to_r => rational + * cmp.to_r -> rational * - * Returns the value as a rational if can. + * Returns the value as a rational if possible. */ static VALUE nucomp_to_r(VALUE self) @@ -1232,7 +1248,7 @@ /* * call-seq: - * nil.to_c => complex + * nil.to_c -> (0+0i) * * Returns zero as a complex. */ @@ -1244,7 +1260,7 @@ /* * call-seq: - * num.to_c => complex + * num.to_c -> complex * * Returns the value as a complex. */ @@ -1425,21 +1441,24 @@ /* * call-seq: - * str.to_c => complex + * str.to_c -> complex * - * Returns a complex which denotes string form. + * Returns a complex which denotes the string form. The parser + * ignores leading whitespaces and trailing garbage. Any digit + * sequences can be separeted by an underscore. Returns zero for null + * string. * * For example: * - * '9'.to_c #=> (9+0i) - * '-3/2'.to_c #=> ((-3/2)+0i) - * '-i'.to_c #=> (0-1i) - * '45i'.to_c #=> (0+45i) - * '3-4i'.to_c #=> (3-4i) - * '-4e2-4e-2i'.to_c #=> (-400.0-0.04i) - * '-0.0-0.0i'.to_c #=> (-0.0-0.0i) - * '1/2+3/4i'.to_c #=> ((1/2)+(3/4)*i) - * 'ruby'.to_c #=> (0+0i) + * '9'.to_c #=> (9+0i) + * '-3/2'.to_c #=> ((-3/2)+0i) + * '-i'.to_c #=> (0-1i) + * '45i'.to_c #=> (0+45i) + * '3-4i'.to_c #=> (3-4i) + * '-4e2-4e-2i'.to_c #=> (-400.0-0.04i) + * '-0.0-0.0i'.to_c #=> (-0.0-0.0i) + * '1/2+3/4i'.to_c #=> ((1/2)+(3/4)*i) + * 'ruby'.to_c #=> (0+0i) */ static VALUE string_to_c(VALUE self) @@ -1547,7 +1566,7 @@ /* * call-seq: - * num.real => self + * num.real -> self * * Returns self. */ @@ -1559,8 +1578,8 @@ /* * call-seq: - * num.imag => 0 - * num.imaginary => 0 + * num.imag -> 0 + * num.imaginary -> 0 * * Returns zero. */ @@ -1572,7 +1591,7 @@ /* * call-seq: - * num.abs2 => real + * num.abs2 -> real * * Returns square of self. */ @@ -1586,9 +1605,9 @@ /* * call-seq: - * num.arg => float - * num.angle => float - * num.phase => float + * num.arg -> float + * num.angle -> float + * num.phase -> float * * Returns 0 if the value is positive, pi otherwise. */ @@ -1602,9 +1621,9 @@ /* * call-seq: - * num.rect => array + * num.rect -> array * - * Returns an array [num, 0]. + * Returns an array; [num, 0]. */ static VALUE numeric_rect(VALUE self) @@ -1614,9 +1633,9 @@ /* * call-seq: - * num.polar => array + * num.polar -> array * - * Returns an array [num.abs, num.arg]. + * Returns an array; [num.abs, num.arg]. */ static VALUE numeric_polar(VALUE self) @@ -1626,8 +1645,8 @@ /* * call-seq: - * num.conj => self - * num.conjucate => self + * num.conj -> self + * num.conjucate -> self * * Returns self. */ @@ -1638,22 +1657,36 @@ } /* - * Complex provides complex number. - * it's simple. it's not real. but really numeric. + * A complex number can be represented as a paired real number with + * imaginary unit; a+bi. Where a is real part, b is imaginary part + * and i is imaginary unit. Real a equals complex a+0i + * mathematically. * - * Complex(0) #=> (0+0i) - * Complex(1, 2) #=> (1+2i) - * Complex.rect(1, 2) #=> (1+2i) - * Complex(1.1, 3.3) #=> (1.1+3.3i) - * Complex(Rational(1, 2), Rational(2, 3)) - * #=> ((1/2)+(2/3)*i) - * Complex.polar(1, 2) #=> (-0.4161468365471424+0.9092974268256817i) + * In ruby, you can create complex object with Complex, Complex::rect, + * Complex::polar or to_c method. * - * Complex('i') #=> (0+1i) - * Complex('1+2i') #=> (1+2i) - * Complex('1.1+3.3i') #=> (1.1+3.3i) - * Complex('1/2+2/3i') #=> ((1/2)+(2/3)*i) - * Complex('1@2') #=> (-0.4161468365471424+0.9092974268256817i) + * Complex(1) #=> (1+0i) + * Complex(2, 3) #=> (2+3i) + * Complex.polar(2, 3) #=> (-1.9799849932008908+0.2822400161197344i) + * 3.to_c #=> (3+0i) + * + * You can also create complex object from floating-point numbers or + * strings. + * + * Complex(0.3) #=> (0.3+0i) + * Complex('0.3-0.5i') #=> (0.3-0.5i) + * Complex('2/3+3/4i') #=> ((2/3)+(3/4)*i) + * Complex('1@2') #=> (-0.4161468365471424+0.9092974268256817i) + * + * 0.3.to_c #=> (0.3+0i) + * '0.3-0.5i'.to_c #=> (0.3-0.5i) + * '2/3+3/4i'.to_c #=> ((2/3)+(3/4)*i) + * '1@2'.to_c #=> (-0.4161468365471424+0.9092974268256817i) + * + * A complex object is either an exact or an inexact number. + * + * Complex(1, 1) / 2 #=> ((1/2)+(1/2)*i) + * Complex(1, 1) / 2.0 #=> (0.5+0.5i) */ void Init_Complex(void) Index: ChangeLog =================================================================== --- ChangeLog (revision 23869) +++ ChangeLog (revision 23870) @@ -1,3 +1,11 @@ +Sat Jun 27 16:45:10 2009 Tadayoshi Funaba <tadf@d...> + + * complex.c: revised rdoc. + + * rational.c: ditto. + + * numeric.c: ditto. + Sat Jun 27 13:44:48 2009 Kouhei Sutou <kou@c...> * NEWS, lib/rss/maker/base.rb, test/rss/test_maker_2.0.rb: add Index: numeric.c =================================================================== --- numeric.c (revision 23869) +++ numeric.c (revision 23870) @@ -103,7 +103,7 @@ /* * call-seq: - * num.coerce(numeric) => array + * num.coerce(numeric) -> array * * If <i>aNumeric</i> is the same type as <i>num</i>, returns an array * containing <i>aNumeric</i> and <i>num</i>. Otherwise, returns an @@ -225,7 +225,7 @@ /* * call-seq: - * +num => num + * +num -> num * * Unary Plus---Returns the receiver's value. */ @@ -238,7 +238,7 @@ /* * call-seq: - * -num => numeric + * -num -> numeric * * Unary Minus---Returns the receiver's value, negated. */ @@ -256,7 +256,7 @@ /* * call-seq: - * num.quo(numeric) => real + * num.quo(numeric) -> real * * Returns most exact division (rational for integers, float for floats). */ @@ -270,7 +270,7 @@ /* * call-seq: - * num.fdiv(numeric) => float + * num.fdiv(numeric) -> float * * Returns float division. */ @@ -284,7 +284,7 @@ /* * call-seq: - * num.div(numeric) => integer + * num.div(numeric) -> integer * * Uses <code>/</code> to perform division, then converts the result to * an integer. <code>numeric</code> does not define the <code>/</code> @@ -306,7 +306,7 @@ /* * call-seq: - * num.modulo(numeric) => real + * num.modulo(numeric) -> real * * x.modulo(y) means x-y*(x/y).floor * @@ -326,7 +326,7 @@ /* * call-seq: - * num.remainder(numeric) => real + * num.remainder(numeric) -> real * * x.remainder(y) means x-y*(x/y).truncate * @@ -350,7 +350,7 @@ /* * call-seq: - * num.divmod(numeric) => array + * num.divmod(numeric) -> array * * Returns an array containing the quotient and modulus obtained by * dividing <i>num</i> by <i>numeric</i>. If <code>q, r = @@ -397,7 +397,7 @@ /* * call-seq: - * num.real? => true or false + * num.real? -> true or false * * Returns <code>true</code> if <i>num</i> is a <code>Real</code> * (i.e. non <code>Complex</code>). @@ -411,7 +411,7 @@ /* * call-seq: - * num.integer? => true or false + * num.integer? -> true or false * * Returns <code>true</code> if <i>num</i> is an <code>Integer</code> * (including <code>Fixnum</code> and <code>Bignum</code>). @@ -425,8 +425,8 @@ /* * call-seq: - * num.abs => numeric - * num.magnitude => numeric + * num.abs -> numeric + * num.magnitude -> numeric * * Returns the absolute value of <i>num</i>. * @@ -447,7 +447,7 @@ /* * call-seq: - * num.zero? => true or false + * num.zero? -> true or false * * Returns <code>true</code> if <i>num</i> has a zero value. */ @@ -464,7 +464,7 @@ /* * call-seq: - * num.nonzero? => self or nil + * num.nonzero? -> self or nil * * Returns <i>self</i> if <i>num</i> is not zero, <code>nil</code> * otherwise. This behavior is useful when chaining comparisons: @@ -485,7 +485,7 @@ /* * call-seq: - * num.to_int => integer + * num.to_int -> integer * * Invokes the child class's <code>to_i</code> method to convert * <i>num</i> to an integer. @@ -519,7 +519,7 @@ /* * call-seq: - * flt.to_s => string + * 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 @@ -573,7 +573,7 @@ /* * call-seq: - * -float => float + * -float -> float * * Returns float, negated. */ @@ -586,7 +586,7 @@ /* * call-seq: - * float + other => float + * float + other -> float * * Returns a new float which is the sum of <code>float</code> * and <code>other</code>. @@ -609,7 +609,7 @@ /* * call-seq: - * float + other => float + * float + other -> float * * Returns a new float which is the difference of <code>float</code> * and <code>other</code>. @@ -632,7 +632,7 @@ /* * call-seq: - * float * other => float + * float * other -> float * * Returns a new float which is the product of <code>float</code> * and <code>other</code>. @@ -655,7 +655,7 @@ /* * call-seq: - * float / other => float + * float / other -> float * * Returns a new float which is the result of dividing * <code>float</code> by <code>other</code>. @@ -718,8 +718,8 @@ /* * call-seq: - * flt % other => float - * flt.modulo(other) => float + * flt % other -> float + * flt.modulo(other) -> float * * Return the modulo after division of <code>flt</code> by <code>other</code>. * @@ -767,7 +767,7 @@ /* * call-seq: - * flt.divmod(numeric) => array + * flt.divmod(numeric) -> array * * See <code>Numeric#divmod</code>. */ @@ -800,7 +800,7 @@ /* * call-seq: * - * flt ** other => float + * flt ** other -> float * * Raises <code>float</code> the <code>other</code> power. * @@ -825,7 +825,7 @@ /* * call-seq: - * num.eql?(numeric) => true or false + * num.eql?(numeric) -> true or false * * Returns <code>true</code> if <i>num</i> and <i>numeric</i> are the * same type and have equal values. @@ -845,7 +845,7 @@ /* * call-seq: - * num <=> other => 0 or nil + * num <=> other -> 0 or nil * * Returns zero if <i>num</i> equals <i>other</i>, <code>nil</code> * otherwise. @@ -867,7 +867,7 @@ /* * call-seq: - * flt == obj => true or false + * 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 @@ -907,7 +907,7 @@ /* * call-seq: - * flt.hash => integer + * flt.hash -> integer * * Returns a hash code for this float. */ @@ -935,7 +935,7 @@ /* * call-seq: - * flt <=> real => -1, 0, +1 + * flt <=> real -> -1, 0, +1 * * Returns -1, 0, or +1 depending on whether <i>flt</i> is less than, * equal to, or greater than <i>real</i>. This is the basis for the @@ -979,7 +979,7 @@ /* * call-seq: - * flt > real => true or false + * flt > real -> true or false * * <code>true</code> if <code>flt</code> is greater than <code>real</code>. */ @@ -1017,7 +1017,7 @@ /* * call-seq: - * flt >= real => true or false + * flt >= real -> true or false * * <code>true</code> if <code>flt</code> is greater than * or equal to <code>real</code>. @@ -1056,7 +1056,7 @@ /* * call-seq: - * flt < real => true or false + * flt < real -> true or false * * <code>true</code> if <code>flt</code> is less than <code>real</code>. */ @@ -1094,7 +1094,7 @@ /* * call-seq: - * flt <= rael => true or false + * flt <= rael -> true or false * * <code>true</code> if <code>flt</code> is less than * or equal to <code>real</code>. @@ -1133,7 +1133,7 @@ /* * call-seq: - * flt.eql?(obj) => true or false + * 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 @@ -1159,7 +1159,7 @@ /* * call-seq: - * flt.to_f => self + * flt.to_f -> self * * As <code>flt</code> is already a float, returns <i>self</i>. */ @@ -1172,8 +1172,8 @@ /* * call-seq: - * flt.abs => float - * flt.magnitude => float + * flt.abs -> float + * flt.magnitude -> float * * Returns the absolute value of <i>flt</i>. * @@ -1191,7 +1191,7 @@ /* * call-seq: - * flt.zero? => true or false + * flt.zero? -> true or false * * Returns <code>true</code> if <i>flt</i> is 0.0. * @@ -1208,7 +1208,7 @@ /* * call-seq: - * flt.nan? => true or false + * flt.nan? -> true or false * * Returns <code>true</code> if <i>flt</i> is an invalid IEEE floating * point number. @@ -1229,7 +1229,7 @@ /* * call-seq: - * flt.infinite? => nil, -1, +1 + * flt.infinite? -> nil, -1, +1 * * Returns <code>nil</code>, -1, or +1 depending on whether <i>flt</i> * is finite, -infinity, or +infinity. @@ -1253,7 +1253,7 @@ /* * call-seq: - * flt.finite? => true or false + * 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 @@ -1279,7 +1279,7 @@ /* * call-seq: - * flt.floor => integer + * flt.floor -> integer * * Returns the largest integer less than or equal to <i>flt</i>. * @@ -1304,7 +1304,7 @@ /* * call-seq: - * flt.ceil => integer + * flt.ceil -> integer * * Returns the smallest <code>Integer</code> greater than or equal to * <i>flt</i>. @@ -1330,10 +1330,10 @@ /* * call-seq: - * flt.round([ndigits]) => integer or float + * flt.round([ndigits]) -> integer or float * * Rounds <i>flt</i> to a given precision in decimal digits (default 0 digits). - * Precision may be negative. Returns a a floating point number when ndigits + * Precision may be negative. Returns a floating point number when ndigits * is more than one. * * 1.5.round #=> 2 @@ -1379,9 +1379,9 @@ /* * call-seq: - * flt.to_i => integer - * flt.to_int => integer - * flt.truncate => integer + * flt.to_i -> integer + * flt.to_int -> integer + * flt.truncate -> integer * * Returns <i>flt</i> truncated to an <code>Integer</code>. */ @@ -1404,7 +1404,7 @@ /* * call-seq: - * num.floor => integer + * num.floor -> integer * * Returns the largest integer less than or equal to <i>num</i>. * <code>Numeric</code> implements this by converting <i>anInteger</i> @@ -1423,7 +1423,7 @@ /* * call-seq: - * num.ceil => integer + * num.ceil -> integer * * Returns the smallest <code>Integer</code> greater than or equal to * <i>num</i>. Class <code>Numeric</code> achieves this by converting @@ -1444,10 +1444,10 @@ /* * call-seq: - * num.round([ndigits]) => integer or float + * num.round([ndigits]) -> integer or float * * Rounds <i>num</i> to a given precision in decimal digits (default 0 digits). - * Precision may be negative. Returns a a floating point number when ndigits + * Precision may be negative. Returns a floating point number when ndigits * is more than one. <code>Numeric</code> implements this by converting itself * to a <code>Float</code> and invoking <code>Float#round</code>. */ @@ -1460,7 +1460,7 @@ /* * call-seq: - * num.truncate => integer + * num.truncate -> integer * * Returns <i>num</i> truncated to an integer. <code>Numeric</code> * implements this by converting its value to a float and invoking @@ -1504,8 +1504,8 @@ /* * call-seq: - * num.step(limit[, step]) {|i| block } => self - * num.step(limit[, step]) => enumerator + * num.step(limit[, step]) {|i| block } -> self + * num.step(limit[, step]) -> enumerator * * Invokes <em>block</em> with the sequence of numbers starting at * <i>num</i>, incremented by <i>step</i> (default 1) on each @@ -1801,12 +1801,12 @@ /* * call-seq: - * int.to_i => integer - * int.to_int => integer - * int.floor => integer - * int.ceil => integer - * int.round => integer - * int.truncate => integer + * int.to_i -> integer + * int.to_int -> integer + * int.floor -> integer + * int.ceil -> integer + * int.round -> integer + * int.truncate -> integer * * As <i>int</i> is already an <code>Integer</code>, all these * methods simply return the receiver. @@ -1820,7 +1820,7 @@ /* * call-seq: - * int.integer? => true + * int.integer? -> true * * Always returns <code>true</code>. */ @@ -1833,7 +1833,7 @@ /* * call-seq: - * int.odd? => true or false + * int.odd? -> true or false * * Returns <code>true</code> if <i>int</i> is an odd number. */ @@ -1849,7 +1849,7 @@ /* * call-seq: - * int.even? => true or false + * int.even? -> true or false * * Returns <code>true</code> if <i>int</i> is an even number. */ @@ -1865,8 +1865,8 @@ /* * call-seq: - * fixnum.next => integer - * fixnum.succ => integer + * fixnum.next -> integer + * fixnum.succ -> integer * * Returns the <code>Integer</code> equal to <i>int</i> + 1. * @@ -1883,8 +1883,8 @@ /* * call-seq: - * int.next => integer - * int.succ => integer + * int.next -> integer + * int.succ -> integer * * Returns the <code>Integer</code> equal to <i>int</i> + 1. * @@ -1904,7 +1904,7 @@ /* * call-seq: - * int.pred => integer + * int.pred -> integer * * Returns the <code>Integer</code> equal to <i>int</i> - 1. * @@ -1924,7 +1924,7 @@ /* * call-seq: - * int.chr([encoding]) => string + * int.chr([encoding]) -> string * * Returns a string containing the character represented by the * receiver's value according to +encoding+. @@ -1981,7 +1981,7 @@ /* * call-seq: - * int.ord => self + * int.ord -> self * * Returns the int itself. * @@ -2020,7 +2020,7 @@ /* * call-seq: - * -fix => integer + * -fix -> integer * * Negates <code>fix</code> (which might return a Bignum). */ @@ -2062,7 +2062,7 @@ /* * call-seq: - * fix.to_s(base=10) => string + * fix.to_s(base=10) -> string * * Returns a string containing the representation of <i>fix</i> radix * <i>base</i> (between 2 and 36). @@ -2093,7 +2093,7 @@ /* * call-seq: - * fix + numeric => numeric_result + * 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 @@ -2126,7 +2126,7 @@ /* * call-seq: - * fix - numeric => numeric_result + * 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 @@ -2164,7 +2164,7 @@ /* * call-seq: - * fix * numeric => numeric_result + * 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 @@ -2246,7 +2246,7 @@ /* * call-seq: - * fix.fdiv(numeric) => float + * fix.fdiv(numeric) -> float * * Returns the floating point result of dividing <i>fix</i> by * <i>numeric</i>. @@ -2308,7 +2308,7 @@ /* * call-seq: - * fix / numeric => numeric_result + * fix / 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 @@ -2323,7 +2323,7 @@ /* * call-seq: - * fix.div(numeric) => integer + * fix.div(numeric) -> integer * * Performs integer division: returns integer value. */ @@ -2336,8 +2336,8 @@ /* * call-seq: - * fix % other => real - * fix.modulo(other) => real + * fix % other -> real + * fix.modulo(other) -> real * * Returns <code>fix</code> modulo <code>other</code>. * See <code>numeric.divmod</code> for more information. @@ -2370,7 +2370,7 @@ /* * call-seq: - * fix.divmod(numeric) => array + * fix.divmod(numeric) -> array * * See <code>Numeric#divmod</code>. */ @@ -2443,7 +2443,7 @@ /* * call-seq: - * fix ** numeric => numeric_result + * fix ** numeric -> numeric_result * * Raises <code>fix</code> to the <code>numeric</code> power, which may * be negative or fractional. @@ -2508,7 +2508,7 @@ /* * call-seq: - * fix == other => true or false + * fix == other -> true or false * * Return <code>true</code> if <code>fix</code> equals <code>other</code> * numerically. @@ -2534,7 +2534,7 @@ /* * call-seq: - * fix <=> numeric => -1, 0, +1 + * 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 @@ -2561,7 +2561,7 @@ /* * call-seq: - * fix > real => true or false + * fix > real -> true or false * * Returns <code>true</code> if the value of <code>fix</code> is * greater than that of <code>real</code>. @@ -2586,7 +2586,7 @@ /* * call-seq: - * fix >= real => true or false + * fix >= real -> true or false * * Returns <code>true</code> if the value of <code>fix</code> is * greater than or equal to that of <code>real</code>. @@ -2611,7 +2611,7 @@ /* * call-seq: - * fix < real => true or false + * fix < real -> true or false * * Returns <code>true</code> if the value of <code>fix</code> is * less than that of <code>real</code>. @@ -2636,7 +2636,7 @@ /* * call-seq: - * fix <= rael => true or false + * fix <= rael -> true or false * * Returns <code>true</code> if the value of <code>fix</code> is * less than or equal to that of <code>real</code>. @@ -2661,7 +2661,7 @@ /* * call-seq: - * ~fix => integer + * ~fix -> integer * * One's complement: returns a number where each bit is flipped. */ @@ -2689,7 +2689,7 @@ /* * call-seq: - * fix & integer => integer_result + * fix & integer -> integer_result * * Bitwise AND. */ @@ -2708,7 +2708,7 @@ /* * call-seq: - * fix | integer => integer_result + * fix | integer -> integer_result * * Bitwise OR. */ @@ -2727,7 +2727,7 @@ /* * call-seq: - * fix ^ integer => integer_result + * fix ^ integer -> integer_result * * Bitwise EXCLUSIVE OR. */ @@ -2749,7 +2749,7 @@ /* * call-seq: - * fix << count => integer + * fix << count -> integer * * Shifts _fix_ left _count_ positions (right if _count_ is negative). */ @@ -2781,7 +2781,7 @@ /* * call-seq: - * fix >> count => integer + * fix >> count -> integer * * Shifts _fix_ right _count_ positions (left if _count_ is negative). */ @@ -2814,7 +2814,7 @@ /* * call-seq: - * fix[n] => 0, 1 + * 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 @@ -2857,7 +2857,7 @@ /* * call-seq: - * fix.to_f => float + * fix.to_f -> float * * Converts <i>fix</i> to a <code>Float</code>. * @@ -2875,8 +2875,8 @@ /* * call-seq: - * fix.abs => integer - * fix.magnitude => integer + * fix.abs -> integer + * fix.magnitude -> integer * * Returns the absolute value of <i>fix</i>. * @@ -2899,7 +2899,7 @@ /* * call-seq: - * fix.size => fixnum + * fix.size -> fixnum * * Returns the number of <em>bytes</em> in the machine representation * of a <code>Fixnum</code>. @@ -2917,8 +2917,8 @@ /* * call-seq: - * int.upto(limit) {|i| block } => self - * int.upto(limit) => enumerator + * int.upto(limit) {|i| block } -> self + * int.upto(limit) -> enumerator * * Iterates <em>block</em>, passing in integer values from <i>int</i> * up to and including <i>limit</i>. @@ -2956,8 +2956,8 @@ /* * call-seq: - * int.downto(limit) {|i| block } => self - * int.downto(limit) => enumerator + * int.downto(limit) {|i| block } -> self + * int.downto(limit) -> enumerator * * Iterates <em>block</em>, passing decreasing values from <i>int</i> * down to and including <i>limit</i>. @@ -2996,8 +2996,8 @@ /* * call-seq: - * int.times {|i| block } => self - * int.times => enumerator + * int.times {|i| block } -> self + * int.times -> enumerator * * Iterates block <i>int</i> times, passing in values from zero to * <i>int</i> - 1. @@ -3075,7 +3075,7 @@ /* * call-seq: - * fix.zero? => true or false + * fix.zero? -> true or false * * Returns <code>true</code> if <i>fix</i> is zero. * @@ -3092,7 +3092,7 @@ /* * call-seq: - * fix.odd? => true or false + * fix.odd? -> true or false * * Returns <code>true</code> if <i>fix</i> is an odd number. */ @@ -3108,7 +3108,7 @@ /* * call-seq: - * fix.even? => true or false + * fix.even? -> true or false * * Returns <code>true</code> if <i>fix</i> is an even number. */ Index: rational.c =================================================================== --- rational.c (revision 23869) +++ rational.c (revision 23870) @@ -502,6 +502,12 @@ return nurat_s_canonicalize_internal_no_reduce(klass, x, y); } +/* + * call-seq: + * Rational(x[, y]) -> numeric + * + * Returns x/y; + */ static VALUE nurat_f_rational(int argc, VALUE *argv, VALUE klass) { @@ -510,17 +516,16 @@ /* * call-seq: - * rat.numerator => integer + * rat.numerator -> integer * - * Returns the numerator of _rat_ as an +Integer+ object. + * Returns the numerator. * * For example: * - * Rational(7).numerator #=> 7 - * Rational(7, 1).numerator #=> 7 - * Rational(4.3, 40.3).numerator #=> 4841369599423283 - * Rational(9, -4).numerator #=> -9 - * Rational(-2, -10).numerator #=> 1 + * Rational(7).numerator #=> 7 + * Rational(7, 1).numerator #=> 7 + * Rational(9, -4).numerator #=> -9 + * Rational(-2, -10).numerator #=> 1 */ static VALUE nurat_numerator(VALUE self) @@ -531,18 +536,17 @@ /* * call-seq: - * rat.denominator => integer + * rat.denominator -> integer * - * Returns the denominator of _rat_ as an +Integer+ object. If _rat_ was - * created without an explicit denominator, +1+ is returned. + * Returns the denominator (always positive). * * For example: * - * Rational(7).denominator #=> 1 - * Rational(7, 1).denominator #=> 1 - * Rational(4.3, 40.3).denominator #=> 45373766245757744 - * Rational(9, -4).denominator #=> 4 - * Rational(-2, -10).denominator #=> 5 + * Rational(7).denominator #=> 1 + * Rational(7, 1).denominator #=> 1 + * Rational(9, -4).denominator #=> 4 + * Rational(-2, -10).denominator #=> 5 + * rat.numerator.gcd(rat.denominator) #=> 1 */ static VALUE nurat_denominator(VALUE self) @@ -638,24 +642,18 @@ /* * call-seq: - * rat + numeric => numeric_result + * rat + numeric -> numeric_result * - * Performs addition. The class of the resulting object depends on - * the class of _numeric_ and on the magnitude of the - * result. + * Performs addition. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. - * * For example: * - * Rational(2, 3) + Rational(2, 3) #=> (4/3) - * Rational(900) + Rational(1) #=> (900/1) - * Rational(-2, 9) + Rational(-9, 2) #=> (-85/18) - * Rational(9, 8) + 4 #=> (41/8) - * Rational(20, 9) + 9.8 #=> 12.022222222222222 - * Rational(8, 7) + 2**20 #=> (7340040/7) + * Rational(2, 3) + Rational(2, 3) #=> (4/3) + * Rational(900) + Rational(1) #=> (900/1) + * Rational(-2, 9) + Rational(-9, 2) #=> (-85/18) + * Rational(9, 8) + 4 #=> (41/8) + * Rational(20, 9) + 9.8 #=> 12.022222222222222 */ - static VALUE nurat_add(VALUE self, VALUE other) { @@ -686,21 +684,17 @@ /* * call-seq: - * rat - numeric => numeric_result + * rat - numeric -> numeric_result * - * Performs subtraction. The class of the resulting object depends on the - * class of _numeric_ and on the magnitude of the result. + * Performs subtraction. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. - * * For example: * - * Rational(2, 3) - Rational(2, 3) #=> (0/1) - * Rational(900) - Rational(1) #=> (899/1) - * Rational(-2, 9) - Rational(-9, 2) #=> (77/18) - * Rational(9, 8) - 4 #=> (23/8) - * Rational(20, 9) - 9.8 #=> -7.577777777777778 - * Rational(8, 7) - 2**20 #=> (-7340024/7) + * Rational(2, 3) - Rational(2, 3) #=> (0/1) + * Rational(900) - Rational(1) #=> (899/1) + * Rational(-2, 9) - Rational(-9, 2) #=> (77/18) + * Rational(9, 8) - 4 #=> (23/8) + * Rational(20, 9) - 9.8 #=> -7.577777777777778 */ static VALUE nurat_sub(VALUE self, VALUE other) @@ -771,21 +765,17 @@ /* * call-seq: - * rat * numeric => numeric_result + * rat * numeric -> numeric_result * - * Performs multiplication. The class of the resulting object depends on - * the class of _numeric_ and on the magnitude of the result. + * Performs multiplication. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. - * * For example: * - * Rational(2, 3) * Rational(2, 3) #=> (4/9) - * Rational(900) * Rational(1) #=> (900/1) - * Rational(-2, 9) * Rational(-9, 2) #=> (1/1) - * Rational(9, 8) * 4 #=> (9/2) - * Rational(20, 9) * 9.8 #=> 21.77777777777778 - * Rational(8, 7) * 2**20 #=> (8388608/7) + * Rational(2, 3) * Rational(2, 3) #=> (4/9) + * Rational(900) * Rational(1) #=> (900/1) + * Rational(-2, 9) * Rational(-9, 2) #=> (1/1) + * Rational(9, 8) * 4 #=> (9/2) + * Rational(20, 9) * 9.8 #=> 21.77777777777778 */ static VALUE nurat_mul(VALUE self, VALUE other) @@ -817,25 +807,18 @@ /* * call-seq: - * rat / numeric => numeric_result - * rat.quo(numeric) => numeric_result + * rat / numeric -> numeric_result + * rat.quo(numeric) -> numeric_result * - * Performs division. The class of the resulting object depends on the class - * of _numeric_ and on the magnitude of the result. + * Performs division. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. A - * +ZeroDivisionError+ is raised if _numeric_ is 0. - * * For example: * - * Rational(2, 3) / Rational(2, 3) #=> (1/1) - * Rational(900) / Rational(1) #=> (900/1) - * Rational(-2, 9) / Rational(-9, 2) #=> (4/81) - * Rational(9, 8) / 4 #=> (9/32) - * Rational(20, 9) / 9.8 #=> 0.22675736961451246 - * Rational(8, 7) / 2**20 #=> (1/917504) - * Rational(2, 13) / 0 #=> ZeroDivisionError: divided by zero - * Rational(2, 13) / 0.0 #=> Infinity + * Rational(2, 3) / Rational(2, 3) #=> (1/1) + * Rational(900) / Rational(1) #=> (900/1) + * Rational(-2, 9) / Rational(-9, 2) #=> (4/81) + * Rational(9, 8) / 4 #=> (9/32) + * Rational(20, 9) / 9.8 #=> 0.22675736961451246 */ static VALUE nurat_div(VALUE self, VALUE other) @@ -871,20 +854,15 @@ /* * call-seq: - * rat.fdiv(numeric) => float + * rat.fdiv(numeric) -> float * - * Performs float division: dividing _rat_ by _numeric_. The return value is a - * +Float+ object. + * Performs division and returns the value as a float. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. - * * For example: * - * Rational(2, 3).fdiv(1) #=> 0.6666666666666666 - * Rational(2, 3).fdiv(0.5) #=> 1.3333333333333333 - * Rational(2).fdiv(3) #=> 0.6666666666666666 - * Rational(-9, 6.6).fdiv(6.6) #=> -0.20661157024793392 - * Rational(-20).fdiv(0.0) #=> -Infinity + * Rational(2, 3).fdiv(1) #=> 0.6666666666666666 + * Rational(2, 3).fdiv(0.5) #=> 1.3333333333333333 + * Rational(2).fdiv(3) #=> 0.6666666666666666 */ static VALUE nurat_fdiv(VALUE self, VALUE other) @@ -894,23 +872,18 @@ /* * call-seq: - * rat ** numeric => numeric_result + * rat ** numeric -> numeric_result * - * Performs exponentiation, i.e. it raises _rat_ to the exponent _numeric_. - * The class of the resulting object depends on the class of _numeric_ and on - * the magnitude of the result. A +TypeError+ is raised unless _numeric_ is a - * +Numeric+ object. + * Performs exponentiation. * * For example: * - * Rational(2, 3) ** Rational(2, 3) #=> 0.7631428283688879 - * Rational(900) ** Rational(1) #=> (900/1) - * Rational(-2, 9) ** Rational(-9, 2) #=> (4.793639101185069e-13-869.8739233809262i) - * Rational(9, 8) ** 4 #=> (6561/4096) - * Rational(20, 9) ** 9.8 #=> 2503.325740344559 - * Rational(3, 2) ** 2**3 #=> (6561/256) - * Rational(2, 13) ** 0 #=> (1/1) - * Rational(2, 13) ** 0.0 #=> 1.0 + * Rational(2) ** Rational(3) #=> (8/1) + * Rational(10) ** -2 #=> (1/100) + * Rational(10) ** -2.0 #=> 0.01 + * Rational(-4) ** Rational(1,2) #=> (1.2246063538223773e-16+2.0i) + * Rational(1, 2) ** 0 #=> (1/1) + * Rational(1, 2) ** 0.0 #=> 1.0 */ static VALUE nurat_expt(VALUE self, VALUE other) @@ -961,24 +934,17 @@ /* * call-seq: - * rat <=> numeric => -1, 0, +1 + * rat <=> numeric -> -1, 0 or +1 * - * Performs comparison. Returns -1, 0, or +1 depending on whether _rat_ is - * less than, equal to, or greater than _numeric_. This is the basis for the - * tests in +Comparable+. + * Performs comparison and returns -1, 0, or +1. * - * A +TypeError+ is raised unless _numeric_ is a +Numeric+ object. - * * For example: * - * Rational(2, 3) <=> Rational(2, 3) #=> 0 - * Rational(5) <=> 5 #=> 0 - * Rational(900) <=> Rational(1) #=> 1 - * Rational(-2, 9) <=> Rational(-9, 2) #=> 1 - * Rational(9, 8) <=> 4 #=> -1 - * Rational(20, 9) <=> 9.8 #=> -1 - * Rational(5, 3) <=> 'string' #=> TypeError: String can't - * # be coerced into Rational + * Rational(2, 3) <=> Rational(2, 3) #=> 0 + * Rational(5) <=> 5 #=> 0 + * Rational(2,3) <=> Rational(1,3) #=> 1 + * Rational(1,3) <=> 1 #=> -1 + * Rational(1,3) <=> 0.3 #=> 1 */ static VALUE nurat_cmp(VALUE self, VALUE other) @@ -1019,19 +985,17 @@ /* * call-seq: - * rat == object => true or false + * rat == object -> true or false * - * Tests for equality. Returns +true+ if _rat_ is equal to _object_; +false+ - * otherwise. + * Returns true if rat equals object numerically. * * For example: * - * Rational(2, 3) == Rational(2, 3) #=> true - * Rational(5) == 5 #=> true - * Rational(7, 1) == Rational(7) #=> true - * Rational(-2, 9) == Rational(-9, 2) #=> false - * Rational(9, 8) == 4 #=> false - * Rational(5, 3) == 'string' #=> false + * Rational(2, 3) == Rational(2, 3) #=> true + * Rational(5) == 5 #=> true + * Rational(0) == 0.0 #=> true + * Rational('1/3') == 0.33 #=> false + * Rational('1/2') == '1/2' #=> false */ static VALUE nurat_equal_p(VALUE self, VALUE other) @@ -1070,6 +1034,7 @@ } } +/* :nodoc: */ static VALUE nurat_coerce(VALUE self, VALUE other) { @@ -1095,12 +1060,18 @@ #if 0 /* :nodoc: */ static VALUE +nurat_idiv(VALUE self, VALUE other) +{ + return f_idiv(self, other); +} + +/* :nodoc: */ +static VALUE nurat_quot(VALUE self, VALUE other) { return f_truncate(f_div(self, other)); } - /* :nodoc: */ static VALUE nurat_quotrem(VALUE self, VALUE other) @@ -1136,20 +1107,20 @@ /* * call-seq: - * rat.to_i => integer + * rat.to_i -> integer * - * Returns _rat_ truncated to an integer as an +Integer+ object. + * Returns the truncated value as an integer. * - * Equivalent to - * <i>rat</i>.<code>truncate(</code>. + * Equivalent to + * rat.truncate. * * For example: * - * Rational(2, 3).to_i #=> 0 - * Rational(3).to_i #=> 3 - * Rational(300.6).to_i #=> 300 - * Rational(98,71).to_i #=> 1 - * Rational(-30,2).to_i #=> -15 + * Rational(2, 3).to_i #=> 0 + * Rational(3).to_i #=> 3 + * Rational(300.6).to_i #=> 300 + * Rational(98,71).to_i #=> 1 + * Rational(-30,2).to_i #=> -15 */ static VALUE nurat_truncate(VALUE self) @@ -1213,32 +1184,23 @@ /* * call-seq: - * rat.floor => integer - * rat.floor(precision=0) => rational + * rat.floor -> integer + * rat.floor(precision=0) -> rational * - * Returns the largest integer less than or equal to _rat_ as an +Integer+ - * object. Contrast with +Rational#ceil+. + * Returns the truncated value (toward negative infinity). * - * An optional _precision_ argument can be supplied as an +Integer+. If - * _precision_ is positive the result is rounded downwards to that number of - * decimal places. If _precision_ is negative, the result is rounded downwards - * to the nearest 10**_precision_. By default _precision_ is equal to 0, - * causing the result to be a whole number. - * * For example: * - * Rational(2, 3).floor #=> 0 - * Rational(3).floor #=> 3 - * Rational(300.6).floor #=> 300 - * Rational(98,71).floor #=> 1 - * Rational(-30,2).floor #=> -15 - * Rational(-30,-11).floor #=> 2 + * Rational(3).floor #=> 3 + * Rational(2, 3).floor #=> 0 + * Rational(-3, 2).floor #=> -1 * - * Rational(-1.125).floor(2).to_f #=> -1.13 - * Rational(-1.125).floor(1).to_f #=> -1.2 - * Rational(-1.125).floor.to_f #=> -2.0 - * Rational(-1.125).floor(-1).to_f #=> -10.0 - * Rational(-1.125).floor(-2).to_f #=> -100.0 + * decimal - 1 2 3 . 4 5 6 + * ^ ^ ^ ^ ^ ^ + * precision -3 -2 -1 0 +1 +2 + * + * '%f' % Rational('-123.456').floor(+1) #=> "-123.500000" + * '%f' % Rational('-123.456').floor(-1) #=> "-130.000000" */ static VALUE nurat_floor_n(int argc, VALUE *argv, VALUE self) @@ -1248,32 +1210,23 @@ /* * call-seq: - * rat.ceil => integer - * rat.ceil(precision=0) => rational + * rat.ceil -> integer + * rat.ceil(precision=0) -> rational * - * Returns the smallest integer greater than or equal to _rat_ as an +Integer+ - * object. Contrast with +Rational#floor+. + * Returns the truncated value (toward positive infinity). * - * An optional _precision_ argument can be supplied as an +Integer+. If - * _precision_ is positive the result is rounded upwards to that number of - * decimal places. If _precision_ is negative, the result is rounded upwards - * to the nearest 10**_precision_. By default _precision_ is equal to 0, - * causing the result to be a whole number. - * * For example: * - * Rational(2, 3).ceil #=> 1 - * Rational(3).ceil #=> 3 - * Rational(300.6).ceil #=> 301 - * Rational(98, 71).ceil #=> 2 - * Rational(-30, 2).ceil #=> -15 - * Rational(-30,-11).ceil #=> 3 + * Rational(3).ceil #=> 3 + * Rational(2, 3).ceil #=> 1 + * Rational(-3, 2).ceil #=> -1 * - * Rational(-1.125).ceil(2).to_f #=> -1.12 - * Rational(-1.125).ceil(1).to_f #=> -1.1 - * Rational(-1.125).ceil.to_f #=> -1.0 - * Rational(-1.125).ceil(-1).to_f #=> 0.0 - * Rational(-1.125).ceil(-2).to_f #=> 0.0 + * decimal - 1 2 3 . 4 5 6 + * ^ ^ ^ ^ ^ ^ + * precision -3 -2 -1 0 +1 +2 + * + * '%f' % Rational('-123.456').ceil(+1) #=> "-123.400000" + * '%f' % Rational('-123.456').ceil(-1) #=> "-120.000000" */ static VALUE nurat_ceil_n(int argc, VALUE *argv, VALUE self) @@ -1283,31 +1236,23 @@ /* * call-seq: - * rat.truncate => integer - * rat.truncate(precision=0) => rational + * rat.truncate -> integer + * rat.truncate(precision=0) -> rational * - * Truncates self to an integer and returns the result as an +Integer+ object. + * Returns the truncated value (toward zero). * - * An optional _precision_ argument can be supplied as an +Integer+. If - * _precision_ is positive the result is rounded downwards to that number of - * decimal places. If _precision_ is negative, the result is rounded downwards - * to the nearest 10**_precision_. By default _precision_ is equal to 0, - * causing the result to be a whole number. - * * For example: * - * Rational(2, 3).truncate #=> 0 - * Rational(3).truncate #=> 3 - * Rational(300.6).truncate #=> 300 - * Rational(98,71).truncate #=> 1 - * Rational(-30,2).truncate #=> -15 - * Rational(-30, -11).truncate #=> 2 + * Rational(3).truncate #=> 3 + * Rational(2, 3).truncate #=> 0 + * Rational(-3, 2).truncate #=> -1 * - * Rational(-123.456).truncate(2).to_f #=> -123.45 - * Rational(-123.456).truncate(1).to_f #=> -123.4 - * Rational(-123.456).truncate.to_f #=> -123.0 - * Rational(-123.456).truncate(-1).to_f #=> -120.0 - * Rational(-123.456).truncate(-2).to_f #=> -100.0 + * decimal - 1 2 3 . 4 5 6 + * ^ ^ ^ ^ ^ ^ + * precision -3 -2 -1 0 +1 +2 + * + * '%f' % Rational('-123.456').truncate(+1) #=> "-123.400000" + * '%f' % Rational('-123.456').truncate(-1) #=> "-120.000000" */ static VALUE nurat_truncate_n(int argc, VALUE *argv, VALUE self) @@ -1317,33 +1262,24 @@ /* * call-seq: - * rat.round => integer - * rat.round(precision=0) => rational + * rat.round -> integer + * rat.round(precision=0) -> rational * - * Rounds _rat_ to an integer, and returns the result as an +Integer+ object. + * Returns the truncated value (toward the nearest integer; + * 0.5 => 1; -0.5 => -1). * - * An optional _precision_ argument can be supplied as an +Integer+. If - * _precision_ is positive the result is rounded to that number of decimal - * places. If _precision_ is negative, the result is rounded to the nearest - * 10**_precision_. By default _precision_ is equal to 0, causing the result - * to be a whole number. - * - * A +TypeError+ is raised if _integer_ is given and not an +Integer+ object. - * * For example: * - * Rational(9, 3.3).round #=> 3 - * Rational(9, 3.3).round(1) #=> (27/10) - * Rational(9,3.3).round(2) #=> (273/100) - * Rational(8, 7).round(5) #=> (57143/50000) - * Rational(-20, -3).round #=> 7 + * Rational(3).round #=> 3 + * Rational(2, 3).round #=> 1 + * Rational(-3, 2).round #=> -2 * - * Rational(-123.456).round(2).to_f #=> -123.46 - * Rational(-123.456).round(1).to_f #=> -123.5 - * Rational(-123.456).round.to_f #=> -123.0 - * Rational(-123.456).round(-1).to_f #=> -120.0 - * Rational(-123.456).round(-2).to_f #=> -100.0 + * decimal - 1 2 3 . 4 5 6 + * ^ ^ ^ ^ ^ ^ + * precision -3 -2 -1 0 +1 +2 * + * '%f' % Rational('-123.456').round(+1) #=> "-123.500000" + * '%f' % Rational('-123.456').round(-1) #=> "-120.000000" */ static VALUE nurat_round_n(int argc, VALUE *argv, VALUE self) @@ -1353,17 +1289,16 @@ /* * call-seq: - * rat.to_f => float + * rat.to_f -> float * - * Converts _rat_ to a floating point number and returns the result as a - * +Float+ object. + * Return the value as a float. * * For example: * - * Rational(2).to_f #=> 2.0 - * Rational(9, 4).to_f #=> 2.25 - * Rational(-3, 4).to_f #=> -0.75 - * Rational(20, 3).to_f #=> 6.666666666666667 + * Rational(2).to_f #=> 2.0 + * Rational(9, 4).to_f #=> 2.25 + * Rational(-3, 4).to_f #=> -0.75 + * Rational(20, 3).to_f #=> 6.666666666666667 */ static VALUE nurat_to_f(VALUE self) @@ -1374,15 +1309,14 @@ /* * call-seq: - * rat.to_r => self + * rat.to_r -> self * - * Returns self, i.e. a +Rational+ object representing _rat_. + * Returns self. * * For example: * - * Rational(2).to_r #=> (2/1) - * Rational(-8, 6).to_r #=> (-4/3) - * Rational(39.2).to_r #=> (2758454771764429/70368744177664) + * Rational(2).to_r #=> (2/1) + * Rational(-8, 6).to_r #=> (-4/3) */ static VALUE nurat_to_r(VALUE self) @@ -1390,6 +1324,7 @@ return self; } +/* :nodoc: */ static VALUE nurat_hash(VALUE self) { @@ -1421,16 +1356,15 @@ /* * call-seq: - * rat.to_s => string + * rat.to_s -> string * - * Returns a +String+ representation of _rat_ in the form - * "_numerator_/_denominator_". + * Returns the value as a string. * * For example: * - * Rational(2).to_s #=> "2/1" - * Rational(-8, 6).to_s #=> "-4/3" - * Rational(0.5).to_s #=> "1/2" + * Rational(2).to_s #=> "2/1" + * Rational(-8, 6).to_s #=> "-4/3" + * Rational('0.5').to_s #=> "1/2" */ static VALUE nurat_to_s(VALUE self) @@ -1440,16 +1374,15 @@ /* * call-seq: - * rat.inspect => string + * rat.inspect -> string * - * Returns a +String+ containing a human-readable representation of _rat_ in - * the form "(_numerator_/_denominator_)". + * Returns the value as a string for inspection. * * For example: * - * Rational(2).to_s #=> "(2/1)" - * Rational(-8, 6).to_s #=> "(-4/3)" - * Rational(0.5).to_s #=> "(1/2)" + * Rational(2).inspect #=> "(2/1)" + * Rational(-8, 6).inspect #=> "(-4/3)" + * Rational('0.5').inspect #=> "(1/2)" */ static VALUE nurat_inspect(VALUE self) @@ -1494,20 +1427,16 @@ /* * call-seq: - * int.gcd(_int2_) => integer + * int.gcd(int2) -> integer * - * Returns the greatest common divisor of _int_ and _int2_: the largest - * positive integer that divides the two without a remainder. The result is an - * +Integer+ object. + * Returns the greatest common divisor (always positive). 0.gcd(x) + * and x.gcd(0) return abs(x). * - * An +ArgumentError+ is raised unless _int2_ is an +Integer+ object. - * * For example: * - * 2.gcd(2) #=> 2 - * -2.gcd(2) #=> 2 - * 8.gcd(6) #=> 2 - * 25.gcd(5) #=> 5 + * 2.gcd(2) #=> 2 + * 3.gcd(-7) #=> 1 + * ((1<<31)-1).gcd((1<<61)-1) #=> 1 */ VALUE rb_gcd(VALUE self, VALUE other) @@ -1518,20 +1447,16 @@ /* * call-seq: - * int.lcm(_int2_) => integer + * int.lcm(int2) -> integer * - * Returns the least common multiple (or "lowest common multiple") of _int_ - * and _int2_: the smallest positive integer that is a multiple of both - * integers. The result is an +Integer+ object. + * Returns the least common multiple (always positive). 0.lcm(x) and + * x.lcm(0) return zero. * - * An +ArgumentError+ is raised unless _int2_ is an +Integer+ object. - * * For example: * - * 2.lcm(2) #=> 2 - * -2.gcd(2) #=> 2 - * 8.gcd(6) #=> 24 - * 8.lcm(9) #=> 72 + * 2.lcm(2) #=> 2 + * 3.lcm(-7) #=> 21 + * ((1<<31)-1).lcm((1<<61)-1) #=> 4951760154835678088235319297 */ VALUE rb_lcm(VALUE self, VALUE other) @@ -1542,22 +1467,15 @@ /* * call-seq: - * int.gcdlcm(_int2_) => array + * int.gcdlcm(int2) -> array * - * Returns a two-element +Array+ containing _int_.gcd(_int2_) and - * _int_.lcm(_int2_) respectively. That is, the greatest common divisor of - * _int_ and _int2_, then the least common multiple of _int_ and _int2_. Both - * elements are +Integer+ objects. + * Returns an array; [int.gcd(int2), int.lcm(int2)]. * - * An +ArgumentError+ is raised unless _int2_ is an +Integer+ object. - * * For example: * - * 2.gcdlcm(2) #=> [2, 2] - * -2.gcdlcm(2) #=> [2, 2] - * 8.gcdlcm(6) #=> [2, 24] - * 8.gcdlcm(9) #=> [1, 72] - * 9.gcdlcm(9**9) #=> [9, 387420489] + * 2.gcdlcm(2) #=> [2, 2] + * 3.gcdlcm(-7) #=> [1, 21] + * ((1<<31)-1).gcdlcm((1<<61)-1) #=> [1, 4951760154835678088235319297] */ VALUE rb_gcdlcm(VALUE self, VALUE other) @@ -1600,9 +1518,9 @@ /* * call-seq: - * num.numerator => integer + * num.numerator -> integer * - * Returns the numerator of _num_ as an +Integer+ object. + * Returns the numerator. */ static VALUE numeric_numerator(VALUE self) @@ -1612,9 +1530,9 @@ /* * call-seq: - * num.denominator => integer + * num.denominator -> integer * - * Returns the denominator of _num_ as an +Integer+ object. + * Returns the denominator (always positive). */ static VALUE numeric_denominator(VALUE self) @@ -1624,7 +1542,7 @@ /* * call-seq: - * int.numerator => self + * int.numerator -> self * * Returns self. */ @@ -1636,7 +1554,7 @@ /* * call-seq: - * int.numerator => 1 + * int.numerator -> 1 * * Returns 1. */ @@ -1648,15 +1566,15 @@ /* * call-seq: - * flo.numerator => integer + * flo.numerator -> integer * - * Returns the numerator of _flo_ as an +Integer+ object. + * Returns the numerator. The result is machine dependent. * * For example: * - * n = 0.3.numerator #=> 5404319552844595 # machine dependent - * d = 0.3.denominator #=> 18014398509481984 # machine dependent - * n.fdiv(d) #=> 0.3 + * n = 0.3.numerator #=> 5404319552844595 + * d = 0.3.denominator #=> 18014398509481984 + * n.fdiv(d) #=> 0.3 */ static VALUE float_numerator(VALUE self) @@ -1669,11 +1587,12 @@ /* * call-seq: - * flo.denominator => integer + * flo.denominator -> integer * - * Returns the denominator of _flo_ as an +Integer+ object. + * Returns the denominator (always positive). The result is machine + * dependent. * - * See Float#numerator. + * See numerator. */ static VALUE float_denominator(VALUE self) @@ -1686,9 +1605,9 @@ /* * call-seq: - * nil.to_r => (0/1) + * nil.to_r -> (0/1) * - * Returns a +Rational+ object representing _nil_ as a rational number. + * Returns zero as a rational. */ static VALUE nilclass_to_r(VALUE self) @@ -1698,14 +1617,14 @@ /* * call-seq: - * int.to_r => rational + * int.to_r -> rational * - * Returns a +Rational+ object representing _int_ as a rational number. + * Returns the value as a rational. * * For example: * - * 1.to_r #=> (1/1) - * 12.to_r #=> (12/1) + * 1.to_r #=> (1/1) + * (1<<64).to_r #=> (18446744073709551616/1) */ static VALUE integer_to_r(VALUE self) @@ -1739,18 +1658,19 @@ /* * call-seq: - * flt.to_r => rational + * flt.to_r -> rational * - * Returns _flt_ as an +Rational+ object. Raises a +FloatDomainError+ if _flt_ - * is +Infinity+ or +NaN+. + * Returns the value as a rational. * + * NOTE: 0.3.to_r isn't the same as '0.3'.to_r. The latter is + * equivalent to '3/10'.to_r, but the former isn't so. + * * For example: * - * 2.0.to_r #=> (2/1) - * 2.5.to_r #=> (5/2) - * -0.75.to_r #=> (-3/4) - * 0.0.to_r #=> (0/1) - * (1/0.0).to_r #=> FloatDomainError: Infinity + * 2.0.to_r #=> (2/1) + * 2.5.to_r #=> (5/2) + * -0.75.to_r #=> (-3/4) + * 0.0.to_r #=> (0/1) */ static VALUE float_to_r(VALUE self) @@ -1898,21 +1818,26 @@ /* * call-seq: - * str.to_r => rational + * str.to_r -> rational * - * Returns a +Rational+ object representing _string_ as a rational number. - * Leading and trailing whitespace is ignored. Underscores may be used to - * separate numbers. If _string_ is not recognised as a rational, (0/1) is - * returned. + * Returns a rational which denotes the string form. The parser + * ignores leading whitespaces and trailing garbage. Any digit + * sequences can be separeted by an underscore. Returns zero for null + * or garbage string. * + * NOTE: '0.3'.to_r isn't the same as 0.3.to_r. The former is + * equivalent to '3/10'.to_r, but the latter isn't so. + * * For example: * - * "2".to_r #=> (2/1) - * "300/2".to_r #=> (150/1) - * "-9.2/3".to_r #=> (-46/15) - * " 2/9 ".to_r #=> (2/9) - * "2_9".to_r #=> (29/1) - * "?".to_r #=> (0/1) + * ' 2 '.to_r #=> (2/1) + * '300/2'.to_r #=> (150/1) + * '-9.2'.to_r #=> (-46/5) + * '-9.2e2'.to_r #=> (-920/1) + * '1_234_567'.to_r #=> (1234567/1) + * '21 june 09'.to_r #=> (21/1) + * '21/06/09'.to_r #=> (7/2) + * 'bwv 1079'.to_r #=> (0/1) */ static VALUE string_to_r(VALUE self) @@ -2011,68 +1936,43 @@ } /* - * A +Rational+ object represents a rational number, which is any number that - * can be expressed as the quotient a/b of two integers (where the denominator - * is nonzero). Given that b may be equal to 1, every integer is rational. + * A rational number can be represented as a paired integer number; + * a/b (b>0). Where a is numerator and b is denominator. Integer a + * equals rational a/1 mathematically. * - * A +Rational+ object can be created with the +Rational()+ constructor: + * In ruby, you can create rational object with Rational or to_r + * method. The return values will be irreducible. * - * Rational(1) #=> (1/1) - * Rational(2, 3) #=> (2/3) - * Rational(0.5) #=> (1/2) - * Rational("2/7") #=> (2/7) - * Rational("0.25") #=> (1/4) - * Rational("10e3") #=> (10000/1) + * Rational(1) #=> (1/1) + * Rational(2, 3) #=> (2/3) + * Rational(4, -6) #=> (-2/3) + * 3.to_r #=> (3/1) * - * The first argument is the numerator, the second the denominator. If the - * denominator is not supplied it defaults to 1. The arguments can be - * +Numeric+ or +String+ objects. + * You can also create ratioanl object from floating-point numbers or + * strings. * - * Rational(12) == Rational(12, 1) #=> true + * Rational(0.3) #=> (5404319552844595/18014398509481984) + * Rational('0.3') #=> (3/10) + * Rational('2/3') #=> (2/3) * - * A +ZeroDivisionError+ will be raised if 0 is specified as the denominator: + * 0.3.to_r #=> (5404319552844595/18014398509481984) + * '0.3'.to_r #=> (3/10) + * '2/3'.to_r #=> (2/3) * - * Rational(3, 0) #=> ZeroDivisionError: divided by zero + * A rational object is an exact number, which helps you to write + * program without any rounding errors. * - * The numerator and denominator of a +Rational+ object can be retrieved with - * the +Rational#numerator+ and +Rational#denominator+ accessors, - * respectively. + * 10.times.inject(0){|t,| t + 0.1} #=> 0.9999999999999999 + * 10.times.inject(0){|t,| t + Rational('0.1')} #=> (1/1) * - * rational = Rational(4, 7) #=> (4/7) - * rational.numerator #=> 4 - * rational.denominator #=> 7 + * However, when an expression has inexact factor (numerical value or + * operation), will produce an inexact result. * - * A +Rational+ is automatically reduced into its simplest form: + * Rational(10) / 3 #=> (10/3) + * Rational(10) / 3.0 #=> 3.3333333333333335 * - * Rational(10, 2) #=> (5/1) - * - * +Numeric+ and +String+ objects can be converted into a +Rational+ with - * their +#to_r+ methods. - * - * 30.to_r #=> (30/1) - * 3.33.to_r #=> (1874623344892969/562949953421312) - * '33/3'.to_r #=> (11/1) - * - * The reverse operations work as you would expect: - * - * Rational(30, 1).to_i #=> 30 - * Rational(1874623344892969, 562949953421312).to_f #=> 3.33 - * Rational(11, 1).to_s #=> "11/1" - * - * +Rational+ objects can be compared with other +Numeric+ objects using the - * normal semantics: - * - * Rational(20, 10) == Rational(2, 1) #=> true - * Rational(10) > Rational(1) #=> true - * Rational(9, 2) <=> Rational(8, 3) #=> 1 - * - * Similarly, standard mathematical operations support +Rational+ objects, too: - * - * Rational(9, 2) * 2 #=> (9/1) - * Rational(12, 29) / Rational(2,3) #=> (18/29) - * Rational(7,5) + Rational(60) #=> (307/5) - * Rational(22, 5) - Rational(5, 22) #=> (459/110) - * Rational(2,3) ** 3 #=> (8/27) + * Rational(-8) ** Rational(1, 3) + * #=> (1.0000000000000002+1.7320508075688772i) */ void Init_Rational(void) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/