Package org.apache.commons.lang.math

## Class Fraction

- java.lang.Object
- - java.lang.Number
  - - org.apache.commons.lang.math.Fraction

- All Implemented Interfaces:
    `Serializable`, `Comparable`

      public final class Fraction
      extends Number
      implements Comparable

  `Fraction` is a `Number` implementation that stores fractions accurately.

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

  Since:
    2.0
  Version:
    $Id: Fraction.java 1057072 2011-01-10 01:55:57Z niallp $
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Fraction` | `FOUR_FIFTHS` | `Fraction` representation of 4/5.
    `static Fraction` | `ONE` | `Fraction` representation of 1.
    `static Fraction` | `ONE_FIFTH` | `Fraction` representation of 1/5.
    `static Fraction` | `ONE_HALF` | `Fraction` representation of 1/2.
    `static Fraction` | `ONE_QUARTER` | `Fraction` representation of 1/4.
    `static Fraction` | `ONE_THIRD` | `Fraction` representation of 1/3.
    `static Fraction` | `THREE_FIFTHS` | `Fraction` representation of 3/5.
    `static Fraction` | `THREE_QUARTERS` | `Fraction` representation of 3/4.
    `static Fraction` | `TWO_FIFTHS` | `Fraction` representation of 2/5.
    `static Fraction` | `TWO_QUARTERS` | `Fraction` representation of 2/4.
    `static Fraction` | `TWO_THIRDS` | `Fraction` representation of 2/3.
    `static Fraction` | `ZERO` | `Fraction` representation of 0.

  - ### 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​(Object object)` | 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​(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​(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.
    `String` | `toProperString()` | Gets the fraction as a proper `String` in the format X Y/Z.
    `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:
        `ArithmeticException` - if the denomiator is `zero`

    - #### 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:
        `ArithmeticException` - if the denomiator is `zero`
        `ArithmeticException` - if the denominator is negative
        `ArithmeticException` - if the numerator is negative
        `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:
        `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:
        `ArithmeticException` - if `|value| > Integer.MAX_VALUE` or `value = NaN`
        `ArithmeticException` - if the calculated denominator is `zero`
        `ArithmeticException` - if the the algorithm does not converge

    - #### getFraction

          public static Fraction getFraction​(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:
        `IllegalArgumentException` - if the string is `null`
        `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 `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 `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 `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 `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:
        `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 >= 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:
        `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:
        `IllegalArgumentException` - if the fraction is `null`
        `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:
        `IllegalArgumentException` - if the fraction is `null`
        `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:
        `IllegalArgumentException` - if the fraction is `null`
        `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:
        `IllegalArgumentException` - if the fraction is `null`
        `ArithmeticException` - if the fraction to divide by is zero
        `ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

    - #### equals

          public boolean equals​(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 `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 `Object`
      Returns:
        a hash code value for this object

    - #### compareTo

          public int compareTo​(Object object)

      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 `Comparable`
      Parameters:
        `object` - the object to compare to
      Returns:
        -1 if this is less, 0 if equal, +1 if greater
      Throws:
        `ClassCastException` - if the object is not a `Fraction`
        `NullPointerException` - if the object is `null`

    - #### toString

          public String toString()

      Gets the fraction as a `String`.

      The format used is 'numerator/denominator' always.

      Overrides:
        `toString` in class `Object`
      Returns:
        a `String` form of the fraction

    - #### toProperString

          public 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 ommitted. If the numerator is zero, only the whole number is returned.

      Returns:
        a `String` form of the fraction