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

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Fraction​(int numerator, int denominator)
      Constructs a Fraction instance with the 2 parts of a fraction Y/Z.

    • 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.
      private static int addAndCheck​(int x, int y)
      Add two integers, checking for overflow.
      private Fraction addSub​(Fraction fraction, boolean isAdd)
      Implement add and subtract using algorithm described in Knuth 4.5.1.
      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.
      private static int greatestCommonDivisor​(int u, int v)
      Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations.
      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.
      private static int mulAndCheck​(int x, int y)
      Multiply two integers, checking for overflow.
      private static int mulPosAndCheck​(int x, int y)
      Multiply two non-negative integers, checking for overflow.
      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.
      private static int subAndCheck​(int x, int y)
      Subtract two integers, checking for overflow.
      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

      • serialVersionUID

        private static final long serialVersionUID
        Required for serialization support. Lang version 2.0.
        See Also:
        Serializable, Constant Field Values

      • 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.

      • numerator

        private final int numerator
        The numerator number part of the fraction (the three in three sevenths).

      • denominator

        private final int denominator
        The denominator number part of the fraction (the seven in three sevenths).

      • hashCode

        private transient int hashCode
        Cached output hashCode (class is immutable).

      • toString

        private transient java.lang.String toString
        Cached output toString (class is immutable).

      • toProperString

        private transient java.lang.String toProperString
        Cached output toProperString (class is immutable).

    • Constructor Detail

      • Fraction

        private Fraction​(int numerator,
                 int denominator)

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

        Parameters:
        numerator - the numerator, for example the three in 'three sevenths'
        denominator - the denominator, for example the seven in 'three sevenths'

    • 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

      • greatestCommonDivisor

        private static int greatestCommonDivisor​(int u,
                                         int v)

        Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations. See Knuth 4.5.2 algorithm B. This algorithm is due to Josef Stein (1961).

        Parameters:
        u - a non-zero number
        v - a non-zero number
        Returns:
        the greatest common divisor, never zero

      • mulAndCheck

        private static int mulAndCheck​(int x,
                               int y)
        Multiply two integers, checking for overflow.
        Parameters:
        x - a factor
        y - a factor
        Returns:
        the product x*y
        Throws:
        java.lang.ArithmeticException - if the result can not be represented as an int

      • mulPosAndCheck

        private static int mulPosAndCheck​(int x,
                                  int y)
        Multiply two non-negative integers, checking for overflow.
        Parameters:
        x - a non-negative factor
        y - a non-negative factor
        Returns:
        the product x*y
        Throws:
        java.lang.ArithmeticException - if the result can not be represented as an int

      • addAndCheck

        private static int addAndCheck​(int x,
                               int y)
        Add two integers, checking for overflow.
        Parameters:
        x - an addend
        y - an addend
        Returns:
        the sum x+y
        Throws:
        java.lang.ArithmeticException - if the result can not be represented as an int

      • subAndCheck

        private static int subAndCheck​(int x,
                               int y)
        Subtract two integers, checking for overflow.
        Parameters:
        x - the minuend
        y - the subtrahend
        Returns:
        the difference x-y
        Throws:
        java.lang.ArithmeticException - if the result can not be represented as an int

      • 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.

      • addSub

        private Fraction addSub​(Fraction fraction,
                        boolean isAdd)
        Implement add and subtract using algorithm described in Knuth 4.5.1.
        Parameters:
        fraction - the fraction to subtract, must not be null
        isAdd - true to add, false to subtract
        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