# Complex

Class

A Complex object houses a pair of values, given when the object is created as either rectangular coordinates or polar coordinates.

## Rectangular Coordinates

The rectangular coordinates of a complex number are called the real and imaginary parts; see Complex number definition.

You can create a Complex object from rectangular coordinates with:

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:

The corresponding (computed) polar values may be retrieved:

## Polar Coordinates

The polar coordinates of a complex number are called the absolute and argument parts; see Complex polar plane.

In this class, the argument part in expressed radians (not degrees).

You can create a Complex object from polar coordinates with:

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:

The corresponding (computed) rectangular values may be retrieved:

Constants

#### I

Equivalent to `Complex(0, 1)`:

```Complex::I # => (0+1i)
```
Class Methods

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:

```Complex.polar(3)        # => (3+0i)
Complex.polar(3, 2.0)   # => (-1.2484405096414273+2.727892280477045i)
Complex.polar(-3, -2.0) # => (1.2484405096414273+2.727892280477045i)
```

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:

```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.

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:

```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.

Instance Methods

Returns the product of `self` and `numeric`:

```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)
```

Returns `self` raised to power `numeric`:

```Complex('i') ** 2             # => (-1+0i)
Complex(-8) ** Rational(1, 3) # => (1.0000000000000002+1.7320508075688772i)
```

Returns the sum of `self` and `numeric`:

```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)
```

Returns the difference of `self` and `numeric`:

```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)
```

Returns the negation of `self`, which is the negation of each of its parts:

```-Complex(1, 2)   # => (-1-2i)
-Complex(-1, -2) # => (1+2i)
```

Returns the quotient of `self` and `numeric`:

```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)
```

Returns:

• `self.real <=> object.real` if both of the following are true:

• `self.imag == 0`.

• `object.imag == 0`. # Always true if object is numeric but not complex.

• `nil` otherwise.

Examples:

```Complex(2) <=> 3             # => -1
Complex(2) <=> 2             # => 0
Complex(2) <=> 1             # => 1
Complex(2, 1) <=> 1          # => nil # self.imag not zero.
Complex(1) <=> Complex(1, 1) # => nil # object.imag not zero.
Complex(1) <=> 'Foo'         # => nil # object.imag not defined.
```

Returns `true` if `self.real == object.real` and `self.imag == object.imag`:

```Complex(2, 3)  == Complex(2.0, 3.0)      # => true
```

Returns the absolute value (magnitude) for `self`; see polar coordinates:

```Complex.polar(-1, 0).abs # => 1.0
```

If `self` was created with rectangular coordinates, the returned value is computed, and may be inexact:

```Complex.rectangular(1, 1).abs # => 1.4142135623730951 # The square root of 2.
```

Returns square of the absolute value (magnitude) for `self`; see polar coordinates:

```Complex.polar(2, 2).abs2 # => 4.0
```

If `self` was created with rectangular coordinates, the returned value is computed, and may be inexact:

```Complex.rectangular(1.0/3, 1.0/3).abs2 # => 0.2222222222222222
```
An alias for arg

Returns the argument (angle) for `self` in radians; see polar coordinates:

```Complex.polar(3, Math::PI/2).arg  # => 1.57079632679489660
```

If `self` was created with rectangular coordinates, the returned value is computed, and may be inexact:

```Complex.polar(1, 1.0/3).arg # => 0.33333333333333326
```

Methods `Complex#as_json` and `Complex.json_create` may be used to serialize and deserialize a Complex object; see `Marshal`.

Method `Complex#as_json` serializes `self`, returning a 2-element hash representing `self`:

```require 'json/add/complex'
x = Complex(2).as_json      # => {"json_class"=>"Complex", "r"=>2, "i"=>0}
y = Complex(2.0, 4).as_json # => {"json_class"=>"Complex", "r"=>2.0, "i"=>4}
```

Method `JSON.create` deserializes such a hash, returning a Complex object:

```Complex.json_create(x) # => (2+0i)
Complex.json_create(y) # => (2.0+4i)
```
An alias for conjugate

Returns the conjugate of `self`, `Complex.rect(self.imag, self.real)`:

```Complex.rect(1, 2).conj # => (1-2i)
```

Returns the denominator of `self`, which is the least common multiple of `self.real.denominator` and `self.imag.denominator`:

```Complex.rect(Rational(1, 2), Rational(2, 3)).denominator # => 6
```

Note that `n.denominator` of a non-rational numeric is `1`.

Related: `Complex#numerator`.

Returns `Complex(self.real/numeric, self.imag/numeric)`:

```Complex(11, 22).fdiv(3) # => (3.6666666666666665+7.333333333333333i)
```

Returns `true` if both `self.real.finite?` and `self.imag.finite?` are true, `false` otherwise:

