Package org.apfloat

Class Apcomplex

  • All Implemented Interfaces:
    java.io.Serializable, java.util.Formattable
    Direct Known Subclasses:
    Apfloat

    public class Apcomplex
    extends java.lang.Number
    implements java.util.Formattable, java.io.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.13.0
    See Also:
    Apfloat, ApcomplexMath, Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static long DEFAULT
      Default precision.
      (package private) static int EXTRA_PRECISION
      Extra precision that is added in various apfloat internal operations to avoid round-off errors.
      static Apcomplex I
      Imaginary unit.
      private Apfloat imag  
      static long INFINITE
      Infinite precision or scale.
      static Apint ONE
      Constant for one.
      (package private) static Apint[] ONES  
      private Apfloat real  
      static java.util.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 java.util.Comparator<Apcomplex> REAL_IMAG_ORDER
      Comparator for ordering by real part, and in case of a tie, by imaginary part.
      private static long serialVersionUID  
      static Apint ZERO
      Constant for zero.
      (package private) static Apint[] ZEROS  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Apcomplex()
      Default constructor.
        Apcomplex​(java.io.PushbackReader in)
      Reads an apcomplex from a reader.
        Apcomplex​(java.lang.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

      All Methods Instance Methods Concrete Methods 
      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​(java.lang.Object obj)
      Compares this object to the specified object.
      float floatValue()
      Returns the value of the this number as a float.
      void formatTo​(java.util.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.
      java.lang.String toString()
      Returns a string representation of this apcomplex.
      java.lang.String toString​(boolean pretty)
      Returns a string representation of this apcomplex.
      void writeTo​(java.io.Writer out)
      Write a string representation of this apcomplex to a Writer.
      void writeTo​(java.io.Writer out, boolean pretty)
      Write a string representation of this apcomplex to a Writer.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • 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 java.util.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 java.util.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.
      • EXTRA_PRECISION

        static final int EXTRA_PRECISION
        Extra precision that is added in various apfloat internal operations to avoid round-off errors.
        See Also:
        Constant Field Values
      • ZEROS

        static final Apint[] ZEROS
      • ONES

        static final Apint[] ONES
    • Constructor Detail

      • 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 java.lang.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:
        java.lang.IllegalArgumentException - If the real part and imaginary part are not zero but have different radixes.
      • Apcomplex

        public Apcomplex​(java.lang.String value)
                  throws java.lang.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:
        java.lang.NumberFormatException - If the number is invalid.
        ApfloatRuntimeException
      • Apcomplex

        public Apcomplex​(java.io.PushbackReader in)
                  throws java.io.IOException,
                         java.lang.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:
        java.io.IOException - In case of I/O error reading from the stream.
        java.lang.NumberFormatException - If the number is invalid.
        ApfloatRuntimeException
    • Method Detail

      • 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.
      • 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 java.lang.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:
        java.lang.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()
      • 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
      • divide

        public Apcomplex divide​(Apcomplex z)
                         throws java.lang.ArithmeticException,
                                ApfloatRuntimeException
        Divides two apcomplex numbers.
        Parameters:
        z - The number by which this number is to be divided.
        Returns:
        this / z.
        Throws:
        java.lang.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.
        Specified by:
        doubleValue in class java.lang.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.
        Specified by:
        floatValue in class java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Number
        Returns:
        The numeric value represented by this object after conversion to type long.
        See Also:
        Apfloat.longValue()
      • byteValueExact

        public byte byteValueExact()
                            throws java.lang.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:
        java.lang.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 java.lang.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:
        java.lang.ArithmeticException - If the value of this will not exactly fit in a short.
        Since:
        1.9.0
      • intValueExact

        public int intValueExact()
                          throws java.lang.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:
        java.lang.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 java.lang.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:
        java.lang.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 java.lang.NumberFormatException,
                                 ApfloatRuntimeException
        Convert this apcomplex to the specified radix.
        Parameters:
        radix - The radix.
        Returns:
        This number in the specified radix.
        Throws:
        java.lang.NumberFormatException - If the radix is invalid.
        ApfloatRuntimeException
        Since:
        1.2
      • equals

        public boolean equals​(java.lang.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 java.lang.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 java.lang.Object
        Returns:
        The hash code value for this object.
      • toString

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

        public java.lang.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​(java.io.Writer out)
                     throws java.io.IOException,
                            ApfloatRuntimeException
        Write a string representation of this apcomplex to a Writer.
        Parameters:
        out - The output Writer.
        Throws:
        java.io.IOException - In case of I/O error writing to the stream.
        ApfloatRuntimeException
      • writeTo

        public void writeTo​(java.io.Writer out,
                            boolean pretty)
                     throws java.io.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:
        java.io.IOException - In case of I/O error writing to the stream.
        ApfloatRuntimeException
      • formatTo

        public void formatTo​(java.util.Formatter formatter,
                             int flags,
                             int width,
                             int precision)
        Formats the object using the provided formatter.
        Specified by:
        formatTo in interface java.util.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)