# Class Apcomplex

java.lang.Object
java.lang.Number
org.apfloat.Apcomplex

All Implemented Interfaces:
  `Serializable, Formattable`

Direct Known Subclasses:
  `Apfloat`

public class Apcomplex extends Number implements Formattable, Serializable
Arbitrary precision complex number class. An apcomplex consists of a real and imaginary part of type `Apfloat`.

Note that although the Apcomplex class extends `Number`, the methods inherited from `Number` return the value of the real part of the complex number. Thus they are more meaningful for the `Apfloat` class and its subclasses.

Version:
  1.15.0
Author:
  Mikko Tommila
See Also:
  - `Apfloat`
  - `ApcomplexMath`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `DEFAULT`
  Default precision.
  `static final Apcomplex`
  `I`
  Imaginary unit.
  `static final long`
  `INFINITE`
  Infinite precision or scale.
  `static final Apint`
  `ONE`
  Constant for one.
  `static final Comparator<Apcomplex>`
  `REAL_ABS_IMAG_ORDER`
  Comparator for ordering by real part, and in case of a tie, by the absolute value of the imaginary part.
  `static final Comparator<Apcomplex>`
  `REAL_IMAG_ORDER`
  Comparator for ordering by real part, and in case of a tie, by imaginary part.
  `static final Apint`
  `ZERO`
  Constant for zero.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Apcomplex()`
  Default constructor.
  ``
  `Apcomplex(PushbackReader in)`
  Reads an apcomplex from a reader.
  ``
  `Apcomplex(String value)`
  Constructs an apcomplex from a string.
  ``
  `Apcomplex(Apfloat real)`
  Construct a real apcomplex whose imaginary part is zero.
  ``
  `Apcomplex(Apfloat real, Apfloat imag)`
  Construct an apcomplex with the specified real and imaginary part.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Apcomplex`
  `add(Apcomplex z)`
  Adds two apcomplex numbers.
  `byte`
  `byteValue()`
  Returns the value of the this number as a `byte`.
  `byte`
  `byteValueExact()`
  Returns the value of the this number as a `byte`, checking for lost information.
  `Apcomplex`
  `conj()`
  Returns the complex conjugate of this apcomplex.
  `Apcomplex`
  `divide(Apcomplex z)`
  Divides two apcomplex numbers.
  `double`
  `doubleValue()`
  Returns the value of the this number as a `double`.
  `long`
  `equalDigits(Apcomplex z)`
  Computes number of equal digits.
  `boolean`
  `equals(Object obj)`
  Compares this object to the specified object.
  `float`
  `floatValue()`
  Returns the value of the this number as a `float`.
  `void`
  `formatTo(Formatter formatter, int flags, int width, int precision)`
  Formats the object using the provided formatter.
  `int`
  `hashCode()`
  Returns a hash code for this apcomplex.
  `Apfloat`
  `imag()`
  Returns the imaginary part of this apcomplex.
  `int`
  `intValue()`
  Returns the value of the this number as an `int`.
  `int`
  `intValueExact()`
  Returns the value of the this number as an `int`, checking for lost information.
  `boolean`
  `isInteger()`
  Returns if this number has an integer value.
  `boolean`
  `isZero()`
  Returns if this number is zero.
  `long`
  `longValue()`
  Returns the value of the this number as a `long`.
  `long`
  `longValueExact()`
  Returns the value of the this number as a `long`, checking for lost information.
  `Apcomplex`
  `multiply(Apcomplex z)`
  Multiplies two apcomplex numbers.
  `Apcomplex`
  `negate()`
  Negative value.
  `long`
  `precision()`
  Returns the precision of this apcomplex.
  `Apcomplex`
  `precision(long precision)`
  Returns an apcomplex with the same value as this apcomplex accurate to the specified precision.
  `int`
  `radix()`
  Radix of this apcomplex.
  `Apfloat`
  `real()`
  Returns the real part of this apcomplex.
  `long`
  `scale()`
  Returns the scale of this apcomplex.
  `short`
  `shortValue()`
  Returns the value of the this number as a `short`.
  `short`
  `shortValueExact()`
  Returns the value of the this number as a `short`, checking for lost information.
  `long`
  `size()`
  Returns the size of this apcomplex.
  `Apcomplex`
  `subtract(Apcomplex z)`
  Subtracts two apcomplex numbers.
  `boolean`
  `test(Apcomplex z)`
  Tests two apcomplex numbers for equality.
  `Apcomplex`
  `toRadix(int radix)`
  Convert this apcomplex to the specified radix.
  `String`
  `toString()`
  Returns a string representation of this apcomplex.
  `String`
  `toString(boolean pretty)`
  Returns a string representation of this apcomplex.
  `void`
  `writeTo(Writer out)`
  Write a string representation of this apcomplex to a `Writer`.
  `void`
  `writeTo(Writer out, boolean pretty)`
  Write a string representation of this apcomplex to a `Writer`.

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### ZERO

    public static final Apint ZERO
    Constant for zero. It is safe to use `ZERO` in all addition, subtraction, multiplication, division and comparison operations regardless of the radix used.

  - ### ONE

    public static final Apint ONE
    Constant for one. Note that this number is created using the initial default radix. It is safe to use `ONE` in all multiplication, division and equality comparison operations regardless of the radix used. However, in subtraction and addition it only works with numbers in the same radix.

  - ### I

    public static final Apcomplex I
    Imaginary unit. That is, `Apcomplex(ZERO, ONE)`. It is safe to use `I` in all multiplication, division and equality comparison operations regardless of the radix used. In addition and subtraction it only works with numbers in the same radix.

  - ### INFINITE

    public static final long INFINITE
    Infinite precision or scale. Can be used as the precision argument when constructing apfloats.
    See Also:
      - Constant Field Values

  - ### DEFAULT

    public static final long DEFAULT
    Default precision. Can be used as an argument when constructing apfloats.
    See Also:
      - Constant Field Values

  - ### REAL_IMAG_ORDER

    public static final Comparator<Apcomplex> REAL_IMAG_ORDER
    Comparator for ordering by real part, and in case of a tie, by imaginary part.

  - ### REAL_ABS_IMAG_ORDER

    public static final Comparator<Apcomplex> REAL_ABS_IMAG_ORDER
    Comparator for ordering by real part, and in case of a tie, by the absolute value of the imaginary part. If a tie persists, order by imaginary part.

