Class BigFraction

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int DEFAULT_MAX_ITERATIONS
      The default iterations used for convergence.
      private java.math.BigInteger denominator
      The denominator of this fraction reduced to lowest terms.
      private static java.lang.String NOT_FINITE
      Message for non-finite input double argument to factory constructors.
      private java.math.BigInteger numerator
      The numerator of this fraction reduced to lowest terms.
      static BigFraction ONE
      A fraction representing "1".
      private static long OVERFLOW
      The overflow limit for conversion from a double (2^31).
      private static long serialVersionUID
      Serializable version identifier.
      static BigFraction ZERO
      A fraction representing "0".
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private BigFraction​(java.math.BigInteger num)
      Private constructor: Instances are created using factory methods.
      private BigFraction​(java.math.BigInteger num, java.math.BigInteger den)
      Private constructor: Instances are created using factory methods.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      BigFraction abs()
      Returns the absolute value of this fraction.
      BigFraction add​(int value)
      Adds the specified value to this fraction, returning the result in reduced form.
      BigFraction add​(long value)
      Adds the specified value to this fraction, returning the result in reduced form.
      BigFraction add​(java.math.BigInteger value)
      Adds the specified value to this fraction, returning the result in reduced form.
      BigFraction add​(BigFraction value)
      Adds the specified value to this fraction, returning the result in reduced form.
      java.math.BigDecimal bigDecimalValue()
      Returns the BigDecimal representation of this fraction.
      java.math.BigDecimal bigDecimalValue​(int scale, java.math.RoundingMode roundingMode)
      Returns the BigDecimal representation of this fraction.
      java.math.BigDecimal bigDecimalValue​(java.math.RoundingMode roundingMode)
      Returns the BigDecimal representation of this fraction.
      int compareTo​(BigFraction other)
      Compares this object with the specified object for order using the signed magnitude.
      BigFraction divide​(int value)
      Divide this fraction by the passed value, returning the result in reduced form.
      BigFraction divide​(long value)
      Divide this fraction by the passed value, returning the result in reduced form.
      BigFraction divide​(java.math.BigInteger value)
      Divide this fraction by the passed value, returning the result in reduced form.
      BigFraction divide​(BigFraction value)
      Divide this fraction by the passed value, returning the result in reduced form.
      double doubleValue()
      Returns the double value closest to this fraction.
      boolean equals​(java.lang.Object other)
      Test for equality with another object.
      float floatValue()
      Returns the float value closest to this fraction.
      static BigFraction from​(double value)
      Create a fraction given the double value.
      static BigFraction from​(double value, double epsilon, int maxIterations)
      Create a fraction given the double value and maximum error allowed.
      private static BigFraction from​(double value, double epsilon, int maxDenominator, int maxIterations)
      Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.
      static BigFraction from​(double value, int maxDenominator)
      Create a fraction given the double value and maximum denominator.
      java.math.BigInteger getDenominator()
      Access the denominator as a BigInteger.
      int getDenominatorAsInt()
      Access the denominator as an int.
      long getDenominatorAsLong()
      Access the denominator as a long.
      java.math.BigInteger getNumerator()
      Access the numerator as a BigInteger.
      int getNumeratorAsInt()
      Access the numerator as an int.
      long getNumeratorAsLong()
      Access the numerator as a long.
      int hashCode()  
      int intValue()
      Returns the whole number part of the fraction.
      private boolean isZero()
      Returns true if this fraction is zero.
      long longValue()
      Returns the whole number part of the fraction.
      BigFraction multiply​(int value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      BigFraction multiply​(long value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      BigFraction multiply​(java.math.BigInteger value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      BigFraction multiply​(BigFraction value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      BigFraction negate()
      Additive inverse.
      static BigFraction of​(int num)
      Create a fraction given the numerator.
      static BigFraction of​(int num, int den)
      Create a fraction given the numerator and denominator.
      static BigFraction of​(long num)
      Create a fraction given the numerator.
      static BigFraction of​(long num, long den)
      Create a fraction given the numerator and denominator.
      static BigFraction of​(java.math.BigInteger num)
      Create a fraction given the numerator.
      static BigFraction of​(java.math.BigInteger num, java.math.BigInteger den)
      Create a fraction given the numerator and denominator.
      BigFraction one()
      Identity element.
      static BigFraction parse​(java.lang.String s)
      Returns a BigFraction instance representing the specified string s.
      BigFraction pow​(int exponent)
      Returns a BigFraction whose value is thisexponent, returning the result in reduced form.
      BigFraction reciprocal()
      Multiplicative inverse.
      private static java.math.BigInteger roundAndRightShift​(java.math.BigInteger value, int bits, boolean hasFractionalBits)
      Rounds an integer to the specified power of two (i.e.
      int signum()
      Retrieves the sign of this fraction.
      BigFraction subtract​(int value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      BigFraction subtract​(long value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      BigFraction subtract​(java.math.BigInteger value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      BigFraction subtract​(BigFraction value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      private long toFloatingPointBits​(int exponentLength, int significandLength)
      Calculates the sign bit, the biased exponent and the significand for a binary floating-point representation of this BigFraction according to the IEEE 754 standard, and encodes these values into a long variable.
      java.lang.String toString()
      Returns the String representing this fraction.
      BigFraction zero()
      Identity element.
      • Methods inherited from class java.lang.Number

        byteValue, shortValue
      • Methods inherited from class java.lang.Object

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

      • ZERO

        public static final BigFraction ZERO
        A fraction representing "0".
      • ONE

        public static final BigFraction ONE
        A fraction representing "1".
      • serialVersionUID

        private static final long serialVersionUID
        Serializable version identifier.
        See Also:
        Constant Field Values
      • DEFAULT_MAX_ITERATIONS

        private static final int DEFAULT_MAX_ITERATIONS
        The default iterations used for convergence.
        See Also:
        Constant Field Values
      • NOT_FINITE

        private static final java.lang.String NOT_FINITE
        Message for non-finite input double argument to factory constructors.
        See Also:
        Constant Field Values
      • OVERFLOW

        private static final long OVERFLOW
        The overflow limit for conversion from a double (2^31).
        See Also:
        Constant Field Values
      • numerator

        private final java.math.BigInteger numerator
        The numerator of this fraction reduced to lowest terms.
      • denominator

        private final java.math.BigInteger denominator
        The denominator of this fraction reduced to lowest terms.
    • Constructor Detail

      • BigFraction

        private BigFraction​(java.math.BigInteger num,
                            java.math.BigInteger den)
        Private constructor: Instances are created using factory methods.

        This constructor should only be invoked when the fraction is known to be non-zero; otherwise use ZERO. This avoids creating the zero representation 0 / -1.

        Parameters:
        num - Numerator, must not be null.
        den - Denominator, must not be null.
        Throws:
        java.lang.ArithmeticException - if the denominator is zero.
      • BigFraction

        private BigFraction​(java.math.BigInteger num)
        Private constructor: Instances are created using factory methods.

        This sets the denominator to 1.

        Parameters:
        num - Numerator (must not be null).
    • Method Detail

      • from

        private static BigFraction from​(double value,
                                        double epsilon,
                                        int maxDenominator,
                                        int maxIterations)
        Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.

        NOTE: This method is called with:

        • EITHER a valid epsilon value and the maxDenominator set to Integer.MAX_VALUE (that way the maxDenominator has no effect)
        • OR a valid maxDenominator value and the epsilon value set to zero (that way epsilon only has effect if there is an exact match before the maxDenominator value is reached).

        It has been done this way so that the same code can be reused for both scenarios. However this could be confusing to users if it were part of the public API and this method should therefore remain PRIVATE.

        See JIRA issue ticket MATH-181 for more details: https://issues.apache.org/jira/browse/MATH-181

        Parameters:
        value - Value to convert to a fraction.
        epsilon - Maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
        maxDenominator - Maximum denominator value allowed.
        maxIterations - Maximum number of convergents.
        Returns:
        a new instance.
        Throws:
        java.lang.IllegalArgumentException - if the given value is NaN or infinite.
        java.lang.ArithmeticException - if the continued fraction failed to converge.
      • from

        public static BigFraction from​(double value)
        Create a fraction given the double value.

        This factory method behaves differently to the method from(double, double, int). It converts the double value exactly, considering its internal bits representation. This works for all values except NaN and infinities and does not requires any loop or convergence threshold.

        Since this conversion is exact and since double numbers are sometimes approximated, the fraction created may seem strange in some cases. For example, calling from(1.0 / 3.0) does not create the fraction \( \frac{1}{3} \), but the fraction \( \frac{6004799503160661}{18014398509481984} \) because the double number passed to the method is not exactly \( \frac{1}{3} \) (which cannot be represented exactly in IEEE754).

        Parameters:
        value - Value to convert to a fraction.
        Returns:
        a new instance.
        Throws:
        java.lang.IllegalArgumentException - if the given value is NaN or infinite.
        See Also:
        from(double,double,int)
      • from

        public static BigFraction from​(double value,
                                       double epsilon,
                                       int maxIterations)
        Create a fraction given the double value and maximum error allowed.

        References:

        Parameters:
        value - Value to convert to a fraction.
        epsilon - Maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
        maxIterations - Maximum number of convergents.
        Returns:
        a new instance.
        Throws:
        java.lang.IllegalArgumentException - if the given value is NaN or infinite; epsilon is not positive; or maxIterations < 1.
        java.lang.ArithmeticException - if the continued fraction failed to converge.
      • from

        public static BigFraction from​(double value,
                                       int maxDenominator)
        Create a fraction given the double value and maximum denominator.

        References:

        Note: The magnitude of the maxDenominator is used allowing use of Integer.MIN_VALUE for a supported maximum denominator of 231.

        Parameters:
        value - Value to convert to a fraction.
        maxDenominator - Maximum allowed value for denominator.
        Returns:
        a new instance.
        Throws:
        java.lang.IllegalArgumentException - if the given value is NaN or infinite or maxDenominator is zero.
        java.lang.ArithmeticException - if the continued fraction failed to converge.
      • of

        public static BigFraction of​(int num)
        Create a fraction given the numerator. The denominator is 1.
        Parameters:
        num - the numerator.
        Returns:
        a new instance.
      • of

        public static BigFraction of​(long num)
        Create a fraction given the numerator. The denominator is 1.
        Parameters:
        num - Numerator.
        Returns:
        a new instance.
      • of

        public static BigFraction of​(java.math.BigInteger num)
        Create a fraction given the numerator. The denominator is 1.
        Parameters:
        num - Numerator.
        Returns:
        a new instance.
        Throws:
        java.lang.NullPointerException - if numerator is null.
      • of

        public static BigFraction of​(int num,
                                     int den)
        Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.
        Parameters:
        num - Numerator.
        den - Denominator.
        Returns:
        a new instance.
        Throws:
        java.lang.ArithmeticException - if den is zero.
      • of

        public static BigFraction of​(long num,
                                     long den)
        Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.
        Parameters:
        num - Numerator.
        den - Denominator.
        Returns:
        a new instance.
        Throws:
        java.lang.ArithmeticException - if den is zero.
      • of

        public static BigFraction of​(java.math.BigInteger num,
                                     java.math.BigInteger den)
        Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.
        Parameters:
        num - Numerator.
        den - Denominator.
        Returns:
        a new instance.
        Throws:
        java.lang.NullPointerException - if numerator or denominator are null.
        java.lang.ArithmeticException - if the denominator is zero.
      • parse

        public static BigFraction parse​(java.lang.String s)
        Returns a BigFraction instance representing the specified string s.

        If s is null, then a NullPointerException is thrown.

        The string must be in a format compatible with that produced by BigFraction.toString(). The format expects an integer optionally followed by a '/' character and and second integer. Leading and trailing spaces are allowed around each numeric part. Each numeric part is parsed using BigInteger(String). The parts are interpreted as the numerator and optional denominator of the fraction. If absent the denominator is assumed to be "1".

        Examples of valid strings and the equivalent BigFraction are shown below:

         "0"                 = BigFraction.of(0)
         "42"                = BigFraction.of(42)
         "0 / 1"             = BigFraction.of(0, 1)
         "1 / 3"             = BigFraction.of(1, 3)
         "-4 / 13"           = BigFraction.of(-4, 13)

        Note: The fraction is returned in reduced form and the numerator and denominator may not match the values in the input string. For this reason the result of BigFraction.parse(s).toString().equals(s) may not be true.

        Parameters:
        s - String representation.
        Returns:
        an instance.
        Throws:
        java.lang.NullPointerException - if the string is null.
        java.lang.NumberFormatException - if the string does not contain a parsable fraction.
        See Also:
        BigInteger(String), toString()
      • zero

        public BigFraction zero()
        Description copied from interface: Addition
        Identity element.
        Specified by:
        zero in interface Addition<BigFraction>
        Returns:
        the field element such that for all a, zero().add(a).equals(a) is true.
      • getNumerator

        public java.math.BigInteger getNumerator()
        Access the numerator as a BigInteger.
        Returns:
        the numerator as a BigInteger.
      • getNumeratorAsInt

        public int getNumeratorAsInt()
        Access the numerator as an int.
        Returns:
        the numerator as an int.
      • getNumeratorAsLong

        public long getNumeratorAsLong()
        Access the numerator as a long.
        Returns:
        the numerator as a long.
      • getDenominator

        public java.math.BigInteger getDenominator()
        Access the denominator as a BigInteger.
        Returns:
        the denominator as a BigInteger.
      • getDenominatorAsInt

        public int getDenominatorAsInt()
        Access the denominator as an int.
        Returns:
        the denominator as an int.
      • getDenominatorAsLong

        public long getDenominatorAsLong()
        Access the denominator as a long.
        Returns:
        the denominator as a long.
      • signum

        public int signum()
        Retrieves the sign of this fraction.
        Returns:
        -1 if the value is strictly negative, 1 if it is strictly positive, 0 if it is 0.
      • abs

        public BigFraction abs()
        Returns the absolute value of this fraction.
        Returns:
        the absolute value.
      • reciprocal

        public BigFraction reciprocal()
        Multiplicative inverse.

        Raises an exception if the fraction is equal to zero.

        Specified by:
        reciprocal in interface Multiplication<BigFraction>
        Returns:
        this-1.
        Throws:
        java.lang.ArithmeticException - if the current numerator is zero
      • doubleValue

        public double doubleValue()
        Returns the double value closest to this fraction.
        Specified by:
        doubleValue in class java.lang.Number
        Returns:
        the fraction as a double.
      • floatValue

        public float floatValue()
        Returns the float value closest to this fraction.
        Specified by:
        floatValue in class java.lang.Number
        Returns:
        the fraction as a double.
      • intValue

        public int intValue()
        Returns the whole number part of the fraction.
        Specified by:
        intValue in class java.lang.Number
        Returns:
        the largest int value that is not larger than this fraction.
      • longValue

        public long longValue()
        Returns the whole number part of the fraction.
        Specified by:
        longValue in class java.lang.Number
        Returns:
        the largest long value that is not larger than this fraction.
      • bigDecimalValue

        public java.math.BigDecimal bigDecimalValue()
        Returns the BigDecimal representation of this fraction. This calculates the fraction as numerator divided by denominator.
        Returns:
        the fraction as a BigDecimal.
        Throws:
        java.lang.ArithmeticException - if the exact quotient does not have a terminating decimal expansion.
        See Also:
        BigDecimal
      • bigDecimalValue

        public java.math.BigDecimal bigDecimalValue​(java.math.RoundingMode roundingMode)
        Returns the BigDecimal representation of this fraction. This calculates the fraction as numerator divided by denominator following the passed rounding mode.
        Parameters:
        roundingMode - Rounding mode to apply.
        Returns:
        the fraction as a BigDecimal.
        See Also:
        BigDecimal
      • bigDecimalValue

        public java.math.BigDecimal bigDecimalValue​(int scale,
                                                    java.math.RoundingMode roundingMode)
        Returns the BigDecimal representation of this fraction. This calculates the fraction as numerator divided by denominator following the passed scale and rounding mode.
        Parameters:
        scale - scale of the BigDecimal quotient to be returned. see BigDecimal for more information.
        roundingMode - Rounding mode to apply.
        Returns:
        the fraction as a BigDecimal.
        Throws:
        java.lang.ArithmeticException - if roundingMode == RoundingMode.UNNECESSARY and the specified scale is insufficient to represent the result of the division exactly.
        See Also:
        BigDecimal
      • add

        public BigFraction add​(int value)
        Adds the specified value to this fraction, returning the result in reduced form.
        Parameters:
        value - Value to add.
        Returns:
        this + value.
      • add

        public BigFraction add​(long value)
        Adds the specified value to this fraction, returning the result in reduced form.
        Parameters:
        value - Value to add.
        Returns:
        this + value.
      • add

        public BigFraction add​(java.math.BigInteger value)
        Adds the specified value to this fraction, returning the result in reduced form.
        Parameters:
        value - Value to add.
        Returns:
        this + value.
      • add

        public BigFraction add​(BigFraction value)
        Adds the specified value to this fraction, returning the result in reduced form.
        Specified by:
        add in interface Addition<BigFraction>
        Parameters:
        value - Value to add.
        Returns:
        this + value.
      • subtract

        public BigFraction subtract​(int value)
        Subtracts the specified value from this fraction, returning the result in reduced form.
        Parameters:
        value - Value to subtract.
        Returns:
        this - value.
      • subtract

        public BigFraction subtract​(long value)
        Subtracts the specified value from this fraction, returning the result in reduced form.
        Parameters:
        value - Value to subtract.
        Returns:
        this - value.
      • subtract

        public BigFraction subtract​(java.math.BigInteger value)
        Subtracts the specified value from this fraction, returning the result in reduced form.
        Parameters:
        value - Value to subtract.
        Returns:
        this - value.
      • subtract

        public BigFraction subtract​(BigFraction value)
        Subtracts the specified value from this fraction, returning the result in reduced form.
        Specified by:
        subtract in interface NativeOperators<BigFraction>
        Parameters:
        value - Value to subtract.
        Returns:
        this - value.
      • multiply

        public BigFraction multiply​(int value)
        Multiply this fraction by the passed value, returning the result in reduced form.
        Specified by:
        multiply in interface NativeOperators<BigFraction>
        Parameters:
        value - Value to multiply by.
        Returns:
        this * value.
      • multiply

        public BigFraction multiply​(long value)
        Multiply this fraction by the passed value, returning the result in reduced form.
        Parameters:
        value - Value to multiply by.
        Returns:
        this * value.
      • multiply

        public BigFraction multiply​(java.math.BigInteger value)
        Multiply this fraction by the passed value, returning the result in reduced form.
        Parameters:
        value - Value to multiply by.
        Returns:
        this * value.
      • multiply

        public BigFraction multiply​(BigFraction value)
        Multiply this fraction by the passed value, returning the result in reduced form.
        Specified by:
        multiply in interface Multiplication<BigFraction>
        Parameters:
        value - Value to multiply by.
        Returns:
        this * value.
      • divide

        public BigFraction divide​(int value)
        Divide this fraction by the passed value, returning the result in reduced form.
        Parameters:
        value - Value to divide by
        Returns:
        this / value.
        Throws:
        java.lang.ArithmeticException - if the value to divide by is zero
      • divide

        public BigFraction divide​(long value)
        Divide this fraction by the passed value, returning the result in reduced form.
        Parameters:
        value - Value to divide by
        Returns:
        this / value.
        Throws:
        java.lang.ArithmeticException - if the value to divide by is zero
      • divide

        public BigFraction divide​(java.math.BigInteger value)
        Divide this fraction by the passed value, returning the result in reduced form.
        Parameters:
        value - Value to divide by
        Returns:
        this / value.
        Throws:
        java.lang.ArithmeticException - if the value to divide by is zero
      • divide

        public BigFraction divide​(BigFraction value)
        Divide this fraction by the passed value, returning the result in reduced form.
        Specified by:
        divide in interface NativeOperators<BigFraction>
        Parameters:
        value - Value to divide by
        Returns:
        this / value.
        Throws:
        java.lang.ArithmeticException - if the value to divide by is zero
      • pow

        public BigFraction pow​(int exponent)
        Returns a BigFraction whose value is thisexponent, returning the result in reduced form.
        Specified by:
        pow in interface NativeOperators<BigFraction>
        Parameters:
        exponent - exponent to which this BigFraction is to be raised.
        Returns:
        thisexponent.
        Throws:
        java.lang.ArithmeticException - if the intermediate result would overflow.
      • toString

        public java.lang.String toString()
        Returns the String representing this fraction. Uses:
        • "0" if numerator is zero.
        • "numerator" if denominator is one.
        • "numerator / denominator" for all other cases.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of the fraction.
      • compareTo

        public int compareTo​(BigFraction other)
        Compares this object with the specified object for order using the signed magnitude.
        Specified by:
        compareTo in interface java.lang.Comparable<BigFraction>
        Parameters:
        other -
        Returns:
      • equals

        public boolean equals​(java.lang.Object other)
        Test for equality with another object. If the other object is a Fraction then a comparison is made of the sign and magnitude; otherwise false is returned.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other -
        Returns:
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toFloatingPointBits

        private long toFloatingPointBits​(int exponentLength,
                                         int significandLength)
        Calculates the sign bit, the biased exponent and the significand for a binary floating-point representation of this BigFraction according to the IEEE 754 standard, and encodes these values into a long variable. The representative bits are arranged adjacent to each other and placed at the low-order end of the returned long value, with the least significant bits used for the significand, the next more significant bits for the exponent, and next more significant bit for the sign.

        Warning: The arguments are not validated.

        Parameters:
        exponentLength - the number of bits allowed for the exponent; must be between 1 and 32 (inclusive), and must not be greater than 63 - significandLength
        significandLength - the number of bits allowed for the significand (excluding the implicit leading 1-bit in normalized numbers, e.g. 52 for a double-precision floating-point number); must be between 1 and 63 - exponentLength (inclusive)
        Returns:
        the bits of an IEEE 754 binary floating-point representation of this fraction encoded in a long, as described above.
      • roundAndRightShift

        private static java.math.BigInteger roundAndRightShift​(java.math.BigInteger value,
                                                               int bits,
                                                               boolean hasFractionalBits)
        Rounds an integer to the specified power of two (i.e. the minimum number of low-order bits that must be zero) and performs a right-shift by this amount. The rounding mode applied is round to nearest, with ties rounding to even (meaning the prospective least significant bit must be zero). The number can optionally be treated as though it contained at least one 0-bit and one 1-bit in its fractional part, to influence the result in cases that would otherwise be a tie.
        Parameters:
        value - the number to round and right-shift
        bits - the power of two to which to round; must be positive
        hasFractionalBits - whether the number should be treated as though it contained a non-zero fractional part
        Returns:
        a BigInteger as described above
        Throws:
        java.lang.IllegalArgumentException - if bits <= 0
      • isZero

        private boolean isZero()
        Returns true if this fraction is zero.
        Returns:
        true if zero