Fraction (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.math, class: Fraction

Package org.apache.commons.lang3.math

# Class Fraction

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

All Implemented Interfaces:
  `Serializable`, `Comparable<Fraction>`

public final class Fraction extends Number implements 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

- ## Field Summary

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

- ## Method Summary

  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(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 Details

  - ### 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 Details

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

  - ### 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 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:
      `ArithmeticException` - if the denominator is `zero`
      `ArithmeticException` - if the denominator is negative
      `ArithmeticException` - if the numerator is negative
      `ArithmeticException` - if the resulting numerator exceeds `Integer.MAX_VALUE`

  - ### 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:
      `NullPointerException` - if the string is `null`
      `NumberFormatException` - if the number format is invalid

  - ### 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`

  - ### 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

  - ### 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:
      `NullPointerException` - if the fraction is `null`
      `ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

  - ### 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 `Comparable<Fraction>`
    Parameters:
      `other` - 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`

  - ### 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:
      `NullPointerException` - 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`

  - ### 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`

  - ### 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

  - ### 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`

  - ### getDenominator

    public int getDenominator()
    Gets the denominator part of the fraction.
    Returns:
      the denominator fraction part

  - ### 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

  - ### 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

  - ### hashCode

    public int hashCode()
    Gets a hashCode for the fraction.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value for this object

  - ### 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

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

  - ### 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

  - ### 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:
      `NullPointerException` - if the fraction is `null`
      `ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

  - ### 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

  - ### 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`

  - ### 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

  - ### 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:
      `NullPointerException` - if the fraction is `null`
      `ArithmeticException` - if the resulting numerator or denominator cannot be represented in an `int`.

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

    Returns:
      a `String` form of the fraction

  - ### 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