- ## Constructor Details

  - ### Apcomplex

    protected Apcomplex()
    Default constructor. To be used only by subclasses that overload all needed methods.

  - ### Apcomplex

    public Apcomplex(Apfloat real)
    Construct a real apcomplex whose imaginary part is zero.
    Parameters:
      `real` - The real part of the number.

  - ### Apcomplex

    public Apcomplex(Apfloat real, Apfloat imag) throws IllegalArgumentException
    Construct an apcomplex with the specified real and imaginary part.
    Parameters:
      `real` - The real part of the number.
      `imag` - The imaginary part of the number.
    Throws:
      `IllegalArgumentException` - If the real part and imaginary part are not zero but have different radixes.

  - ### Apcomplex

    public Apcomplex(String value) throws NumberFormatException, ApfloatRuntimeException
    Constructs an apcomplex from a string.

    The input must be of one of the formats

    `realPart`
    `"(" [whitespace] realPart [whitespace] ")"`
    `"(" [whitespace] realPart [whitespace] "," [whitespace] imaginaryPart [whitespace] ")"`

    Parameters:
      `value` - The input string.
    Throws:
      `NumberFormatException` - If the number is invalid.
      `ApfloatRuntimeException`

  - ### Apcomplex

    public Apcomplex(PushbackReader in) throws IOException, NumberFormatException, ApfloatRuntimeException
    Reads an apcomplex from a reader. The constructor stops reading at the first character it doesn't understand. The reader must thus be a `PushbackReader` so that the invalid character can be returned back to the stream.

    The input must be of one of the formats

    `realPart`
    `"(" [whitespace] realPart [whitespace] ")"`
    `"(" [whitespace] realPart [whitespace] "," [whitespace] imaginaryPart [whitespace] ")"`

    Parameters:
      `in` - The input stream.
    Throws:
      `IOException` - In case of I/O error reading from the stream.
      `NumberFormatException` - If the number is invalid.
      `ApfloatRuntimeException`

