diff options
Diffstat (limited to 'complex.c')
| -rw-r--r-- | complex.c | 1118 |
1 files changed, 772 insertions, 346 deletions
@@ -24,6 +24,7 @@ #include "internal/numeric.h" #include "internal/object.h" #include "internal/rational.h" +#include "internal/string.h" #include "ruby_assert.h" #define ZERO INT2FIX(0) @@ -391,11 +392,12 @@ k_numeric_p(VALUE x) inline static VALUE nucomp_s_new_internal(VALUE klass, VALUE real, VALUE imag) { - NEWOBJ_OF(obj, struct RComplex, klass, T_COMPLEX | (RGENGC_WB_PROTECTED_COMPLEX ? FL_WB_PROTECTED : 0)); + NEWOBJ_OF(obj, struct RComplex, klass, + T_COMPLEX | (RGENGC_WB_PROTECTED_COMPLEX ? FL_WB_PROTECTED : 0), sizeof(struct RComplex), 0); RCOMPLEX_SET_REAL(obj, real); RCOMPLEX_SET_IMAG(obj, imag); - OBJ_FREEZE_RAW((VALUE)obj); + OBJ_FREEZE((VALUE)obj); return (VALUE)obj; } @@ -409,15 +411,15 @@ nucomp_s_alloc(VALUE klass) inline static VALUE f_complex_new_bang1(VALUE klass, VALUE x) { - assert(!RB_TYPE_P(x, T_COMPLEX)); + RUBY_ASSERT(!RB_TYPE_P(x, T_COMPLEX)); return nucomp_s_new_internal(klass, x, ZERO); } inline static VALUE f_complex_new_bang2(VALUE klass, VALUE x, VALUE y) { - assert(!RB_TYPE_P(x, T_COMPLEX)); - assert(!RB_TYPE_P(y, T_COMPLEX)); + RUBY_ASSERT(!RB_TYPE_P(x, T_COMPLEX)); + RUBY_ASSERT(!RB_TYPE_P(y, T_COMPLEX)); return nucomp_s_new_internal(klass, x, y); } @@ -430,7 +432,7 @@ nucomp_real_check(VALUE num) !RB_TYPE_P(num, T_RATIONAL)) { if (RB_TYPE_P(num, T_COMPLEX) && nucomp_real_p(num)) { VALUE real = RCOMPLEX(num)->real; - assert(!RB_TYPE_P(real, T_COMPLEX)); + RUBY_ASSERT(!RB_TYPE_P(real, T_COMPLEX)); return real; } if (!k_numeric_p(num) || !f_real_p(num)) @@ -473,12 +475,19 @@ nucomp_s_canonicalize_internal(VALUE klass, VALUE real, VALUE imag) /* * call-seq: - * Complex.rect(real[, imag]) -> complex - * Complex.rectangular(real[, imag]) -> complex + * Complex.rect(real, imag = 0) -> complex * - * Returns a complex object which denotes the given rectangular form. + * Returns a new \Complex object formed from the arguments, + * each of which must be an instance of Numeric, + * or an instance of one of its subclasses: + * \Complex, Float, Integer, Rational; + * see {Rectangular Coordinates}[rdoc-ref:Complex@Rectangular+Coordinates]: * - * Complex.rectangular(1, 2) #=> (1+2i) + * Complex.rect(3) # => (3+0i) + * Complex.rect(3, Math::PI) # => (3+3.141592653589793i) + * Complex.rect(-3, -Math::PI) # => (-3-3.141592653589793i) + * + * \Complex.rectangular is an alias for \Complex.rect. */ static VALUE nucomp_s_new(int argc, VALUE *argv, VALUE klass) @@ -515,39 +524,54 @@ static VALUE nucomp_s_convert(int argc, VALUE *argv, VALUE klass); /* * call-seq: - * Complex(x[, y], exception: true) -> numeric or nil - * - * Returns x+i*y; - * - * Complex(1, 2) #=> (1+2i) - * Complex('1+2i') #=> (1+2i) - * Complex(nil) #=> TypeError - * Complex(1, nil) #=> TypeError - * - * Complex(1, nil, exception: false) #=> nil - * Complex('1+2', exception: false) #=> nil - * - * Syntax of string form: - * - * string form = extra spaces , complex , extra spaces ; - * complex = real part | [ sign ] , imaginary part - * | real part , sign , imaginary part - * | rational , "@" , rational ; - * real part = rational ; - * imaginary part = imaginary unit | unsigned rational , imaginary unit ; - * rational = [ sign ] , unsigned rational ; - * unsigned rational = numerator | numerator , "/" , denominator ; - * numerator = integer part | fractional part | integer part , fractional part ; - * denominator = digits ; - * integer part = digits ; - * fractional part = "." , digits , [ ( "e" | "E" ) , [ sign ] , digits ] ; - * imaginary unit = "i" | "I" | "j" | "J" ; - * sign = "-" | "+" ; - * digits = digit , { digit | "_" , digit }; - * digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; - * extra spaces = ? \s* ? ; - * - * See String#to_c. + * Complex(real, imag = 0, exception: true) -> complex or nil + * Complex(s, exception: true) -> complex or nil + * + * Returns a new \Complex object if the arguments are valid; + * otherwise raises an exception if +exception+ is +true+; + * otherwise returns +nil+. + * + * With Numeric arguments +real+ and +imag+, + * returns <tt>Complex.rect(real, imag)</tt> if the arguments are valid. + * + * With string argument +s+, returns a new \Complex object if the argument is valid; + * the string may have: + * + * - One or two numeric substrings, + * each of which specifies a Complex, Float, Integer, Numeric, or Rational value, + * specifying {rectangular coordinates}[rdoc-ref:Complex@Rectangular+Coordinates]: + * + * - Sign-separated real and imaginary numeric substrings + * (with trailing character <tt>'i'</tt>): + * + * Complex('1+2i') # => (1+2i) + * Complex('+1+2i') # => (1+2i) + * Complex('+1-2i') # => (1-2i) + * Complex('-1+2i') # => (-1+2i) + * Complex('-1-2i') # => (-1-2i) + * + * - Real-only numeric string (without trailing character <tt>'i'</tt>): + * + * Complex('1') # => (1+0i) + * Complex('+1') # => (1+0i) + * Complex('-1') # => (-1+0i) + * + * - Imaginary-only numeric string (with trailing character <tt>'i'</tt>): + * + * Complex('1i') # => (0+1i) + * Complex('+1i') # => (0+1i) + * Complex('-1i') # => (0-1i) + * + * - At-sign separated real and imaginary rational substrings, + * each of which specifies a Rational value, + * specifying {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates]: + * + * Complex('1/2@3/4') # => (0.36584443443691045+0.34081938001166706i) + * Complex('+1/2@+3/4') # => (0.36584443443691045+0.34081938001166706i) + * Complex('+1/2@-3/4') # => (0.36584443443691045-0.34081938001166706i) + * Complex('-1/2@+3/4') # => (-0.36584443443691045-0.34081938001166706i) + * Complex('-1/2@-3/4') # => (-0.36584443443691045+0.34081938001166706i) + * */ static VALUE nucomp_f_complex(int argc, VALUE *argv, VALUE klass) @@ -697,14 +721,19 @@ rb_dbl_complex_new_polar_pi(double abs, double ang) /* * call-seq: - * Complex.polar(abs[, arg]) -> complex + * Complex.polar(abs, arg = 0) -> complex + * + * Returns a new \Complex object formed from the arguments, + * each of which must be an instance of Numeric, + * or an instance of one of its subclasses: + * \Complex, Float, Integer, Rational. + * Argument +arg+ is given in radians; + * see {Polar Coordinates}[rdoc-ref:Complex@Polar+Coordinates]: * - * Returns a complex object which denotes the given polar form. + * Complex.polar(3) # => (3+0i) + * Complex.polar(3, 2.0) # => (-1.2484405096414273+2.727892280477045i) + * Complex.polar(-3, -2.0) # => (1.2484405096414273+2.727892280477045i) * - * 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) @@ -724,12 +753,19 @@ nucomp_s_polar(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * cmp.real -> real + * real -> numeric + * + * Returns the real value for +self+: * - * Returns the real part. + * Complex.rect(7).real # => 7 + * Complex.rect(9, -4).real # => 9 + * + * If +self+ was created with + * {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates], the returned value + * is computed, and may be inexact: + * + * Complex.polar(1, Math::PI/4).real # => 0.7071067811865476 # Square root of 2. * - * Complex(7).real #=> 7 - * Complex(9, -4).real #=> 9 */ VALUE rb_complex_real(VALUE self) @@ -740,13 +776,19 @@ rb_complex_real(VALUE self) /* * call-seq: - * cmp.imag -> real - * cmp.imaginary -> real + * imag -> numeric + * + * Returns the imaginary value for +self+: + * + * Complex.rect(7).imag # => 0 + * Complex.rect(9, -4).imag # => -4 + * + * If +self+ was created with + * {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates], the returned value + * is computed, and may be inexact: * - * Returns the imaginary part. + * Complex.polar(1, Math::PI/4).imag # => 0.7071067811865476 # Square root of 2. * - * Complex(7).imaginary #=> 0 - * Complex(9, -4).imaginary #=> -4 */ VALUE rb_complex_imag(VALUE self) @@ -757,11 +799,13 @@ rb_complex_imag(VALUE self) /* * call-seq: - * -cmp -> complex + * -self -> complex * - * Returns negation of the value. + * Returns +self+, negated, which is the negation of each of its parts: + * + * -Complex.rect(1, 2) # => (-1-2i) + * -Complex.rect(-1, -2) # => (1+2i) * - * -Complex(1, 2) #=> (-1-2i) */ VALUE rb_complex_uminus(VALUE self) @@ -772,16 +816,26 @@ rb_complex_uminus(VALUE self) } /* - * call-seq: - * cmp + numeric -> complex + * call-seq: + * self + other -> numeric + * + * Returns the sum of +self+ and +other+: + * + * Complex(1, 2) + 0 # => (1+2i) + * Complex(1, 2) + 1 # => (2+2i) + * Complex(1, 2) + -1 # => (0+2i) + * + * Complex(1, 2) + 1.0 # => (2.0+2i) + * + * Complex(1, 2) + Complex(2, 1) # => (3+3i) + * Complex(1, 2) + Complex(2.0, 1.0) # => (3.0+3.0i) * - * Performs addition. + * Complex(1, 2) + Rational(1, 1) # => ((2/1)+2i) + * Complex(1, 2) + Rational(1, 2) # => ((3/2)+2i) * - * 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) + * For a computation involving Floats, the result may be inexact (see Float#+): + * + * Complex(1, 2) + 3.14 # => (4.140000000000001+2i) */ VALUE rb_complex_plus(VALUE self, VALUE other) @@ -807,15 +861,16 @@ rb_complex_plus(VALUE self, VALUE other) /* * call-seq: - * cmp - numeric -> complex + * self - other -> complex + * + * Returns the difference of +self+ and +other+: * - * Performs subtraction. + * Complex.rect(2, 3) - Complex.rect(2, 3) # => (0+0i) + * Complex.rect(900) - Complex.rect(1) # => (899+0i) + * Complex.rect(-2, 9) - Complex.rect(-9, 2) # => (7+7i) + * Complex.rect(9, 8) - 4 # => (5+8i) + * Complex.rect(20, 9) - 9.8 # => (10.2+9i) * - * 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) */ VALUE rb_complex_minus(VALUE self, VALUE other) @@ -867,15 +922,17 @@ comp_mul(VALUE areal, VALUE aimag, VALUE breal, VALUE bimag, VALUE *real, VALUE /* * call-seq: - * cmp * numeric -> complex + * self * other -> numeric + * + * Returns the numeric product of +self+ and +other+: * - * Performs multiplication. + * Complex.rect(9, 8) * 4 # => (36+32i) + * Complex.rect(20, 9) * 9.8 # => (196.0+88.2i) + * Complex.rect(2, 3) * Complex.rect(2, 3) # => (-5+12i) + * Complex.rect(900) * Complex.rect(1) # => (900+0i) + * Complex.rect(-2, 9) * Complex.rect(-9, 2) # => (0-85i) + * Complex.rect(9, 8) * Rational(2, 3) # => ((6/1)+(16/3)*i) * - * 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) */ VALUE rb_complex_mul(VALUE self, VALUE other) @@ -942,16 +999,16 @@ f_divide(VALUE self, VALUE other, /* * call-seq: - * cmp / numeric -> complex - * cmp.quo(numeric) -> complex + * self / other -> complex * - * Performs division. + * Returns the quotient of +self+ and +other+: + * + * Complex.rect(2, 3) / Complex.rect(2, 3) # => (1+0i) + * Complex.rect(900) / Complex.rect(1) # => (900+0i) + * Complex.rect(-2, 9) / Complex.rect(-9, 2) # => ((36/85)-(77/85)*i) + * Complex.rect(9, 8) / 4 # => ((9/4)+2i) + * Complex.rect(20, 9) / 9.8 # => (2.0408163265306123+0.9183673469387754i) * - * 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) */ VALUE rb_complex_div(VALUE self, VALUE other) @@ -963,11 +1020,12 @@ rb_complex_div(VALUE self, VALUE other) /* * call-seq: - * cmp.fdiv(numeric) -> complex + * fdiv(numeric) -> new_complex + * + * Returns <tt>Complex.rect(self.real/numeric, self.imag/numeric)</tt>: * - * Performs division as each part is a float, never returns a float. + * Complex.rect(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) @@ -981,14 +1039,96 @@ f_reciprocal(VALUE x) return f_quo(ONE, x); } +static VALUE +zero_for(VALUE x) +{ + if (RB_FLOAT_TYPE_P(x)) + return DBL2NUM(0); + if (RB_TYPE_P(x, T_RATIONAL)) + return rb_rational_new(INT2FIX(0), INT2FIX(1)); + + return INT2FIX(0); +} + +static VALUE +complex_pow_for_special_angle(VALUE self, VALUE other) +{ + if (!rb_integer_type_p(other)) { + return Qundef; + } + + get_dat1(self); + VALUE x = Qundef; + int dir; + if (f_zero_p(dat->imag)) { + x = dat->real; + dir = 0; + } + else if (f_zero_p(dat->real)) { + x = dat->imag; + dir = 2; + } + else if (f_eqeq_p(dat->real, dat->imag)) { + x = dat->real; + dir = 1; + } + else if (f_eqeq_p(dat->real, f_negate(dat->imag))) { + x = dat->imag; + dir = 3; + } + else { + dir = 0; + } + + if (UNDEF_P(x)) return x; + + if (f_negative_p(x)) { + x = f_negate(x); + dir += 4; + } + + VALUE zx; + if (dir % 2 == 0) { + zx = rb_num_pow(x, other); + } + else { + zx = rb_num_pow( + rb_funcall(rb_int_mul(TWO, x), '*', 1, x), + rb_int_div(other, TWO) + ); + if (rb_int_odd_p(other)) { + zx = rb_funcall(zx, '*', 1, x); + } + } + static const int dirs[][2] = { + {1, 0}, {1, 1}, {0, 1}, {-1, 1}, {-1, 0}, {-1, -1}, {0, -1}, {1, -1} + }; + int z_dir = FIX2INT(rb_int_modulo(rb_int_mul(INT2FIX(dir), other), INT2FIX(8))); + + VALUE zr = Qfalse, zi = Qfalse; + switch (dirs[z_dir][0]) { + case 0: zr = zero_for(zx); break; + case 1: zr = zx; break; + case -1: zr = f_negate(zx); break; + } + switch (dirs[z_dir][1]) { + case 0: zi = zero_for(zx); break; + case 1: zi = zx; break; + case -1: zi = f_negate(zx); break; + } + return nucomp_s_new_internal(CLASS_OF(self), zr, zi); +} + + /* * call-seq: - * cmp ** numeric -> complex + * self ** exponent -> complex + * + * Returns +self+ raised to the power +exponent+: * - * Performs exponentiation. + * Complex.rect(0, 1) ** 2 # => (-1+0i) + * Complex.rect(-8) ** Rational(1, 3) # => (1.0000000000000002+1.7320508075688772i) * - * Complex('i') ** 2 #=> (-1+0i) - * Complex(-8) ** Rational(1, 3) #=> (1.0000000000000002+1.7320508075688772i) */ VALUE rb_complex_pow(VALUE self, VALUE other) @@ -1006,6 +1146,14 @@ rb_complex_pow(VALUE self, VALUE other) other = dat->real; /* c14n */ } + if (other == ONE) { + get_dat1(self); + return nucomp_s_new_internal(CLASS_OF(self), dat->real, dat->imag); + } + + VALUE result = complex_pow_for_special_angle(self, other); + if (!UNDEF_P(result)) return result; + if (RB_TYPE_P(other, T_COMPLEX)) { VALUE r, theta, nr, ntheta; @@ -1078,15 +1226,13 @@ rb_complex_pow(VALUE self, VALUE other) /* * call-seq: - * cmp == object -> true or false + * self == other -> true or false + * + * Returns whether both <tt>self.real == other.real</tt> + * and <tt>self.imag == other.imag</tt>: * - * Returns true if cmp equals object numerically. + * Complex.rect(2, 3) == Complex.rect(2.0, 3.0) # => true * - * 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) @@ -1114,17 +1260,30 @@ nucomp_real_p(VALUE self) /* * call-seq: - * cmp <=> object -> 0, 1, -1, or nil + * self <=> other -> -1, 0, 1, or nil + * + * Compares +self+ and +other+. + * + * Returns: + * + * - <tt>self.real <=> other.real</tt> if both of the following are true: * - * If +cmp+'s imaginary part is zero, and +object+ is also a - * real number (or a Complex number where the imaginary part is zero), - * compare the real part of +cmp+ to object. Otherwise, return nil. + * - <tt>self.imag == 0</tt>. + * - <tt>other.imag == 0</tt> (always true if +other+ is numeric but not complex). * - * Complex(2, 3) <=> Complex(2, 3) #=> nil - * Complex(2, 3) <=> 1 #=> nil - * Complex(2) <=> 1 #=> 1 - * Complex(2) <=> 2 #=> 0 - * Complex(2) <=> 3 #=> -1 + * - +nil+ otherwise. + * + * Examples: + * + * Complex.rect(2) <=> 3 # => -1 + * Complex.rect(2) <=> 2 # => 0 + * Complex.rect(2) <=> 1 # => 1 + * Complex.rect(2, 1) <=> 1 # => nil # self.imag not zero. + * Complex.rect(1) <=> Complex.rect(1, 1) # => nil # object.imag not zero. + * Complex.rect(1) <=> 'Foo' # => nil # object.imag not defined. + * + * \Class \Complex includes module Comparable, + * each of whose methods uses Complex#<=> for comparison. */ static VALUE nucomp_cmp(VALUE self, VALUE other) @@ -1169,13 +1328,19 @@ nucomp_coerce(VALUE self, VALUE other) /* * call-seq: - * cmp.abs -> real - * cmp.magnitude -> real + * abs -> float + * + * Returns the absolute value (magnitude) for +self+; + * see {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates]: + * + * Complex.polar(-1, 0).abs # => 1.0 + * + * If +self+ was created with + * {rectangular coordinates}[rdoc-ref:Complex@Rectangular+Coordinates], the returned value + * is computed, and may be inexact: * - * Returns the absolute part of its polar form. + * Complex.rectangular(1, 1).abs # => 1.4142135623730951 # The square root of 2. * - * Complex(-1).abs #=> 1 - * Complex(3.0, -4.0).abs #=> 5.0 */ VALUE rb_complex_abs(VALUE self) @@ -1199,12 +1364,19 @@ rb_complex_abs(VALUE self) /* * call-seq: - * cmp.abs2 -> real + * abs2 -> float * - * Returns square of the absolute value. + * Returns square of the absolute value (magnitude) for +self+; + * see {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates]: + * + * Complex.polar(2, 2).abs2 # => 4.0 + * + * If +self+ was created with + * {rectangular coordinates}[rdoc-ref:Complex@Rectangular+Coordinates], the returned value + * is computed, and may be inexact: + * + * Complex.rectangular(1.0/3, 1.0/3).abs2 # => 0.2222222222222222 * - * Complex(-1).abs2 #=> 1 - * Complex(3.0, -4.0).abs2 #=> 25.0 */ static VALUE nucomp_abs2(VALUE self) @@ -1216,13 +1388,19 @@ nucomp_abs2(VALUE self) /* * call-seq: - * cmp.arg -> float - * cmp.angle -> float - * cmp.phase -> float + * arg -> float + * + * Returns the argument (angle) for +self+ in radians; + * see {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates]: + * + * Complex.polar(3, Math::PI/2).arg # => 1.57079632679489660 * - * Returns the angle part of its polar form. + * If +self+ was created with + * {rectangular coordinates}[rdoc-ref:Complex@Rectangular+Coordinates], the returned value + * is computed, and may be inexact: + * + * Complex.polar(1, 1.0/3).arg # => 0.33333333333333326 * - * Complex.polar(3, Math::PI/2).arg #=> 1.5707963267948966 */ VALUE rb_complex_arg(VALUE self) @@ -1233,12 +1411,22 @@ rb_complex_arg(VALUE self) /* * call-seq: - * cmp.rect -> array - * cmp.rectangular -> array + * rect -> array + * + * Returns the array <tt>[self.real, self.imag]</tt>: + * + * Complex.rect(1, 2).rect # => [1, 2] + * + * See {Rectangular Coordinates}[rdoc-ref:Complex@Rectangular+Coordinates]. + * + * If +self+ was created with + * {polar coordinates}[rdoc-ref:Complex@Polar+Coordinates], the returned value + * is computed, and may be inexact: + * + * Complex.polar(1.0, 1.0).rect # => [0.5403023058681398, 0.8414709848078965] * - * Returns an array; [cmp.real, cmp.imag]. * - * Complex(1, 2).rectangular #=> [1, 2] + * Complex#rectangular is an alias for Complex#rect. */ static VALUE nucomp_rect(VALUE self) @@ -1249,11 +1437,20 @@ nucomp_rect(VALUE self) /* * call-seq: - * cmp.polar -> array + * polar -> array * - * Returns an array; [cmp.abs, cmp.arg]. + * Returns the array <tt>[self.abs, self.arg]</tt>: + * + * Complex.polar(1, 2).polar # => [1.0, 2.0] + * + * See {Polar Coordinates}[rdoc-ref:Complex@Polar+Coordinates]. + * + * If +self+ was created with + * {rectangular coordinates}[rdoc-ref:Complex@Rectangular+Coordinates], the returned value + * is computed, and may be inexact: + * + * Complex.rect(1, 1).polar # => [1.4142135623730951, 0.7853981633974483] * - * Complex(1, 2).polar #=> [2.23606797749979, 1.1071487177940904] */ static VALUE nucomp_polar(VALUE self) @@ -1263,12 +1460,12 @@ nucomp_polar(VALUE self) /* * call-seq: - * cmp.conj -> complex - * cmp.conjugate -> complex + * conj -> complex + * + * Returns the conjugate of +self+, <tt>Complex.rect(self.imag, self.real)</tt>: * - * Returns the complex conjugate. + * Complex.rect(1, 2).conj # => (1-2i) * - * Complex(1, 2).conjugate #=> (1-2i) */ VALUE rb_complex_conjugate(VALUE self) @@ -1279,10 +1476,9 @@ rb_complex_conjugate(VALUE self) /* * call-seq: - * Complex(1).real? -> false - * Complex(1, 2).real? -> false + * real? -> false * - * Returns false, even if the complex number has no imaginary part. + * Returns +false+; for compatibility with Numeric#real?. */ static VALUE nucomp_real_p_m(VALUE self) @@ -1292,11 +1488,17 @@ nucomp_real_p_m(VALUE self) /* * call-seq: - * cmp.denominator -> integer + * denominator -> integer * - * Returns the denominator (lcm of both denominator - real and imag). + * Returns the denominator of +self+, which is + * the {least common multiple}[https://en.wikipedia.org/wiki/Least_common_multiple] + * of <tt>self.real.denominator</tt> and <tt>self.imag.denominator</tt>: * - * See numerator. + * Complex.rect(Rational(1, 2), Rational(2, 3)).denominator # => 6 + * + * Note that <tt>n.denominator</tt> of a non-rational numeric is +1+. + * + * Related: Complex#numerator. */ static VALUE nucomp_denominator(VALUE self) @@ -1307,21 +1509,23 @@ nucomp_denominator(VALUE self) /* * call-seq: - * cmp.numerator -> numeric + * numerator -> new_complex + * + * Returns the \Complex object created from the numerators + * of the real and imaginary parts of +self+, + * after converting each part to the + * {lowest common denominator}[https://en.wikipedia.org/wiki/Lowest_common_denominator] + * of the two: * - * Returns the numerator. + * c = Complex.rect(Rational(2, 3), Rational(3, 4)) # => ((2/3)+(3/4)*i) + * c.numerator # => (8+9i) * - * 1 2 3+4i <- numerator - * - + -i -> ---- - * 2 3 6 <- denominator + * In this example, the lowest common denominator of the two parts is 12; + * the two converted parts may be thought of as \Rational(8, 12) and \Rational(9, 12), + * whose numerators, respectively, are 8 and 9; + * so the returned value of <tt>c.numerator</tt> is <tt>Complex.rect(8, 9)</tt>. * - * 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 denominator. + * Related: Complex#denominator. */ static VALUE nucomp_numerator(VALUE self) @@ -1354,6 +1558,18 @@ rb_complex_hash(VALUE self) return v; } +/* + * :call-seq: + * hash -> integer + * + * Returns the integer hash value for +self+. + * + * Two \Complex objects created from the same values will have the same hash value + * (and will compare using #eql?): + * + * Complex.rect(1, 2).hash == Complex.rect(1, 2).hash # => true + * + */ static VALUE nucomp_hash(VALUE self) { @@ -1392,16 +1608,15 @@ f_tpositive_p(VALUE x) } static VALUE -f_format(VALUE self, VALUE (*func)(VALUE)) +f_format(VALUE self, VALUE s, VALUE (*func)(VALUE)) { - VALUE s; int impos; get_dat1(self); impos = f_tpositive_p(dat->imag); - s = (*func)(dat->real); + rb_str_concat(s, (*func)(dat->real)); rb_str_cat2(s, !impos ? "-" : "+"); rb_str_concat(s, (*func)(f_abs(dat->imag))); @@ -1414,33 +1629,35 @@ f_format(VALUE self, VALUE (*func)(VALUE)) /* * call-seq: - * cmp.to_s -> string + * to_s -> string + * + * Returns a string representation of +self+: * - * Returns the value as a string. + * Complex.rect(2).to_s # => "2+0i" + * Complex.rect(-8, 6).to_s # => "-8+6i" + * Complex.rect(0, Rational(1, 2)).to_s # => "0+1/2i" + * Complex.rect(0, Float::INFINITY).to_s # => "0+Infinity*i" + * Complex.rect(Float::NAN, Float::NAN).to_s # => "NaN+NaN*i" * - * 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) { - return f_format(self, rb_String); + return f_format(self, rb_usascii_str_new2(""), rb_String); } /* * call-seq: - * cmp.inspect -> string + * inspect -> string * - * Returns the value as a string for inspection. + * Returns a string representation of +self+: + * + * Complex.rect(2).inspect # => "(2+0i)" + * Complex.rect(-8, 6).inspect # => "(-8+6i)" + * Complex.rect(0, Rational(1, 2)).inspect # => "(0+(1/2)*i)" + * Complex.rect(0, Float::INFINITY).inspect # => "(0+Infinity*i)" + * Complex.rect(Float::NAN, Float::NAN).inspect # => "(NaN+NaN*i)" * - * 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) @@ -1448,7 +1665,7 @@ nucomp_inspect(VALUE self) VALUE s; s = rb_usascii_str_new2("("); - rb_str_concat(s, f_format(self, rb_inspect)); + f_format(self, s, rb_inspect); rb_str_cat2(s, ")"); return s; @@ -1458,10 +1675,15 @@ nucomp_inspect(VALUE self) /* * call-seq: - * cmp.finite? -> true or false + * finite? -> true or false + * + * Returns +true+ if both <tt>self.real.finite?</tt> and <tt>self.imag.finite?</tt> + * are true, +false+ otherwise: + * + * Complex.rect(1, 1).finite? # => true + * Complex.rect(Float::INFINITY, 0).finite? # => false * - * Returns +true+ if +cmp+'s real and imaginary parts are both finite numbers, - * otherwise returns +false+. + * Related: Numeric#finite?, Float#finite?. */ static VALUE rb_complex_finite_p(VALUE self) @@ -1473,15 +1695,15 @@ rb_complex_finite_p(VALUE self) /* * call-seq: - * cmp.infinite? -> nil or 1 + * infinite? -> 1 or nil * - * Returns +1+ if +cmp+'s real or imaginary part is an infinite number, - * otherwise returns +nil+. + * Returns +1+ if either <tt>self.real.infinite?</tt> or <tt>self.imag.infinite?</tt> + * is true, +nil+ otherwise: * - * For example: + * Complex.rect(Float::INFINITY, 0).infinite? # => 1 + * Complex.rect(1, 1).infinite? # => nil * - * (1+1i).infinite? #=> nil - * (Float::INFINITY + 1i).infinite? #=> 1 + * Related: Numeric#infinite?, Float#infinite?. */ static VALUE rb_complex_infinite_p(VALUE self) @@ -1509,7 +1731,7 @@ nucomp_loader(VALUE self, VALUE a) RCOMPLEX_SET_REAL(dat, rb_ivar_get(a, id_i_real)); RCOMPLEX_SET_IMAG(dat, rb_ivar_get(a, id_i_imag)); - OBJ_FREEZE_RAW(self); + OBJ_FREEZE(self); return self; } @@ -1557,12 +1779,6 @@ rb_complex_new_polar(VALUE x, VALUE y) } VALUE -rb_complex_polar(VALUE x, VALUE y) -{ - return rb_complex_new_polar(x, y); -} - -VALUE rb_Complex(VALUE x, VALUE y) { VALUE a[2]; @@ -1579,14 +1795,15 @@ rb_dbl_complex_new(double real, double imag) /* * call-seq: - * cmp.to_i -> integer + * to_i -> integer + * + * Returns the value of <tt>self.real</tt> as an Integer, if possible: * - * Returns the value as an integer if possible (the imaginary part - * should be exactly zero). + * Complex.rect(1, 0).to_i # => 1 + * Complex.rect(1, Rational(0, 1)).to_i # => 1 * - * Complex(1, 0).to_i #=> 1 - * Complex(1, 0.0).to_i # RangeError - * Complex(1, 2).to_i # RangeError + * Raises RangeError if <tt>self.imag</tt> is not exactly zero + * (either <tt>Integer(0)</tt> or <tt>Rational(0, n)</tt>). */ static VALUE nucomp_to_i(VALUE self) @@ -1602,14 +1819,15 @@ nucomp_to_i(VALUE self) /* * call-seq: - * cmp.to_f -> float + * to_f -> float * - * Returns the value as a float if possible (the imaginary part should - * be exactly zero). + * Returns the value of <tt>self.real</tt> as a Float, if possible: * - * Complex(1, 0).to_f #=> 1.0 - * Complex(1, 0.0).to_f # RangeError - * Complex(1, 2).to_f # RangeError + * Complex.rect(1, 0).to_f # => 1.0 + * Complex.rect(1, Rational(0, 1)).to_f # => 1.0 + * + * Raises RangeError if <tt>self.imag</tt> is not exactly zero + * (either <tt>Integer(0)</tt> or <tt>Rational(0, n)</tt>). */ static VALUE nucomp_to_f(VALUE self) @@ -1625,41 +1843,69 @@ nucomp_to_f(VALUE self) /* * call-seq: - * cmp.to_r -> rational + * to_r -> rational + * + * Returns the value of <tt>self.real</tt> as a Rational, if possible: * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). + * Complex.rect(1, 0).to_r # => (1/1) + * Complex.rect(1, Rational(0, 1)).to_r # => (1/1) + * Complex.rect(1, 0.0).to_r # => (1/1) * - * Complex(1, 0).to_r #=> (1/1) - * Complex(1, 0.0).to_r # RangeError - * Complex(1, 2).to_r # RangeError + * Raises RangeError if <tt>self.imag</tt> is not exactly zero + * (either <tt>Integer(0)</tt> or <tt>Rational(0, n)</tt>) + * and <tt>self.imag.to_r</tt> is not exactly zero. * - * See rationalize. + * Related: Complex#rationalize. */ static VALUE nucomp_to_r(VALUE self) { get_dat1(self); - if (!k_exact_zero_p(dat->imag)) { - rb_raise(rb_eRangeError, "can't convert %"PRIsVALUE" into Rational", - self); + if (RB_FLOAT_TYPE_P(dat->imag) && FLOAT_ZERO_P(dat->imag)) { + /* Do nothing here */ + } + else if (!k_exact_zero_p(dat->imag)) { + VALUE imag = rb_check_convert_type_with_id(dat->imag, T_RATIONAL, "Rational", idTo_r); + if (NIL_P(imag) || !k_exact_zero_p(imag)) { + rb_raise(rb_eRangeError, "can't convert %"PRIsVALUE" into Rational", + self); + } } return f_to_r(dat->real); } /* * call-seq: - * cmp.rationalize([eps]) -> rational - * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). - * - * Complex(1.0/3, 0).rationalize #=> (1/3) - * Complex(1, 0.0).rationalize # RangeError - * Complex(1, 2).rationalize # RangeError - * - * See to_r. + * rationalize(epsilon = nil) -> rational + * + * Returns a Rational object whose value is exactly or approximately + * equivalent to that of <tt>self.real</tt>. + * + * With no argument +epsilon+ given, returns a \Rational object + * whose value is exactly equal to that of <tt>self.real.rationalize</tt>: + * + * Complex.rect(1, 0).rationalize # => (1/1) + * Complex.rect(1, Rational(0, 1)).rationalize # => (1/1) + * Complex.rect(3.14159, 0).rationalize # => (314159/100000) + * + * With argument +epsilon+ given, returns a \Rational object + * whose value is exactly or approximately equal to that of <tt>self.real</tt> + * to the given precision: + * + * Complex.rect(3.14159, 0).rationalize(0.1) # => (16/5) + * Complex.rect(3.14159, 0).rationalize(0.01) # => (22/7) + * Complex.rect(3.14159, 0).rationalize(0.001) # => (201/64) + * Complex.rect(3.14159, 0).rationalize(0.0001) # => (333/106) + * Complex.rect(3.14159, 0).rationalize(0.00001) # => (355/113) + * Complex.rect(3.14159, 0).rationalize(0.000001) # => (7433/2366) + * Complex.rect(3.14159, 0).rationalize(0.0000001) # => (9208/2931) + * Complex.rect(3.14159, 0).rationalize(0.00000001) # => (47460/15107) + * Complex.rect(3.14159, 0).rationalize(0.000000001) # => (76149/24239) + * Complex.rect(3.14159, 0).rationalize(0.0000000001) # => (314159/100000) + * Complex.rect(3.14159, 0).rationalize(0.0) # => (3537115888337719/1125899906842624) + * + * Related: Complex#to_r. */ static VALUE nucomp_rationalize(int argc, VALUE *argv, VALUE self) @@ -1677,12 +1923,9 @@ nucomp_rationalize(int argc, VALUE *argv, VALUE self) /* * call-seq: - * complex.to_c -> self - * - * Returns self. + * to_c -> self * - * Complex(2).to_c #=> (2+0i) - * Complex(-8, 6).to_c #=> (-8+6i) + * Returns +self+. */ static VALUE nucomp_to_c(VALUE self) @@ -1692,24 +1935,9 @@ nucomp_to_c(VALUE self) /* * call-seq: - * to_c -> (0+0i) - * - * Returns zero as a Complex: - * - * nil.to_c # => (0+0i) + * to_c -> complex * - */ -static VALUE -nilclass_to_c(VALUE self) -{ - return rb_complex_new1(INT2FIX(0)); -} - -/* - * call-seq: - * num.to_c -> complex - * - * Returns the value as a complex. + * Returns +self+ as a Complex object. */ static VALUE numeric_to_c(VALUE self) @@ -1989,23 +2217,14 @@ string_to_c_strict(VALUE self, int raise) rb_must_asciicompat(self); - s = RSTRING_PTR(self); - - if (!s || memchr(s, '\0', RSTRING_LEN(self))) { - if (!raise) return Qnil; - rb_raise(rb_eArgError, "string contains null byte"); + if (raise) { + s = StringValueCStr(self); } - - if (s && s[RSTRING_LEN(self)]) { - rb_str_modify(self); - s = RSTRING_PTR(self); - s[RSTRING_LEN(self)] = '\0'; + else if (!(s = rb_str_to_cstr(self))) { + return Qnil; } - if (!s) - s = (char *)""; - - if (!parse_comp(s, 1, &num)) { + if (!parse_comp(s, TRUE, &num)) { if (!raise) return Qnil; rb_raise(rb_eArgError, "invalid value for convert(): %+"PRIsVALUE, self); @@ -2016,53 +2235,167 @@ string_to_c_strict(VALUE self, int raise) /* * call-seq: - * str.to_c -> complex - * - * Returns a complex which denotes the string form. The parser - * ignores leading whitespaces and trailing garbage. Any digit - * sequences can be separated by an underscore. Returns zero for null - * or garbage string. - * - * '9'.to_c #=> (9+0i) - * '2.5'.to_c #=> (2.5+0i) - * '2.5/1'.to_c #=> ((5/2)+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) - * - * Polar form: - * include Math - * "1.0@0".to_c #=> (1+0.0i) - * "1.0@#{PI/2}".to_c #=> (0.0+1i) - * "1.0@#{PI}".to_c #=> (-1+0.0i) - * - * See Kernel.Complex. + * to_c -> complex + * + * Returns a Complex object: + * parses the leading substring of +self+ + * to extract two numeric values that become the coordinates of the complex object. + * + * The substring is interpreted as containing + * either rectangular coordinates (real and imaginary parts) + * or polar coordinates (magnitude and angle parts), + * depending on an included or implied "separator" character: + * + * - <tt>'+'</tt>, <tt>'-'</tt>, or no separator: rectangular coordinates. + * - <tt>'@'</tt>: polar coordinates. + * + * <b>In Brief</b> + * + * In these examples, we use method Complex#rect to display rectangular coordinates, + * and method Complex#polar to display polar coordinates. + * + * # Rectangular coordinates. + * + * # Real-only: no separator; imaginary part is zero. + * '9'.to_c.rect # => [9, 0] # Integer. + * '-9'.to_c.rect # => [-9, 0] # Integer (negative). + * '2.5'.to_c.rect # => [2.5, 0] # Float. + * '1.23e-14'.to_c.rect # => [1.23e-14, 0] # Float with exponent. + * '2.5/1'.to_c.rect # => [(5/2), 0] # Rational. + * + * # Some things are ignored. + * 'foo1'.to_c.rect # => [0, 0] # Unparsed entire substring. + * '1foo'.to_c.rect # => [1, 0] # Unparsed trailing substring. + * ' 1 '.to_c.rect # => [1, 0] # Leading and trailing whitespace. + * * + * # Imaginary only: trailing 'i' required; real part is zero. + * '9i'.to_c.rect # => [0, 9] + * '-9i'.to_c.rect # => [0, -9] + * '2.5i'.to_c.rect # => [0, 2.5] + * '1.23e-14i'.to_c.rect # => [0, 1.23e-14] + * '2.5/1i'.to_c.rect # => [0, (5/2)] + * + * # Real and imaginary; '+' or '-' separator; trailing 'i' required. + * '2+3i'.to_c.rect # => [2, 3] + * '-2-3i'.to_c.rect # => [-2, -3] + * '2.5+3i'.to_c.rect # => [2.5, 3] + * '2.5+3/2i'.to_c.rect # => [2.5, (3/2)] + * + * # Polar coordinates; '@' separator; magnitude required. + * '1.0@0'.to_c.polar # => [1.0, 0.0] + * '1.0@'.to_c.polar # => [1.0, 0.0] + * "1.0@#{Math::PI}".to_c.polar # => [1.0, 3.141592653589793] + * "1.0@#{Math::PI/2}".to_c.polar # => [1.0, 1.5707963267948966] + * + * <b>Parsed Values</b> + * + * The parsing may be thought of as searching for numeric literals + * embedded in the substring. + * + * This section shows how the method parses numeric values from leading substrings. + * The examples show real-only or imaginary-only parsing; + * the parsing is the same for each part. + * + * '1foo'.to_c # => (1+0i) # Ignores trailing unparsed characters. + * ' 1 '.to_c # => (1+0i) # Ignores leading and trailing whitespace. + * 'x1'.to_c # => (0+0i) # Finds no leading numeric. + * + * # Integer literal embedded in the substring. + * '1'.to_c # => (1+0i) + * '-1'.to_c # => (-1+0i) + * '1i'.to_c # => (0+1i) + * + * # Integer literals that don't work. + * '0b100'.to_c # => (0+0i) # Not parsed as binary. + * '0o100'.to_c # => (0+0i) # Not parsed as octal. + * '0d100'.to_c # => (0+0i) # Not parsed as decimal. + * '0x100'.to_c # => (0+0i) # Not parsed as hexadecimal. + * '010'.to_c # => (10+0i) # Not parsed as octal. + * + * # Float literals: + * '3.14'.to_c # => (3.14+0i) + * '3.14i'.to_c # => (0+3.14i) + * '1.23e4'.to_c # => (12300.0+0i) + * '1.23e+4'.to_c # => (12300.0+0i) + * '1.23e-4'.to_c # => (0.000123+0i) + * + * # Rational literals: + * '1/2'.to_c # => ((1/2)+0i) + * '-1/2'.to_c # => ((-1/2)+0i) + * '1/2r'.to_c # => ((1/2)+0i) + * '-1/2r'.to_c # => ((-1/2)+0i) + * + * <b>Rectangular Coordinates</b> + * + * With separator <tt>'+'</tt> or <tt>'-'</tt>, + * or with no separator, + * interprets the values as rectangular coordinates: real and imaginary. + * + * With no separator, assigns a single value to either the real or the imaginary part: + * + * ''.to_c # => (0+0i) # Defaults to zero. + * '1'.to_c # => (1+0i) # Real (no trailing 'i'). + * '1i'.to_c # => (0+1i) # Imaginary (trailing 'i'). + * 'i'.to_c # => (0+1i) # Special case (imaginary 1). + * + * With separator <tt>'+'</tt>, both parts positive (or zero): + * + * # Without trailing 'i'. + * '+'.to_c # => (0+0i) # No values: defaults to zero. + * '+1'.to_c # => (1+0i) # Value after '+': real only. + * '1+'.to_c # => (1+0i) # Value before '+': real only. + * '2+1'.to_c # => (2+0i) # Values before and after '+': real and imaginary. + * # With trailing 'i'. + * '+1i'.to_c # => (0+1i) # Value after '+': imaginary only. + * '2+i'.to_c # => (2+1i) # Value before '+': real and imaginary 1. + * '2+1i'.to_c # => (2+1i) # Values before and after '+': real and imaginary. + * + * With separator <tt>'-'</tt>, negative imaginary part: + * + * # Without trailing 'i'. + * '-'.to_c # => (0+0i) # No values: defaults to zero. + * '-1'.to_c # => (-1+0i) # Value after '-': negative real, zero imaginary. + * '1-'.to_c # => (1+0i) # Value before '-': positive real, zero imaginary. + * '2-1'.to_c # => (2+0i) # Values before and after '-': positive real, zero imaginary. + * # With trailing 'i'. + * '-1i'.to_c # => (0-1i) # Value after '-': negative real, zero imaginary. + * '2-i'.to_c # => (2-1i) # Value before '-': positive real, negative imaginary. + * '2-1i'.to_c # => (2-1i) # Values before and after '-': positive real, negative imaginary. + * + * Note that the suffixed character <tt>'i'</tt> + * may instead be one of <tt>'I'</tt>, <tt>'j'</tt>, or <tt>'J'</tt>, + * with the same effect. + * + * <b>Polar Coordinates</b> + * + * With separator <tt>'@'</tt>) + * interprets the values as polar coordinates: magnitude and angle. + * + * '2@'.to_c.polar # => [2, 0.0] # Value before '@': magnitude only. + * # Values before and after '@': magnitude and angle. + * '2@1'.to_c.polar # => [2.0, 1.0] + * "1.0@#{Math::PI/2}".to_c # => (0.0+1i) + * "1.0@#{Math::PI}".to_c # => (-1+0.0i) + * # Magnitude not given: defaults to zero. + * '@'.to_c.polar # => [0, 0.0] + * '@1'.to_c.polar # => [0, 0.0] + * + * '1.0@0'.to_c # => (1+0.0i) + * + * Note that in all cases, the suffixed character <tt>'i'</tt> + * may instead be one of <tt>'I'</tt>, <tt>'j'</tt>, <tt>'J'</tt>, + * with the same effect. + * + * See {Converting to Non-String}[rdoc-ref:String@Converting+to+Non--5CString]. */ static VALUE string_to_c(VALUE self) { - char *s; VALUE num; rb_must_asciicompat(self); - s = RSTRING_PTR(self); - - if (s && s[RSTRING_LEN(self)]) { - rb_str_modify(self); - s = RSTRING_PTR(self); - s[RSTRING_LEN(self)] = '\0'; - } - - if (!s) - s = (char *)""; - - (void)parse_comp(s, 0, &num); + (void)parse_comp(rb_str_fill_terminator(self, 1), FALSE, &num); return num; } @@ -2119,8 +2452,11 @@ nucomp_convert(VALUE klass, VALUE a1, VALUE a2, int raise) return a1; /* should raise exception for consistency */ if (!k_numeric_p(a1)) { - if (!raise) - return rb_protect(to_complex, a1, NULL); + if (!raise) { + a1 = rb_protect(to_complex, a1, NULL); + rb_set_errinfo(Qnil); + return a1; + } return to_complex(a1); } } @@ -2164,9 +2500,9 @@ nucomp_s_convert(int argc, VALUE *argv, VALUE klass) /* * call-seq: - * num.abs2 -> real + * abs2 -> real * - * Returns square of self. + * Returns the square of +self+. */ static VALUE numeric_abs2(VALUE self) @@ -2176,11 +2512,9 @@ numeric_abs2(VALUE self) /* * call-seq: - * num.arg -> 0 or float - * num.angle -> 0 or float - * num.phase -> 0 or float + * arg -> 0 or Math::PI * - * Returns 0 if the value is positive, pi otherwise. + * Returns zero if +self+ is positive, Math::PI otherwise. */ static VALUE numeric_arg(VALUE self) @@ -2192,10 +2526,9 @@ numeric_arg(VALUE self) /* * call-seq: - * num.rect -> array - * num.rectangular -> array + * rect -> array * - * Returns an array; [num, 0]. + * Returns array <tt>[self, 0]</tt>. */ static VALUE numeric_rect(VALUE self) @@ -2205,9 +2538,9 @@ numeric_rect(VALUE self) /* * call-seq: - * num.polar -> array + * polar -> array * - * Returns an array; [num.abs, num.arg]. + * Returns array <tt>[self.abs, self.arg]</tt>. */ static VALUE numeric_polar(VALUE self) @@ -2235,11 +2568,9 @@ numeric_polar(VALUE self) /* * call-seq: - * flo.arg -> 0 or float - * flo.angle -> 0 or float - * flo.phase -> 0 or float + * arg -> 0 or Math::PI * - * Returns 0 if the value is positive, pi otherwise. + * Returns 0 if +self+ is positive, Math::PI otherwise. */ static VALUE float_arg(VALUE self) @@ -2252,45 +2583,137 @@ float_arg(VALUE self) } /* - * 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. + * A \Complex object houses a pair of values, + * given when the object is created as either <i>rectangular coordinates</i> + * or <i>polar coordinates</i>. + * + * == Rectangular Coordinates + * + * The rectangular coordinates of a complex number + * are called the _real_ and _imaginary_ parts; + * see {Complex number definition}[https://en.wikipedia.org/wiki/Complex_number#Definition_and_basic_operations]. * - * You can create a \Complex object explicitly with: + * You can create a \Complex object from rectangular coordinates with: * * - A {complex literal}[rdoc-ref:syntax/literals.rdoc@Complex+Literals]. + * - Method Complex.rect. + * - Method Kernel#Complex, either with numeric arguments or with certain string arguments. + * - Method String#to_c, for certain strings. + * + * Note that each of the stored parts may be a an instance one of the classes + * Complex, Float, Integer, or Rational; + * they may be retrieved: + * + * - Separately, with methods Complex#real and Complex#imaginary. + * - Together, with method Complex#rect. + * + * The corresponding (computed) polar values may be retrieved: + * + * - Separately, with methods Complex#abs and Complex#arg. + * - Together, with method Complex#polar. + * + * == Polar Coordinates + * + * The polar coordinates of a complex number + * are called the _absolute_ and _argument_ parts; + * see {Complex polar plane}[https://en.wikipedia.org/wiki/Complex_number#Polar_form]. + * + * In this class, the argument part + * in expressed {radians}[https://en.wikipedia.org/wiki/Radian] + * (not {degrees}[https://en.wikipedia.org/wiki/Degree_(angle)]). + * + * You can create a \Complex object from polar coordinates with: + * + * - Method Complex.polar. + * - Method Kernel#Complex, with certain string arguments. + * - Method String#to_c, for certain strings. + * + * Note that each of the stored parts may be a an instance one of the classes + * Complex, Float, Integer, or Rational; + * they may be retrieved: + * + * - Separately, with methods Complex#abs and Complex#arg. + * - Together, with method Complex#polar. + * + * The corresponding (computed) rectangular values may be retrieved: + * + * - Separately, with methods Complex#real and Complex#imag. + * - Together, with method Complex#rect. + * + * == What's Here + * + * First, what's elsewhere: + * + * - Class \Complex inherits (directly or indirectly) + * from classes {Numeric}[rdoc-ref:Numeric@What-27s+Here] + * and {Object}[rdoc-ref:Object@What-27s+Here]. + * - Includes (indirectly) module {Comparable}[rdoc-ref:Comparable@What-27s+Here]. + * + * Here, class \Complex has methods for: + * + * === Creating \Complex Objects + * + * - ::polar: Returns a new \Complex object based on given polar coordinates. + * - ::rect (and its alias ::rectangular): + * Returns a new \Complex object based on given rectangular coordinates. + * + * === Querying + * + * - #abs (and its alias #magnitude): Returns the absolute value for +self+. + * - #arg (and its aliases #angle and #phase): + * Returns the argument (angle) for +self+ in radians. + * - #denominator: Returns the denominator of +self+. + * - #finite?: Returns whether both +self.real+ and +self.image+ are finite. + * - #hash: Returns the integer hash value for +self+. + * - #imag (and its alias #imaginary): Returns the imaginary value for +self+. + * - #infinite?: Returns whether +self.real+ or +self.image+ is infinite. + * - #numerator: Returns the numerator of +self+. + * - #polar: Returns the array <tt>[self.abs, self.arg]</tt>. + * - #inspect: Returns a string representation of +self+. + * - #real: Returns the real value for +self+. + * - #real?: Returns +false+; for compatibility with Numeric#real?. + * - #rect (and its alias #rectangular): + * Returns the array <tt>[self.real, self.imag]</tt>. + * + * === Comparing + * + * - #<=>: Returns whether +self+ is less than, equal to, or greater than the given argument. + * - #==: Returns whether +self+ is equal to the given argument. * - * You can convert certain objects to \Complex objects with: + * === Converting * - * - \Method #Complex. + * - #rationalize: Returns a Rational object whose value is exactly + * or approximately equivalent to that of <tt>self.real</tt>. + * - #to_c: Returns +self+. + * - #to_d: Returns the value as a BigDecimal object. + * - #to_f: Returns the value of <tt>self.real</tt> as a Float, if possible. + * - #to_i: Returns the value of <tt>self.real</tt> as an Integer, if possible. + * - #to_r: Returns the value of <tt>self.real</tt> as a Rational, if possible. + * - #to_s: Returns a string representation of +self+. * - * Complex object can be created as literal, and also by using - * Kernel#Complex, Complex::rect, Complex::polar or to_c method. + * === Performing Complex Arithmetic * - * 2+1i #=> (2+1i) - * Complex(1) #=> (1+0i) - * Complex(2, 3) #=> (2+3i) - * Complex.polar(2, 3) #=> (-1.9799849932008908+0.2822400161197344i) - * 3.to_c #=> (3+0i) + * - #*: Returns the product of +self+ and the given numeric. + * - #**: Returns +self+ raised to power of the given numeric. + * - #+: Returns the sum of +self+ and the given numeric. + * - #-: Returns the difference of +self+ and the given numeric. + * - #-@: Returns the negation of +self+. + * - #/: Returns the quotient of +self+ and the given numeric. + * - #abs2: Returns square of the absolute value (magnitude) for +self+. + * - #conj (and its alias #conjugate): Returns the conjugate of +self+. + * - #fdiv: Returns <tt>Complex.rect(self.real/numeric, self.imag/numeric)</tt>. * - * You can also create complex object from floating-point numbers or - * strings. + * === Working with JSON * - * 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) + * - ::json_create: Returns a new \Complex object, + * deserialized from the given serialized hash. + * - #as_json: Returns a serialized hash constructed from +self+. + * - #to_json: Returns a JSON string representing +self+. * - * 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) + * These methods are provided by the {JSON gem}[https://github.com/ruby/json]. To make these methods available: * - * A complex object is either an exact or an inexact number. + * require 'json/add/complex' * - * Complex(1, 1) / 2 #=> ((1/2)+(1/2)*i) - * Complex(1, 1) / 2.0 #=> (0.5+0.5i) */ void Init_Complex(void) @@ -2391,7 +2814,6 @@ Init_Complex(void) rb_define_method(rb_cComplex, "to_r", nucomp_to_r, 0); rb_define_method(rb_cComplex, "rationalize", nucomp_rationalize, -1); rb_define_method(rb_cComplex, "to_c", nucomp_to_c, 0); - rb_define_method(rb_cNilClass, "to_c", nilclass_to_c, 0); rb_define_method(rb_cNumeric, "to_c", numeric_to_c, 0); rb_define_method(rb_cString, "to_c", string_to_c, 0); @@ -2411,13 +2833,17 @@ Init_Complex(void) rb_define_method(rb_cFloat, "phase", float_arg, 0); /* - * The imaginary unit. + * Equivalent + * to <tt>Complex.rect(0, 1)</tt>: + * + * Complex::I # => (0+1i) + * */ rb_define_const(rb_cComplex, "I", f_complex_new_bang2(rb_cComplex, ZERO, ONE)); #if !USE_FLONUM - rb_gc_register_mark_object(RFLOAT_0 = DBL2NUM(0.0)); + rb_vm_register_global_object(RFLOAT_0 = DBL2NUM(0.0)); #endif rb_provide("complex.so"); /* for backward compatibility */ |