From d4199057bc9767d05bc05e90a4ce5de642306396 Mon Sep 17 00:00:00 2001 From: tadf Date: Sat, 3 Nov 2012 14:39:50 +0000 Subject: * complex.c: modified doc. * rational.c: ditto. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37460 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- complex.c | 129 +++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 94 insertions(+), 35 deletions(-) (limited to 'complex.c') diff --git a/complex.c b/complex.c index 94a28f0278..f2f524011c 100644 --- a/complex.c +++ b/complex.c @@ -440,8 +440,7 @@ nucomp_s_canonicalize_internal(VALUE klass, VALUE real, VALUE imag) * * Returns a complex object which denotes the given rectangular form. * - * For example: - * Complex.rect(12, 2) # => (12+2i) + * Complex.rectangular(1, 2) #=> (1+2i) */ static VALUE nucomp_s_new(int argc, VALUE *argv, VALUE klass) @@ -481,6 +480,8 @@ f_complex_new2(VALUE klass, VALUE x, VALUE y) * Complex(x[, y]) -> numeric * * Returns x+i*y; + * + * Complex(1, 2) #=> (1+2i) */ static VALUE nucomp_f_complex(int argc, VALUE *argv, VALUE klass) @@ -590,10 +591,10 @@ f_complex_polar(VALUE klass, VALUE x, VALUE y) * * Returns a complex object which denotes the given polar form. * - * Complex.polar(3, 0) #=> (3.0+0.0i) - * Complex.polar(3, Math::PI/2) #=> (1.836909530733566e-16+3.0i) - * Complex.polar(3, Math::PI) #=> (-3.0+3.673819061467132e-16i) - * Complex.polar(3, -Math::PI/2) #=> (1.836909530733566e-16-3.0i) + * Complex.polar(3, 0) #=> (3.0+0.0i) + * Complex.polar(3, Math::PI/2) #=> (1.836909530733566e-16+3.0i) + * Complex.polar(3, Math::PI) #=> (-3.0+3.673819061467132e-16i) + * Complex.polar(3, -Math::PI/2) #=> (1.836909530733566e-16-3.0i) */ static VALUE nucomp_s_polar(int argc, VALUE *argv, VALUE klass) @@ -618,6 +619,9 @@ nucomp_s_polar(int argc, VALUE *argv, VALUE klass) * cmp.real -> real * * Returns the real part. + * + * Complex(7).real #=> 7 + * Complex(9, -4).real #=> 9 */ static VALUE nucomp_real(VALUE self) @@ -632,6 +636,9 @@ nucomp_real(VALUE self) * cmp.imaginary -> real * * Returns the imaginary part. + * + * Complex(7).imaginary #=> 0 + * Complex(9, -4).imaginary #=> -4 */ static VALUE nucomp_imag(VALUE self) @@ -645,6 +652,8 @@ nucomp_imag(VALUE self) * -cmp -> complex * * Returns negation of the value. + * + * -Complex(1, 2) #=> (-1-2i) */ static VALUE nucomp_negate(VALUE self) @@ -683,10 +692,11 @@ f_addsub(VALUE self, VALUE other, * * Performs addition. * - * Complex(5, 2) + 3 # => (8+2i) - * Complex(5, 2) + 3.i # => (5+5i) - * Complex(5, 2) + Complex(3, 4) # => (8+6i) - * + * Complex(2, 3) + Complex(2, 3) #=> (4+6i) + * Complex(900) + Complex(1) #=> (901+0i) + * Complex(-2, 9) + Complex(-9, 2) #=> (-11+11i) + * Complex(9, 8) + 4 #=> (13+8i) + * Complex(20, 9) + 9.8 #=> (29.8+9i) */ static VALUE nucomp_add(VALUE self, VALUE other) @@ -700,7 +710,11 @@ nucomp_add(VALUE self, VALUE other) * * Performs subtraction. * - * Complex(33, 12) - 10 # => (23+12i) + * Complex(2, 3) - Complex(2, 3) #=> (0+0i) + * Complex(900) - Complex(1) #=> (899+0i) + * Complex(-2, 9) - Complex(-9, 2) #=> (7+7i) + * Complex(9, 8) - 4 #=> (5+8i) + * Complex(20, 9) - 9.8 #=> (10.2+9i) */ static VALUE nucomp_sub(VALUE self, VALUE other) @@ -714,7 +728,11 @@ nucomp_sub(VALUE self, VALUE other) * * Performs multiplication. * - * Complex(78, 58) * 10 # => (780+580i) + * Complex(2, 3) * Complex(2, 3) #=> (-5+12i) + * Complex(900) * Complex(1) #=> (900+0i) + * Complex(-2, 9) * Complex(-9, 2) #=> (0-85i) + * Complex(9, 8) * 4 #=> (36+32i) + * Complex(20, 9) * 9.8 #=> (196.0+88.2i) */ static VALUE nucomp_mul(VALUE self, VALUE other) @@ -802,10 +820,11 @@ f_divide(VALUE self, VALUE other, * * 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(2, 3) / Complex(2, 3) #=> ((1/1)+(0/1)*i) + * Complex(900) / Complex(1) #=> ((900/1)+(0/1)*i) + * Complex(-2, 9) / Complex(-9, 2) #=> ((36/85)-(77/85)*i) + * Complex(9, 8) / 4 #=> ((9/4)+(2/1)*i) + * Complex(20, 9) / 9.8 #=> (2.0408163265306123+0.9183673469387754i) */ static VALUE nucomp_div(VALUE self, VALUE other) @@ -821,9 +840,7 @@ nucomp_div(VALUE self, VALUE other) * * 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) @@ -843,10 +860,8 @@ f_reciprocal(VALUE x) * * 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) @@ -932,6 +947,12 @@ nucomp_expt(VALUE self, VALUE other) * cmp == object -> true or false * * Returns true if cmp equals object numerically. + * + * Complex(2, 3) == Complex(2, 3) #=> true + * Complex(5) == 5 #=> true + * Complex(0) == 0.0 #=> true + * Complex('1/3') == 0.33 #=> false + * Complex('1/2') == '1/2' #=> false */ static VALUE nucomp_eqeq_p(VALUE self, VALUE other) @@ -970,6 +991,9 @@ nucomp_coerce(VALUE self, VALUE other) * cmp.magnitude -> real * * Returns the absolute part of its polar form. + * + * Complex(-1).abs #=> 1 + * Complex(3.0, -4.0).abs #=> 5.0 */ static VALUE nucomp_abs(VALUE self) @@ -996,6 +1020,9 @@ nucomp_abs(VALUE self) * cmp.abs2 -> real * * Returns square of the absolute value. + * + * Complex(-1).abs2 #=> 1 + * Complex(3.0, -4.0).abs2 #=> 25.0 */ static VALUE nucomp_abs2(VALUE self) @@ -1013,8 +1040,7 @@ nucomp_abs2(VALUE self) * * Returns the angle part of its polar form. * - * Complex.polar(3, Math::PI/2).arg #=> 1.5707963267948966 - * + * Complex.polar(3, Math::PI/2).arg #=> 1.5707963267948966 */ static VALUE nucomp_arg(VALUE self) @@ -1029,6 +1055,8 @@ nucomp_arg(VALUE self) * cmp.rectangular -> array * * Returns an array; [cmp.real, cmp.imag]. + * + * Complex(1, 2).rectangular #=> [1, 2] */ static VALUE nucomp_rect(VALUE self) @@ -1042,6 +1070,8 @@ nucomp_rect(VALUE self) * cmp.polar -> array * * Returns an array; [cmp.abs, cmp.arg]. + * + * Complex(1, 2).polar #=> [2.23606797749979, 1.1071487177940904] */ static VALUE nucomp_polar(VALUE self) @@ -1055,6 +1085,8 @@ nucomp_polar(VALUE self) * cmp.conjugate -> complex * * Returns the complex conjugate. + * + * Complex(1, 2).conjugate #=> (1-2i) */ static VALUE nucomp_conj(VALUE self) @@ -1122,8 +1154,6 @@ nucomp_denominator(VALUE self) * * Returns the numerator. * - * For example: - * * 1 2 3+4i <- numerator * - + -i -> ---- * 2 3 6 <- denominator @@ -1229,6 +1259,12 @@ f_format(VALUE self, VALUE (*func)(VALUE)) * cmp.to_s -> string * * Returns the value as a string. + * + * Complex(2).to_s #=> "2+0i" + * Complex('-8/6').to_s #=> "-4/3+0i" + * Complex('1/2i').to_s #=> "0+1/2i" + * Complex(0, Float::INFINITY).to_s #=> "0+Infinity*i" + * Complex(Float::NAN, Float::NAN).to_s #=> "NaN+NaN*i" */ static VALUE nucomp_to_s(VALUE self) @@ -1241,6 +1277,12 @@ nucomp_to_s(VALUE self) * cmp.inspect -> string * * Returns the value as a string for inspection. + * + * Complex(2).inspect #=> "(2+0i)" + * Complex('-8/6').inspect #=> "((-4/3)+0i)" + * Complex('1/2i').inspect #=> "(0+(1/2)*i)" + * Complex(0, Float::INFINITY).inspect #=> "(0+Infinity*i)" + * Complex(Float::NAN, Float::NAN).inspect #=> "(NaN+NaN*i)" */ static VALUE nucomp_inspect(VALUE self) @@ -1331,7 +1373,12 @@ rb_Complex(VALUE x, VALUE y) * call-seq: * cmp.to_i -> integer * - * Returns the value as an integer if possible. + * Returns the value as an integer if possible (the imaginary part + * should be exactly zero). + * + * Complex(1, 0).to_i #=> 1 + * Complex(1, 0.0).to_i # RangeError + * Complex(1, 2).to_i # RangeError */ static VALUE nucomp_to_i(VALUE self) @@ -1350,7 +1397,12 @@ nucomp_to_i(VALUE self) * call-seq: * cmp.to_f -> float * - * Returns the value as a float if possible. + * Returns the value as a float if possible (the imaginary part should + * be exactly zero). + * + * Complex(1, 0).to_f #=> 1.0 + * Complex(1, 0.0).to_f # RangeError + * Complex(1, 2).to_f # RangeError */ static VALUE nucomp_to_f(VALUE self) @@ -1369,8 +1421,12 @@ nucomp_to_f(VALUE self) * call-seq: * cmp.to_r -> rational * - * If the imaginary part is exactly 0, returns the real part as a Rational, - * otherwise a RangeError is raised. + * Returns the value as a rational if possible (the imaginary part + * should be exactly zero). + * + * Complex(1, 0).to_r #=> (1/1) + * Complex(1, 0.0).to_r # RangeError + * Complex(1, 2).to_r # RangeError */ static VALUE nucomp_to_r(VALUE self) @@ -1389,8 +1445,13 @@ nucomp_to_r(VALUE self) * call-seq: * cmp.rationalize([eps]) -> rational * - * If the imaginary part is exactly 0, returns the real part as a Rational, - * otherwise a RangeError is raised. + * Returns the value as a rational if possible (the imaginary part + * should be exactly zero). The optional argument eps is always + * ignored. + * + * Complex(1.0/3, 0).rationalize #=> (1/3) + * Complex(1, 0.0).rationalize # RangeError + * Complex(1, 2).rationalize # RangeError */ static VALUE nucomp_rationalize(int argc, VALUE *argv, VALUE self) @@ -1594,8 +1655,6 @@ string_to_c_strict(VALUE self) * sequences can be separated by an underscore. Returns zero for null * or garbage string. * - * For example: - * * '9'.to_c #=> (9+0i) * '2.5'.to_c #=> (2.5+0i) * '2.5/1'.to_c #=> ((5/2)+0i) -- cgit v1.2.3