Package org.apfloat

Class Apfloat

java.lang.Object
java.lang.Number
org.apfloat.Apcomplex
org.apfloat.Apfloat
All Implemented Interfaces:
Serializable, Comparable<Apfloat>, Formattable
Direct Known Subclasses:
Aprational
public class Apfloat extends Apcomplex implements Comparable<Apfloat>
Arbitrary precision floating-point number class.

Apfloat numbers are immutable.

A pitfall exists with the constructors Apfloat(float,long) and Apfloat(double,long). Since floats and doubles are always represented internally in radix 2, the conversion to any other radix usually causes round-off errors, and the resulting apfloat won't be accurate to the desired number of digits.

For example, 0.3 can't be presented exactly in base 2. When you construct an apfloat like new Apfloat(0.3f, 1000), the resulting number won't be accurate to 1000 digits, but only to roughly 7 digits (in radix 10). In fact, the resulting number will be something like 0.30000001192092896...

If you want an exact representation of a floating-point primitive (which is a rational number), you can use Aprational(double).

Version:
1.11.1
Author:
Mikko Tommila
See Also:

  • Field Summary

    Fields inherited from class org.apfloat.Apcomplex

    DEFAULT, I, INFINITE, ONE, REAL_ABS_IMAG_ORDER, REAL_IMAG_ORDER, ZERO

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Apfloat()
    Default constructor.
     
    Apfloat(double value)
    Constructs an apfloat from the specified double.
     
    Apfloat(double value, long precision)
    Constructs an apfloat from the specified double and precision.
     
    Apfloat(double value, long precision, int radix)
    Constructs an apfloat from the specified double, precision and radix.
     
    Apfloat(float value)
    Constructs an apfloat from the specified float.
     
    Apfloat(float value, long precision)
    Constructs an apfloat from the specified float and precision.
     
    Apfloat(float value, long precision, int radix)
    Constructs an apfloat from the specified float, precision and radix.
     
    Apfloat(long value)
    Constructs an apfloat from the specified long.
     
    Apfloat(long value, long precision)
    Constructs an apfloat from the specified long and precision.
     
    Apfloat(long value, long precision, int radix)
    Constructs an apfloat from the specified long, precision and radix.
     
    Apfloat(PushbackReader in)
    Reads an apfloat from a stream using default precision and radix.
     
    Apfloat(PushbackReader in, long precision)
    Reads an apfloat from a stream using the specified precision.
     
    Apfloat(PushbackReader in, long precision, int radix)
    Reads an apfloat from a stream using the specified precision and radix.
     
    Apfloat(String value)
    Constructs an apfloat from the specified string.
     
    Apfloat(String value, long precision)
    Constructs an apfloat from the specified string and precision.
     
    Apfloat(String value, long precision, int radix)
    Constructs an apfloat from the specified string, precision and radix.
     
    Apfloat(BigDecimal value)
    Creates an apfloat from a BigDecimal.
     
    Apfloat(BigDecimal value, long precision)
    Creates an apfloat from a BigDecimal.
     
    Apfloat(BigInteger value)
    Constructs an apfloat from a BigInteger.
     
    Apfloat(BigInteger value, long precision)
    Constructs an apfloat from a BigInteger with the specified precision.
     
    Apfloat(BigInteger value, long precision, int radix)
    Constructs an apfloat from a BigInteger with the specified precision and radix.
    protected
    Apfloat(ApfloatImpl impl)
    Constructs an apfloat that is backed by the specified ApfloatImpl object.

  • Method Summary

    Modifier and Type
    Method
    Description
    Apfloat
    add(Apfloat x)
    Adds two apfloats.
    byte
    byteValue()
    Returns the value of the this number as a byte.
    Apint
    ceil()
    Ceiling function.
    int
    compareTo(Apfloat x)
    Compare this apfloat to the specified apfloat.
    Apfloat
    divide(Apfloat x)
    Divides two apfloats.
    double
    doubleValue()
    Returns the value of the this number as a double.
    long
    equalDigits(Apfloat x)
    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.
    Apint
    floor()
    Floor function.
    void
    formatTo(Formatter formatter, int flags, int width, int precision)
    Formats the object using the provided formatter.
    Apfloat
    frac()
    Returns the fractional part.
    protected ApfloatImpl
    getImpl(long precision)
    Returns an ApfloatImpl representing the actual instance of this apfloat up to the requested precision.
    int
    hashCode()
    Returns a hash code for this apfloat.
    Apfloat
    imag()
    Imaginary part of this apfloat.
    int
    intValue()
    Returns the value of the this number as an int.
    boolean
    isInteger()
    Returns if this number has an integer value.
    boolean
    isShort()
    Returns if this apfloat is "short".
    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.
    Apfloat
    mod(Apfloat x)
    Calculates the remainder when divided by an apfloat.
    Apfloat
    multiply(Apfloat x)
    Multiplies two apfloats.
    Apfloat
    negate()
    Negative value.
    long
    precision()
    Returns the precision of this apfloat.
    Apfloat
    precision(long precision)
    Returns an apfloat with the same value as this apfloat accurate to the specified precision.
    boolean
    preferCompare(Apfloat x)
    Tests if the comparison with equals and compareTo should be done in the opposite order.
    int
    radix()
    Radix of this apfloat.
    Apfloat
    real()
    Real part of this apfloat.
    long
    scale()
    Returns the scale of this apfloat.
    short
    shortValue()
    Returns the value of the this number as a short.
    int
    signum()
    Returns the signum function of this apfloat.
    long
    size()
    Returns the size of this apfloat.
    Apfloat
    subtract(Apfloat x)
    Subtracts two apfloats.
    boolean
    test(Apfloat x)
    Tests two apfloat numbers for equality.
    Apfloat
    toRadix(int radix)
    Convert this apfloat to the specified radix.
    String
    toString(boolean pretty)
    Returns a string representation of this apfloat.
    Apint
    truncate()
    Truncates fractional part.
    void
    writeTo(Writer out, boolean pretty)
    Write a string representation of this apfloat to a Writer.

    Methods inherited from class org.apfloat.Apcomplex

    add, byteValueExact, conj, divide, equalDigits, intValueExact, isZero, multiply, shortValueExact, subtract, test, toString, writeTo

    Methods inherited from class java.lang.Object

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

  • Constructor Details

  • Method Details

    • radix

      public int radix()
      Radix of this apfloat.
      Overrides:
      radix in class Apcomplex
      Returns:
      Radix of this apfloat.

    • real

      public Apfloat real()
      Real part of this apfloat.
      Overrides:
      real in class Apcomplex
      Returns:
      this

    • imag

      public Apfloat imag()
      Imaginary part of this apfloat.
      Overrides:
      imag in class Apcomplex
      Returns:
      Apcomplex.ZERO

    • precision

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

    • precision

      public Apfloat precision(long precision) throws IllegalArgumentException, ApfloatRuntimeException
      Returns an apfloat with the same value as this apfloat 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.

      Overrides:
      precision in class Apcomplex
      Parameters:
      precision - Precision of the new apfloat.
      Returns:
      An apfloat with the specified precision and same value as this apfloat.
      Throws:
      IllegalArgumentException - If precision is <= 0.
      ApfloatRuntimeException

    • scale

      public long scale() throws ApfloatRuntimeException
      Returns the scale of this apfloat. The scale is defined here as

      apfloat = signum * mantissa * radixscale

      where 1/radix <= mantissa < 1. In other words, scale = floor(logradix(apfloat)) + 1.

      For example, 1 has a scale of 1, and 100 has a scale of 3 (in radix 10). For integers, scale is equal to the number of digits in the apfloat.

      Zero has a scale of -INFINITE.

      Note that this definition of scale is different than in java.math.BigDecimal.

      Overrides:
      scale in class Apcomplex
      Returns:
      The exponent of this apfloat in number of digits of the radix in which it's presented.
      Throws:
      ApfloatRuntimeException
      See Also:

    • size

      public long size() throws ApfloatRuntimeException
      Returns the size of this apfloat. The size is defined here as

      apfloat = signum * mantissa * radixscale and

      mantissa = n / radixsize

      where 1/radix <= mantissa < 1 and n is the smallest possible integer. In other words, the size is the number of significant digits in the mantissa (excluding leading and trailing zeros but including all zeros between the first and last nonzero digit). For example, 1 has a size of 1, and 100 has also a size of 1 (in radix 10). 11 has a size of 2, and 10001000 has a size of 5.

      Zero has a size of 0.

      Overrides:
      size in class Apcomplex
      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:

    • signum

      public int signum()
      Returns the signum function of this apfloat.
      Returns:
      -1, 0 or 1 as the value of this apfloat is negative, zero or positive, correspondingly.

    • 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.
      Overrides:
      isInteger in class Apcomplex
      Returns:
      If this number's value is an integer.
      Throws:
      ApfloatRuntimeException
      Since:
      1.9.0

    • isShort

      public boolean isShort() throws ApfloatRuntimeException
      Returns if this apfloat is "short". In practice an apfloat is "short" if its mantissa fits in one machine word. If the apfloat is "short", some algorithms can be performed faster.

      For example, division by a "short" apfloat requires only a single pass through the data, but that algorithm can't be used for divisors that aren't "short", where calculating an inverse root is required instead.

      The return value of this method is implementation dependent.

      Returns:
      true if the apfloat is "short", false if not.
      Throws:
      ApfloatRuntimeException

    • negate

      public Apfloat negate() throws ApfloatRuntimeException
      Negative value.
      Overrides:
      negate in class Apcomplex
      Returns:
      -this.
      Throws:
      ApfloatRuntimeException
      Since:
      1.1

    • add

      public Apfloat add(Apfloat x) throws ApfloatRuntimeException
      Adds two apfloats.
      Parameters:
      x - The number to be added to this number.
      Returns:
      this + x.
      Throws:
      ApfloatRuntimeException

    • subtract

      public Apfloat subtract(Apfloat x) throws ApfloatRuntimeException
      Subtracts two apfloats.
      Parameters:
      x - The number to be subtracted from this number.
      Returns:
      this - x.
      Throws:
      ApfloatRuntimeException

    • multiply

      public Apfloat multiply(Apfloat x) throws ApfloatRuntimeException
      Multiplies two apfloats.
      Parameters:
      x - The number to be multiplied by this number.
      Returns:
      this * x.
      Throws:
      ApfloatRuntimeException

    • divide

      public Apfloat divide(Apfloat x) throws ArithmeticException, ApfloatRuntimeException
      Divides two apfloats.
      Parameters:
      x - The number by which this number is to be divided.
      Returns:
      this / x.
      Throws:
      ArithmeticException - In case the divisor is zero.
      ApfloatRuntimeException

    • mod

      public Apfloat mod(Apfloat x) throws ApfloatRuntimeException
      Calculates the remainder when divided by an apfloat. The result has the same sign as this number. If x is zero, then zero is returned.
      Parameters:
      x - The number that is used as the divisor in the remainder calculation.
      Returns:
      this % x.
      Throws:
      ApfloatRuntimeException
      Since:
      1.2
      See Also:

    • floor

      public Apint floor() throws ApfloatRuntimeException
      Floor function. Returns the largest (closest to positive infinity) value that is not greater than this apfloat and is equal to a mathematical integer.
      Returns:
      This apfloat rounded towards negative infinity.
      Throws:
      ApfloatRuntimeException

    • ceil

      public Apint ceil() throws ApfloatRuntimeException
      Ceiling function. Returns the smallest (closest to negative infinity) value that is not less than this apfloat and is equal to a mathematical integer.
      Returns:
      This apfloat rounded towards positive infinity.
      Throws:
      ApfloatRuntimeException

    • truncate

      public Apint truncate() throws ApfloatRuntimeException
      Truncates fractional part.
      Returns:
      This apfloat rounded towards zero.
      Throws:
      ApfloatRuntimeException

    • frac

      public Apfloat frac() throws ApfloatRuntimeException
      Returns the fractional part. The fractional part is always 0 <= abs(frac()) < 1. The fractional part has the same sign as the number. For the fractional and integer parts, this always holds:

      x = x.truncate() + x.frac()

      Returns:
      The fractional part of this apfloat.
      Throws:
      ApfloatRuntimeException
      Since:
      1.7.0

    • doubleValue

      public double doubleValue()
      Returns the value of the this number as a double. If the number is too big to fit in a double, Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.
      Overrides:
      doubleValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type double.
      See Also:

    • floatValue

      public float floatValue()
      Returns the value of the this number as a float. If the number is too big to fit in a float, Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned.
      Overrides:
      floatValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type float.
      See Also:

    • byteValue

      public byte byteValue()
      Returns the value of the this number as a byte. If the number is too big to fit in a byte, Byte.MIN_VALUE or Byte.MAX_VALUE is returned.
      Overrides:
      byteValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type byte.
      See Also:

    • shortValue

      public short shortValue()
      Returns the value of the this number as a short. If the number is too big to fit in a short, Short.MIN_VALUE or Short.MAX_VALUE is returned.
      Overrides:
      shortValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type short.
      See Also:

    • intValue

      public int intValue()
      Returns the value of the this number as an int. If the number is too big to fit in an int, Integer.MIN_VALUE or Integer.MAX_VALUE is returned.
      Overrides:
      intValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type int.
      See Also:

    • longValue

      public long longValue()
      Returns the value of the this number as a long. If the number is too big to fit in a long, Long.MIN_VALUE or Long.MAX_VALUE is returned.
      Overrides:
      longValue in class Apcomplex
      Returns:
      The numeric value represented by this object after conversion to type long.
      See Also:

    • longValueExact

      public long longValueExact() throws ArithmeticException
      Description copied from class: Apcomplex
      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.
      Overrides:
      longValueExact in class Apcomplex
      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.

    • equalDigits

      public long equalDigits(Apfloat x) 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 and 123456 have zero matching digits, and the numbers 12345 and 12355 have three matching digits.

      The result of this method is roughly equal to Math.min(scale(), x.scale()) - subtract(x).scale() but it typically is a lot more efficient to execute.

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

    • toRadix

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

    • compareTo

      public int compareTo(Apfloat x)
      Compare this apfloat to the specified apfloat.

      Note: if two apfloats are compared where one number doesn't have enough precise digits, the mantissa is assumed to contain zeros. For example: 

       Apfloat x = new Apfloat("0.12", 2);
 Apfloat y = new Apfloat("0.12345", 5);
      Now x.compareTo(y) < 0 because x is assumed to be 0.12000.

      However, new Apfloat("0.12", 2) and new Apfloat("0.12", 5) would be considered equal.

      Specified by:
      compareTo in interface Comparable<Apfloat>
      Parameters:
      x - Apfloat to which this apfloat is to be compared.
      Returns:
      -1, 0 or 1 as this apfloat is numerically less than, equal to, or greater than x.

    • preferCompare

      public boolean preferCompare(Apfloat x)
      Tests if the comparison with equals and compareTo should be done in the opposite order.

      Implementations should avoid infinite recursion.

      Parameters:
      x - The number to compare to.
      Returns:
      true if this object should invoke x.equals(this) and -x.compareTo(this) instead of comparing normally.
      Since:
      1.7.0

    • equals

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

      Note: if two apfloats are compared where one number doesn't have enough precise digits, the mantissa is assumed to contain zeros. See compareTo(Apfloat).

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

    • test

      public boolean test(Apfloat x) throws ApfloatRuntimeException
      Tests two apfloat 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:
      x - 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 apfloat.
      Overrides:
      hashCode in class Apcomplex
      Returns:
      The hash code value for this object.

    • toString

      public String toString(boolean pretty) throws ApfloatRuntimeException
      Returns a string representation of this apfloat.
      Overrides:
      toString in class 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, boolean pretty) throws IOException, ApfloatRuntimeException
      Write a string representation of this apfloat to a Writer.
      Overrides:
      writeTo in class Apcomplex
      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.

      The format specifiers affect the output as follows:

      • By default, the exponential notation is used.
      • If the alternate format is specified ('#'), then the fixed-point notation is used.
      • Width is the minimum number of characters output. Any padding is done using spaces. Padding is on the left by default.
      • If the '-' flag is specified, then the padding will be on the right.
      • The precision is the number of significant digts output. If the precision of the number exceeds the number of characters output, the rounding mode for output is undefined.

      The decimal separator will be localized if the formatter specifies a locale. The digits will be localized also, but only if the radix is less than or equal to 10.

      Specified by:
      formatTo in interface Formattable
      Overrides:
      formatTo in class Apcomplex
      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:

    • getImpl

      protected ApfloatImpl getImpl(long precision) throws ApfloatRuntimeException
      Returns an ApfloatImpl representing the actual instance of this apfloat up to the requested precision.

      For apfloats this is simply the underlying ApfloatImpl, but e.g. the Aprational class implements this so that it only returns an approximation of the rational number.

      Parameters:
      precision - Precision of the ApfloatImpl that is needed.
      Returns:
      An ApfloatImpl representing this object to the requested precision.
      Throws:
      ApfloatRuntimeException