Package org.apache.commons.lang3.math

Class Fraction

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Fraction>
    public final class Fraction
extends java.lang.Number
implements java.lang.Comparable<Fraction>

    Fraction is a Number implementation that stores fractions accurately.

    This class is immutable, and interoperable with most methods that accept a Number.

    Note that this class is intended for common use cases, it is int based and thus suffers from various overflow issues. For a BigInteger based equivalent, please see the Commons Math BigFraction class.

    Since:
    2.0
    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Fraction abs()
      Gets a fraction that is the positive equivalent of this one.
      Fraction add​(Fraction fraction)
      Adds the value of this fraction to another, returning the result in reduced form.
      int compareTo​(Fraction other)
      Compares this object to another based on size.
      Fraction divideBy​(Fraction fraction)
      Divide the value of this fraction by another.
      double doubleValue()
      Gets the fraction as a double.
      boolean equals​(java.lang.Object obj)
      Compares this fraction to another object to test if they are equal.
      float floatValue()
      Gets the fraction as a float.
      int getDenominator()
      Gets the denominator part of the fraction.
      static Fraction getFraction​(double value)
      Creates a Fraction instance from a double value.
      static Fraction getFraction​(int numerator, int denominator)
      Creates a Fraction instance with the 2 parts of a fraction Y/Z.
      static Fraction getFraction​(int whole, int numerator, int denominator)
      Creates a Fraction instance with the 3 parts of a fraction X Y/Z.
      static Fraction getFraction​(java.lang.String str)
      Creates a Fraction from a String.
      int getNumerator()
      Gets the numerator part of the fraction.
      int getProperNumerator()
      Gets the proper numerator, always positive.
      int getProperWhole()
      Gets the proper whole part of the fraction.
      static Fraction getReducedFraction​(int numerator, int denominator)
      Creates a reduced Fraction instance with the 2 parts of a fraction Y/Z.
      int hashCode()
      Gets a hashCode for the fraction.
      int intValue()
      Gets the fraction as an int.
      Fraction invert()
      Gets a fraction that is the inverse (1/fraction) of this one.
      long longValue()
      Gets the fraction as a long.
      Fraction multiplyBy​(Fraction fraction)
      Multiplies the value of this fraction by another, returning the result in reduced form.
      Fraction negate()
      Gets a fraction that is the negative (-fraction) of this one.
      Fraction pow​(int power)
      Gets a fraction that is raised to the passed in power.
      Fraction reduce()
      Reduce the fraction to the smallest values for the numerator and denominator, returning the result.
      Fraction subtract​(Fraction fraction)
      Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
      java.lang.String toProperString()
      Gets the fraction as a proper String in the format X Y/Z.
      java.lang.String toString()
      Gets the fraction as a String.

      • 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 Fraction ZERO
        Fraction representation of 0.

      • ONE

        public static final Fraction ONE
        Fraction representation of 1.

      • ONE_HALF

        public static final Fraction ONE_HALF
        Fraction representation of 1/2.

      • ONE_THIRD

        public static final Fraction ONE_THIRD
        Fraction representation of 1/3.

      • TWO_THIRDS

        public static final Fraction TWO_THIRDS
        Fraction representation of 2/3.

      • ONE_QUARTER

        public static final Fraction ONE_QUARTER
        Fraction representation of 1/4.

      • TWO_QUARTERS

        public static final Fraction TWO_QUARTERS
        Fraction representation of 2/4.

      • THREE_QUARTERS

        public static final Fraction THREE_QUARTERS
        Fraction representation of 3/4.

      • ONE_FIFTH

        public static final Fraction ONE_FIFTH
        Fraction representation of 1/5.

      • TWO_FIFTHS

        public static final Fraction TWO_FIFTHS
        Fraction representation of 2/5.

      • THREE_FIFTHS

        public static final Fraction THREE_FIFTHS
        Fraction representation of 3/5.

      • FOUR_FIFTHS

        public static final Fraction FOUR_FIFTHS
        Fraction representation of 4/5.

    • Method Detail

      • getFraction

        public static Fraction getFraction​(int numerator,
                                   int denominator)

        Creates a Fraction instance with the 2 parts of a fraction Y/Z.

        Any negative signs are resolved to be on the numerator.

        Parameters:
        numerator - the numerator, for example the three in 'three sevenths'
        denominator - the denominator, for example the seven in 'three sevenths'
        Returns:
        a new fraction instance
        Throws:
        java.lang.ArithmeticException - if the denominator is zero or the denominator is negative and the numerator is Integer#MIN_VALUE

      • getFraction

        public static Fraction getFraction​(int whole,
                                   int numerator,
                                   int denominator)

        Creates a Fraction instance with the 3 parts of a fraction X Y/Z.

        The negative sign must be passed in on the whole number part.

        Parameters:
        whole - the whole number, for example the one in 'one and three sevenths'
        numerator - the numerator, for example the three in 'one and three sevenths'
        denominator - the denominator, for example the seven in 'one and three sevenths'
        Returns:
        a new fraction instance
        Throws:
        java.lang.ArithmeticException - if the denominator is zero
        java.lang.ArithmeticException - if the denominator is negative
        java.lang.ArithmeticException - if the numerator is negative
        java.lang.ArithmeticException - if the resulting numerator exceeds Integer.MAX_VALUE

      • getReducedFraction

        public static Fraction getReducedFraction​(int numerator,
                                          int denominator)

        Creates a reduced Fraction instance with the 2 parts of a fraction Y/Z.

        For example, if the input parameters represent 2/4, then the created fraction will be 1/2.

        Any negative signs are resolved to be on the numerator.

        Parameters:
        numerator - the numerator, for example the three in 'three sevenths'
        denominator - the denominator, for example the seven in 'three sevenths'
        Returns:
        a new fraction instance, with the numerator and denominator reduced
        Throws:
        java.lang.ArithmeticException - if the denominator is zero

      • getFraction

        public static Fraction getFraction​(double value)

        Creates a Fraction instance from a double value.

        This method uses the continued fraction algorithm, computing a maximum of 25 convergents and bounding the denominator by 10,000.

        Parameters:
        value - the double value to convert
        Returns:
        a new fraction instance that is close to the value
        Throws:
        java.lang.ArithmeticException - if |value| &gt; Integer.MAX_VALUE or value = NaN
        java.lang.ArithmeticException - if the calculated denominator is zero
        java.lang.ArithmeticException - if the algorithm does not converge

      • getFraction

        public static Fraction getFraction​(java.lang.String str)

        Creates a Fraction from a String.

        The formats accepted are:

        1. double String containing a dot
        2. 'X Y/Z'
        3. 'Y/Z'
        4. 'X' (a simple whole number)

        and a .

        Parameters:
        str - the string to parse, must not be null
        Returns:
        the new Fraction instance
        Throws:
        java.lang.NullPointerException - if the string is null
        java.lang.NumberFormatException - if the number format is invalid

      • getNumerator

        public int getNumerator()

        Gets the numerator part of the fraction.

        This method may return a value greater than the denominator, an improper fraction, such as the seven in 7/4.

        Returns:
        the numerator fraction part

      • getDenominator

        public int getDenominator()

        Gets the denominator part of the fraction.

        Returns:
        the denominator fraction part

      • getProperNumerator

        public int getProperNumerator()

        Gets the proper numerator, always positive.

        An improper fraction 7/4 can be resolved into a proper one, 1 3/4. This method returns the 3 from the proper fraction.

        If the fraction is negative such as -7/4, it can be resolved into -1 3/4, so this method returns the positive proper numerator, 3.

        Returns:
        the numerator fraction part of a proper fraction, always positive

      • getProperWhole

        public int getProperWhole()

        Gets the proper whole part of the fraction.

        An improper fraction 7/4 can be resolved into a proper one, 1 3/4. This method returns the 1 from the proper fraction.

        If the fraction is negative such as -7/4, it can be resolved into -1 3/4, so this method returns the positive whole part -1.

        Returns:
        the whole fraction part of a proper fraction, that includes the sign

      • intValue

        public int intValue()

        Gets the fraction as an int. This returns the whole number part of the fraction.

        Specified by:
        intValue in class java.lang.Number
        Returns:
        the whole number fraction part

      • longValue

        public long longValue()

        Gets the fraction as a long. This returns the whole number part of the fraction.

        Specified by:
        longValue in class java.lang.Number
        Returns:
        the whole number fraction part

      • floatValue

        public float floatValue()

        Gets the fraction as a float. This calculates the fraction as the numerator divided by denominator.

        Specified by:
        floatValue in class java.lang.Number
        Returns:
        the fraction as a float

      • doubleValue

        public double doubleValue()

        Gets the fraction as a double. This calculates the fraction as the numerator divided by denominator.

        Specified by:
        doubleValue in class java.lang.Number
        Returns:
        the fraction as a double

      • reduce

        public Fraction reduce()

        Reduce the fraction to the smallest values for the numerator and denominator, returning the result.

        For example, if this fraction represents 2/4, then the result will be 1/2.

        Returns:
        a new reduced fraction instance, or this if no simplification possible

      • invert

        public Fraction invert()

        Gets a fraction that is the inverse (1/fraction) of this one.

        The returned fraction is not reduced.

        Returns:
        a new fraction instance with the numerator and denominator inverted.
        Throws:
        java.lang.ArithmeticException - if the fraction represents zero.

      • negate

        public Fraction negate()

        Gets a fraction that is the negative (-fraction) of this one.

        The returned fraction is not reduced.

        Returns:
        a new fraction instance with the opposite signed numerator

      • abs

        public Fraction abs()

        Gets a fraction that is the positive equivalent of this one.

        More precisely: (fraction &gt;= 0 ? this : -fraction)

        The returned fraction is not reduced.

        Returns:
        this if it is positive, or a new positive fraction instance with the opposite signed numerator

      • pow

        public Fraction pow​(int power)

        Gets a fraction that is raised to the passed in power.

        The returned fraction is in reduced form.

        Parameters:
        power - the power to raise the fraction to
        Returns:
        this if the power is one, ONE if the power is zero (even if the fraction equals ZERO) or a new fraction instance raised to the appropriate power
        Throws:
        java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

      • add

        public Fraction add​(Fraction fraction)

        Adds the value of this fraction to another, returning the result in reduced form. The algorithm follows Knuth, 4.5.1.

        Parameters:
        fraction - the fraction to add, must not be null
        Returns:
        a Fraction instance with the resulting values
        Throws:
        java.lang.IllegalArgumentException - if the fraction is null
        java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

      • subtract

        public Fraction subtract​(Fraction fraction)

        Subtracts the value of another fraction from the value of this one, returning the result in reduced form.

        Parameters:
        fraction - the fraction to subtract, must not be null
        Returns:
        a Fraction instance with the resulting values
        Throws:
        java.lang.IllegalArgumentException - if the fraction is null
        java.lang.ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

      • multiplyBy

        public Fraction multiplyBy​(Fraction fraction)

        Multiplies the value of this fraction by another, returning the result in reduced form.

        Parameters:
        fraction - the fraction to multiply by, must not be null
        Returns:
        a Fraction instance with the resulting values
        Throws:
        java.lang.NullPointerException - if the fraction is null
        java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

      • divideBy

        public Fraction divideBy​(Fraction fraction)

        Divide the value of this fraction by another.

        Parameters:
        fraction - the fraction to divide by, must not be null
        Returns:
        a Fraction instance with the resulting values
        Throws:
        java.lang.NullPointerException - if the fraction is null
        java.lang.ArithmeticException - if the fraction to divide by is zero
        java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

      • equals

        public boolean equals​(java.lang.Object obj)

        Compares this fraction to another object to test if they are equal.

        .

        To be equal, both values must be equal. Thus 2/4 is not equal to 1/2.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the reference object with which to compare
        Returns:
        true if this object is equal

      • hashCode

        public int hashCode()

        Gets a hashCode for the fraction.

        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code value for this object

      • compareTo

        public int compareTo​(Fraction other)

        Compares this object to another based on size.

        Note: this class has a natural ordering that is inconsistent with equals, because, for example, equals treats 1/2 and 2/4 as different, whereas compareTo treats them as equal.

        Specified by:
        compareTo in interface java.lang.Comparable<Fraction>
        Parameters:
        other - the object to compare to
        Returns:
        -1 if this is less, 0 if equal, +1 if greater
        Throws:
        java.lang.ClassCastException - if the object is not a Fraction
        java.lang.NullPointerException - if the object is null

      • toString

        public java.lang.String toString()

        Gets the fraction as a String.

        The format used is 'numerator/denominator' always.

        Overrides:
        toString in class java.lang.Object
        Returns:
        a String form of the fraction

      • toProperString

        public java.lang.String toProperString()

        Gets the fraction as a proper String in the format X Y/Z.

        The format used in 'wholeNumber numerator/denominator'. If the whole number is zero it will be omitted. If the numerator is zero, only the whole number is returned.

        Returns:
        a String form of the fraction