- ## Method Details

  - ### radix

    public int radix()
    Radix of this apcomplex.
    Returns:
      Radix of this apcomplex.

  - ### real

    public Apfloat real()
    Returns the real part of this apcomplex.
    Returns:
      The real part of this apcomplex.

  - ### imag

    public Apfloat imag()
    Returns the imaginary part of this apcomplex.
    Returns:
      The imaginary part of this apcomplex.

  - ### conj

    public Apcomplex conj() throws ApfloatRuntimeException
    Returns the complex conjugate of this apcomplex.
    Returns:
      `x - i y`, where this apcomplex is `x + i y`.
    Throws:
      `ApfloatRuntimeException`

  - ### precision

    public long precision() throws ApfloatRuntimeException
    Returns the precision of this apcomplex.
    Returns:
      The precision of this apcomplex in number of digits of the radix in which it's presented.
    Throws:
      `ApfloatRuntimeException`

  - ### precision

    public Apcomplex precision(long precision) throws IllegalArgumentException, ApfloatRuntimeException
    Returns an apcomplex with the same value as this apcomplex accurate to the specified precision.

    If the requested precision less than this number's current precision, the functionality is quite obvious: the precision is simply truncated, and e.g. comparison and equality checking will work as expected. Some rounding errors in e.g. addition and subtraction may still occur, as "invisible" trailing digits can remain in the number.

    If the requested precision more than this number's current precision, the functionality is quite undefined: the digits up to this number's current precision are guaranteed to be the same, but the "new" digits are undefined: they may be zero, or they may be digits that have been previously discarded with a call to precision() with a smaller number of digits, or they may be something else, or any combination of these.

    These limitations allow various performance optimizations to be made.

    Parameters:
      `precision` - Precision of the new apcomplex.
    Returns:
      An apcomplex with the specified precision and same value as this apcomplex.
    Throws:
      `IllegalArgumentException` - If `precision` is <= 0.
      `ApfloatRuntimeException`
    Since:
      1.2

  - ### scale

    public long scale() throws ApfloatRuntimeException
    Returns the scale of this apcomplex. The scale is the maximum of the scale of the real part and imaginary part.

    Zero has a scale of `-INFINITE`.

    Returns:
      The exponent of this apcomplex in number of digits of the radix in which it's presented.
    Throws:
      `ApfloatRuntimeException`
    See Also:
      - `Apfloat.scale()`

  - ### size

    public long size() throws ApfloatRuntimeException
    Returns the size of this apcomplex. The size is the maximum of the size of the real part and imaginary part.

    Zero has a size of `0`.

    Returns:
      The number of digits in this number, from the most significant digit to the least significant nonzero digit, in the radix in which it's presented.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.6
    See Also:
      - `Apfloat.size()`

  - ### isZero

    public boolean isZero() throws ApfloatRuntimeException
    Returns if this number is zero.
    Returns:
      If this number is zero.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.13.0

  - ### isInteger

    public boolean isInteger() throws ApfloatRuntimeException
    Returns if this number has an integer value. Note that this does not necessarily mean that this object is an instance of `Apint`. Neither does it mean that the precision is infinite.

    A complex number needs to have a zero imaginary part to be an integer.

    Returns:
      If this number's value is an integer.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.9.0

  - ### negate

    public Apcomplex negate() throws ApfloatRuntimeException
    Negative value.
    Returns:
      `-this`.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.1

  - ### add

    public Apcomplex add(Apcomplex z) throws ApfloatRuntimeException
    Adds two apcomplex numbers.
    Parameters:
      `z` - The number to be added to this number.
    Returns:
      `this + z`.
    Throws:
      `ApfloatRuntimeException`

  - ### subtract

    public Apcomplex subtract(Apcomplex z) throws ApfloatRuntimeException
    Subtracts two apcomplex numbers.
    Parameters:
      `z` - The number to be subtracted from this number.
    Returns:
      `this - z`.
    Throws:
      `ApfloatRuntimeException`

  - ### multiply

    public Apcomplex multiply(Apcomplex z) throws ApfloatRuntimeException
    Multiplies two apcomplex numbers.
    Parameters:
      `z` - The number to be multiplied by this number.
    Returns:
      `this * z`.
    Throws:
      `ApfloatRuntimeException`

  - ### divide

    public Apcomplex divide(Apcomplex z) throws ArithmeticException, ApfloatRuntimeException
    Divides two apcomplex numbers.
    Parameters:
      `z` - The number by which this number is to be divided.
    Returns:
      `this / z`.
    Throws:
      `ArithmeticException` - In case the divisor is zero.
      `ApfloatRuntimeException`

  - ### doubleValue

    public double doubleValue()
    Returns the value of the this number as a `double`. Only takes the real part of this number. The result should be correct only within ± one ulp.
    Specified by:
      `doubleValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `double`.
    See Also:
      - `Apfloat.doubleValue()`

  - ### floatValue

    public float floatValue()
    Returns the value of the this number as a `float`. Only takes the real part of this number. The result should be correct only within ± one ulp.
    Specified by:
      `floatValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `float`.
    See Also:
      - `Apfloat.floatValue()`

  - ### byteValue

    public byte byteValue()
    Returns the value of the this number as a `byte`. Only takes the real part of this number.
    Overrides:
      `byteValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `byte`.
    See Also:
      - `Apfloat.byteValue()`

  - ### shortValue

    public short shortValue()
    Returns the value of the this number as a `short`. Only takes the real part of this number.
    Overrides:
      `shortValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `short`.
    See Also:
      - `Apfloat.shortValue()`

  - ### intValue

    public int intValue()
    Returns the value of the this number as an `int`. Only takes the real part of this number.
    Specified by:
      `intValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `int`.
    See Also:
      - `Apfloat.intValue()`

  - ### longValue

    public long longValue()
    Returns the value of the this number as a `long`. Only takes the real part of this number.
    Specified by:
      `longValue` in class `Number`
    Returns:
      The numeric value represented by this object after conversion to type `long`.
    See Also:
      - `Apfloat.longValue()`

  - ### byteValueExact

    public byte byteValueExact() throws ArithmeticException
    Returns the value of the this number as a `byte`, checking for lost information. If the value of this number is out of the range of the `byte` type, then an `ArithmeticException` is thrown.
    Returns:
      The numeric value represented by this object after conversion to type `byte`.
    Throws:
      `ArithmeticException` - If the value of `this` will not exactly fit in a `byte` or has a nonzero fractional part.
    Since:
      1.9.0

  - ### shortValueExact

    public short shortValueExact() throws ArithmeticException
    Returns the value of the this number as a `short`, checking for lost information. If the value of this number is out of the range of the `short` type, then an `ArithmeticException` is thrown.
    Returns:
      The numeric value represented by this object after conversion to type `short` or has a nonzero fractional part.
    Throws:
      `ArithmeticException` - If the value of `this` will not exactly fit in a `short`.
    Since:
      1.9.0

  - ### intValueExact

    public int intValueExact() throws ArithmeticException
    Returns the value of the this number as an `int`, checking for lost information. If the value of this number is out of the range of the `int` type, then an `ArithmeticException` is thrown.
    Returns:
      The numeric value represented by this object after conversion to type `int`.
    Throws:
      `ArithmeticException` - If the value of `this` will not exactly fit in an `int` or has a nonzero fractional part.
    Since:
      1.9.0

  - ### longValueExact

    public long longValueExact() throws ArithmeticException
    Returns the value of the this number as a `long`, checking for lost information. If the value of this number is out of the range of the `long` type, then an `ArithmeticException` is thrown.
    Returns:
      The numeric value represented by this object after conversion to type `long`.
    Throws:
      `ArithmeticException` - If the value of `this` will not exactly fit in a `long` or has a nonzero fractional part.
    Since:
      1.9.0

  - ### equalDigits

    public long equalDigits(Apcomplex z) throws ApfloatRuntimeException
    Computes number of equal digits.

    Compares the digits of the numbers starting from the most significant digits. The exponent and sign are taken into consideration, so if either one doesn't match, the numbers are considered to have zero equal digits.

    For example, the numbers (12345, 123) and (123456, 12) have zero matching digits, and the numbers (12345, 12) and (12355, 13) have three matching digits.

    Parameters:
      `z` - Number to compare with.
    Returns:
      Number of matching digits in the radix in which the numbers are presented.
    Throws:
      `ApfloatRuntimeException`

  - ### toRadix

    public Apcomplex toRadix(int radix) throws NumberFormatException, ApfloatRuntimeException
    Convert this apcomplex to the specified radix.
    Parameters:
      `radix` - The radix.
    Returns:
      This number in the specified radix.
    Throws:
      `NumberFormatException` - If the radix is invalid.
      `ApfloatRuntimeException`
    Since:
      1.2

  - ### equals

    public boolean equals(Object obj)
    Compares this object to the specified object.

    Note: two apfloats are considered equal if they have an identical mantissa, but different precision.

    Overrides:
      `equals` in class `Object`
    Parameters:
      `obj` - The object to compare with.
    Returns:
      `true` if the objects are equal; `false` otherwise.

  - ### test

    public boolean test(Apcomplex z) throws ApfloatRuntimeException
    Tests two apcomplex numbers for equality. Returns `false` if the numbers are definitely known to be not equal. If `true` is returned, equality is unknown and should be verified by calling `equals(Object)`. This method is usually significantly faster than calling `equals(Object)`.
    Parameters:
      `z` - The number to test against.
    Returns:
      `false` if the numbers are definitely not equal, `true` if unknown.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.10.0

  - ### hashCode

    public int hashCode()
    Returns a hash code for this apcomplex.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      The hash code value for this object.

  - ### toString

    public String toString()
    Returns a string representation of this apcomplex.
    Overrides:
      `toString` in class `Object`
    Returns:
      A string representing this object.

  - ### toString

    public String toString(boolean pretty) throws ApfloatRuntimeException
    Returns a string representation of this apcomplex.
    Parameters:
      `pretty` - `true` to use a fixed-point notation, `false` to use an exponential notation.
    Returns:
      A string representing this object.
    Throws:
      `ApfloatRuntimeException`

  - ### writeTo

    public void writeTo(Writer out) throws IOException, ApfloatRuntimeException
    Write a string representation of this apcomplex to a `Writer`.
    Parameters:
      `out` - The output `Writer`.
    Throws:
      `IOException` - In case of I/O error writing to the stream.
      `ApfloatRuntimeException`

  - ### writeTo

    public void writeTo(Writer out, boolean pretty) throws IOException, ApfloatRuntimeException
    Write a string representation of this apcomplex to a `Writer`.
    Parameters:
      `out` - The output `Writer`.
      `pretty` - `true` to use a fixed-point notation, `false` to use an exponential notation.
    Throws:
      `IOException` - In case of I/O error writing to the stream.
      `ApfloatRuntimeException`

  - ### formatTo

    public void formatTo(Formatter formatter, int flags, int width, int precision)
    Formats the object using the provided formatter.
    Specified by:
      `formatTo` in interface `Formattable`
    Parameters:
      `formatter` - The formatter.
      `flags` - The flags to modify the output format.
      `width` - The minimum number of characters to be written to the output, or `-1` for no minimum.
      `precision` - The maximum number of characters to be written to the output, or `-1` for no maximum.
    Since:
      1.3
    See Also:
      - `Apfloat.formatTo(Formatter,int,int,int)`