```Complex(1, 1).finite?               # => true
Complex(Float::INFINITY, 0).finite? # => false
```

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(1, 2).hash == Complex(1, 2).hash # => true
```
An alias for imaginary

Returns the imaginary value for `self`:

```Complex(7).imaginary      #=> 0
Complex(9, -4).imaginary  #=> -4
```

If `self` was created with polar coordinates, the returned value is computed, and may be inexact:

```Complex.polar(1, Math::PI/4).imag # => 0.7071067811865476 # Square root of 2.
```

Returns `1` if either `self.real.infinite?` or `self.imag.infinite?` is true, `nil` otherwise:

```Complex(Float::INFINITY, 0).infinite? # => 1
Complex(1, 1).infinite?               # => nil
```

Returns a string representation of `self`:

```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)"
```
An alias for abs

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 of the two:

```c = Complex(Rational(2, 3), Rational(3, 4)) # => ((2/3)+(3/4)*i)
c.numerator                                 # => (8+9i)
```

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 `c.numerator` is `Complex(8, 9)`.

Related: `Complex#denominator`.

An alias for arg

Returns the array `[self.abs, self.arg]`:

```Complex.polar(1, 2).polar # => [1.0, 2.0]
```

If `self` was created with rectangular coordinates, the returned value is computed, and may be inexact:

```Complex.rect(1, 1).polar # => [1.4142135623730951, 0.7853981633974483]
```

Returns the quotient of `self` and `numeric`:

```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)
```

Returns a `Rational` object whose value is exactly or approximately equivalent to that of `self.real`.

With no argument `epsilon` given, returns a Rational object whose value is exactly equal to that of `self.real.rationalize`:

```Complex(1, 0).rationalize              # => (1/1)
Complex(1, Rational(0, 1)).rationalize # => (1/1)
Complex(3.14159, 0).rationalize        # => (314159/100000)
```

With argument `epsilon` given, returns a Rational object whose value is exactly or approximately equal to that of `self.real` to the given precision:

```Complex(3.14159, 0).rationalize(0.1)          # => (16/5)
Complex(3.14159, 0).rationalize(0.01)         # => (22/7)
Complex(3.14159, 0).rationalize(0.001)        # => (201/64)
Complex(3.14159, 0).rationalize(0.0001)       # => (333/106)
Complex(3.14159, 0).rationalize(0.00001)      # => (355/113)
Complex(3.14159, 0).rationalize(0.000001)     # => (7433/2366)
Complex(3.14159, 0).rationalize(0.0000001)    # => (9208/2931)
Complex(3.14159, 0).rationalize(0.00000001)   # => (47460/15107)
Complex(3.14159, 0).rationalize(0.000000001)  # => (76149/24239)
Complex(3.14159, 0).rationalize(0.0000000001) # => (314159/100000)
Complex(3.14159, 0).rationalize(0.0)          # => (3537115888337719/1125899906842624)
```

Related: `Complex#to_r`.

Returns the real value for `self`:

```Complex(7).real      #=> 7
Complex(9, -4).real  #=> 9
```

If `self` was created with polar coordinates, the returned value is computed, and may be inexact:

```Complex.polar(1, Math::PI/4).real # => 0.7071067811865476 # Square root of 2.
```

Returns `false`; for compatibility with `Numeric#real?`.

An alias for rectangular

Returns the array `[self.real, self.imag]`:

```Complex.rect(1, 2).rect # => [1, 2]
```

If `self` was created with polar coordinates, the returned value is computed, and may be inexact:

```Complex.polar(1.0, 1.0).rect # => [0.5403023058681398, 0.8414709848078965]
```

`Complex#rectangular` is an alias for `Complex#rect`.

Returns `self`.

Returns the value as a `BigDecimal`.

The `precision` parameter is required for a rational complex number. This parameter is used to determine the number of significant digits for the result.

```require 'bigdecimal'
require 'bigdecimal/util'

Complex(0.1234567, 0).to_d(4)   # => 0.1235e0
Complex(Rational(22, 7), 0).to_d(3)   # => 0.314e1
```

See also `Kernel.BigDecimal`.

Returns the value of `self.real` as a `Float`, if possible:

```Complex(1, 0).to_f              # => 1.0
Complex(1, Rational(0, 1)).to_f # => 1.0
```

Raises `RangeError` if `self.imag` is not exactly zero (either `Integer(0)` or `Rational(0, n)`).

Returns the value of `self.real` as an `Integer`, if possible:

```Complex(1, 0).to_i              # => 1
Complex(1, Rational(0, 1)).to_i # => 1
```

Raises `RangeError` if `self.imag` is not exactly zero (either `Integer(0)` or `Rational(0, n)`).

Returns a `JSON` string representing `self`:

```require 'json/add/complex'
puts Complex(2).to_json
puts Complex(2.0, 4).to_json
```

Output:

```{"json_class":"Complex","r":2,"i":0}
{"json_class":"Complex","r":2.0,"i":4}
```

Returns the value of `self.real` as a `Rational`, if possible:

```Complex(1, 0).to_r              # => (1/1)
Complex(1, Rational(0, 1)).to_r # => (1/1)
```

Raises `RangeError` if `self.imag` is not exactly zero (either `Integer(0)` or `Rational(0, n)`).

Related: `Complex#rationalize`.

Returns a string representation of `self`:

```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"
```